更新时间：2026-09-01 GMT+08:00

在OpenCode配置代理

在日常开发过程中，开发人员经常需要处理各种任务和工作流程，但现有的工具和助手往往无法满足所有需求，导致效率低下。例如，在处理复杂的数据处理任务时，现有的工具可能无法提供足够的支持，导致开发人员需要手动编写大量代码，耗时且容易出错。如何使用AI助手提高开发效率？

本文介绍OpenCode的代理机制，包括内置代理的功能和使用方式，以及如何创建自定义代理。代理是专门的AI助手，可以针对特定任务和工作流程配置，具备不同的工具权限和能力范围，让您在不同场景下获得最合适的辅助。通过合理配置和使用OpenCode的代理，开发人员可以显著提升工作效率，简化复杂任务的处理流程。

注意事项

使用OpenCode时可能出现风险，详情请参见OpenCode风险说明及安全建议。

前提条件

已在Notebook中安装配置OpenCode。

什么是代理

代理是OpenCode中具有特定角色和权限的AI助手。每个代理拥有不同的工具访问权限，适用于不同的工作场景。您可以在会话期间切换代理，或使用@提及来调用子代理。

OpenCode中有两种类型的代理：主代理和子代理。

表1 OpenCode代理类型说明
类型	说明	调用方式
主代理	您直接交互的主要助手，处理主要对话。OpenCode内置了两个主代理：Build和Plan，详情参见内置主代理。	按Tab键或配置的switch_agent快捷键循环切换。
子代理	主代理可调用来执行特定任务的专业助手。OpenCode内置了两个子代理：General和Explore，详情参见内置子代理。	由主代理自动调用，或在消息中@提及手动调用。

内置主代理

OpenCode内置了两个主代理：Build和Plan。如果您需要让AI直接修改代码和执行命令，使用Build代理；如果您只想让AI分析代码和提供建议，而不希望它修改任何文件，使用Plan代理。

表2 主代理说明
代理名称	定位	工具权限	适用场景
Build	启用了所有工具的默认主代理。	启用所有工具（文件操作、系统命令等）。	需要完全访问权限的开发工作：编写代码、修改文件、执行命令。
Plan	专为规划和分析设计的受限代理。	受限（file edits和bash默认设置为ask）。	分析代码、建议更改、创建计划，不对代码库进行实际修改。

图1 主代理-Build

图2 主代理-Plan

内置子代理

OpenCode内置了两个子代理：General和Explore。

表3 子代理说明
代理名称	定位	工具权限	适用场景
General	用于研究复杂问题和执行多步骤任务的通用代理。	完整工具访问权限（todo除外），可修改文件。	研究复杂问题、执行多步骤任务、并行运行多个工作单元。
Explore	用于探索代码库的快速只读代理。	无法修改文件。	按模式查找文件、搜索代码关键字、回答有关代码库的问题。

图3 使用@提及调用子代理

使用OpenCode内置代理

切换主代理：在会话期间按Tab键循环切换主代理（Build↔Plan）。
调用子代理：
- 主代理会根据任务描述自动调用子代理。
- 在消息中使用@提及手动调用，例如：
```
@general 你这个子代理是用来干嘛的
```
图4 @提及示例

在OpenCode创建自定义代理

在OpenCode聊天框中输入创建指令，描述代理的名称和行为。示例如下：
```
给我创建一个名为repeater的主代理，要求不管我发送什么，他都复述我的话
```
图5 自定义代理创建成功
在“ModelArts Launcher”页面的“AI Agent”区域，单击“OpenCode”，重新打开一个OpenCode，使新代理生效。
图6 打开OpenCode
按Tab键切换到新创建的代理（本示例为Repeater），开始对话。
图7 切换到新代理

如下图所示，如果代理行为与定义的规则一致，表明代理配置成功。

图8 使用新代理