OpenCode Agent 是可以重复使用的助手配置，每个角色都能拥有自己的指令、模型偏好和工具权限。**主 Agent（primary agent）**负责你直接交互的主对话；**子代理（subagent）**则在子会话里处理更窄的任务，它既可以由主 Agent 委派，也可以由你直接调用。
这个区别比笼统地把每个角色叫作“AI 队友”更有用。它决定了对话在哪里进行、角色怎样被选中、能获得什么上下文，以及应该用哪些权限约束其工作。
本文示例以 2026 年 9 月 1 日的 OpenCode 1 官方文档为准。OpenCode 2 目前以单独的 beta 版本提供，使用不同的配置字段；本文后面会单独说明这条版本边界。
用一张表分清主 Agent 和子代理
OpenCode 官方的 Agents 文档定义了两种可由用户配置的角色。
OpenCode 1 内置两个用户可见的主 Agent：
- Build 是默认开发角色，拥有较广的工具权限。
- Plan 用于规划和分析；文件编辑和 Shell 命令默认需要询问批准。
它还内置三个用户可见的子代理：
- General 处理广泛研究和多步骤任务，权限允许时也可以修改文件。
- Explore 是只读的代码库研究角色。
- Scout 是只读的外部文档和依赖源码研究角色。
此外还有负责上下文压缩、标题和摘要等任务的隐藏系统 Agent。它们不是供用户日常选择的普通角色。
如果你还在判断 OpenCode 是否适合自己的执行环境，可以先看更上层的 OpenCode 云端工作区指南。本文下面只讨论 OpenCode 内部的 Agent 角色。
OpenCode 怎样调用不同角色
主 Agent 负责主对话。在 OpenCode 1 中，你可以按 Tab，或使用自定义的 switch_agent 快捷键，在主 Agent 之间切换。切换角色会改变后续工作的当前指令和权限，但这不等于创建了另一个独立项目。
子代理有两种启动方式：
- 自动委派。 主 Agent 会看到可用子代理及其描述，再通过 Task 工具把合适的任务交出去。
- 手动调用。 你可以在消息里直接点名，例如
@general 帮我找到这个函数在哪里定义。
委派任务会创建一个子会话。OpenCode 提供快捷键，让你从父会话进入子会话、在多个子会话间切换，再返回父会话。这样，子代理可以独立调查，不必把所有中间过程都塞进主对话，同时你仍然能进入子会话检查它做过什么。
description 是实际的调度信息，不只是装饰。“帮助处理代码”这样的描述太模糊，主 Agent 很难判断何时应该调用它。更有效的描述会同时写明触发条件和边界，例如：“审查当前 diff 的正确性和遗漏测试，不修改文件。”
怎样配置一个职责集中的子代理
OpenCode 1 支持在 opencode.json 或 Markdown 文件中定义 Agent。Markdown 通常更容易审查，因为配置和角色指令放在同一个文件里。全局 Agent 放在 ~/.config/opencode/agents/，项目专用 Agent 放在 .opencode/agents/。文件名就是 Agent 名称。
下面是一个适用于 OpenCode 1 的项目级 reviewer 子代理示例：
把它保存为 .opencode/agents/reviewer.md，再用一个边界清楚的请求调用：
这个简短定义中的四个选择承担了主要作用：
description告诉用户和主 Agent 什么时候适合使用这个角色。mode: subagent防止该配置成为主对话中可选的主角色。permission禁止编辑，并把 Shell 权限限制在几个只读 Git 命令上。- Markdown 正文 定义期望输出，让任务保持聚焦。
你也可以用 provider/model-id 格式设置 model。如果没有设置，子代理会继承调用它的主 Agent 所用模型。因此，Agent 配置和模型是两个不同选择：配置定义角色，模型为这个角色提供推理能力。
官方的 opencode agent create 命令可以通过交互流程生成 Markdown Agent。它会询问配置是全局还是项目专用，收集角色描述，生成 Prompt 和标识符，并让你选择权限。生成后仍要审查文件；自动生成不能替代权限检查。
权限才是真正的委派边界
Prompt 可以要求 Agent 不要编辑文件，权限则可以阻止编辑工具运行。两者都应该使用，但不能混为一谈。
在 OpenCode 1 中，权限有三种结果：
allow：不询问，直接运行；ask：暂停并等待用户批准；deny：阻止操作。
规则既可以针对一整类工具，也可以针对更窄的输入，例如具体 Shell 命令模式。多个模式同时匹配时，最后一个匹配规则生效。因此应先写范围最广的默认规则，再写更具体的例外。
主 Agent 还有一层独立的委派边界：permission.task。它控制模型可以自动调用哪些子代理。一个受限的编排 Agent 可以先禁止所有子代理，再只允许指定角色：
被禁止的角色会从 Task 工具描述里移除，因此模型不应该再尝试向它委派。在 OpenCode 1 中，这个限制不会阻止用户用 @ 手动点名一个仍然可见的子代理。同样，hidden: true 只会把子代理从自动补全中隐藏，并不是安全控制；只要 Task 权限允许，模型仍可能调用这个隐藏角色。
实用原则很简单：只开放任务真正需要的最小工具范围，单独限制自动委派，并分别测试一项应被允许和一项应被拒绝的操作。更完整的命令模式和审批说明可以参考 OpenCode 权限指南。
按任务选择主 Agent 或子代理
当一个角色需要负责与用户的对话和主要决策顺序时，使用主 Agent。当任务拥有明确输入、有限工具和可以返回给父会话检查的输出时，使用子代理。
任务很小、需要持续和用户来回沟通，或只有复制大部分主对话才能解释清楚时，不要委派。子代理会增加一层上下文边界和一份需要检查的结果。只有专业分工或并行确实能改善工作流时，这些额外成本才值得。
OpenCode 子代理不等于多 Agent 团队工作流
OpenCode 子代理是在 OpenCode 内部被调用的可复用角色，工作记录在子会话里。它不会自动建立拥有独立负责人、共享交付规则、合并权限或跨 Agent harness 协作的团队流程。
这些问题属于另一个层级。团队工作流可能让 Codex、Claude Code 和 OpenCode 分别运行在独立会话里，给每个会话明确的文件边界，再由审查角色整合结果。多 Agent 编码工作流指南讨论的是这种项目级协作。
两种模式可以同时存在。一个 OpenCode 会话可以在内部使用 Explore 子代理，而整个项目只把一个有边界的工作流分配给 OpenCode。需要把术语说清楚：
- OpenCode 主 Agent / 子代理角色描述同一个 Agent harness 内部的委派。
- 多 Agent 团队工作流描述多个独立工作会话或不同 harness 之间的职责和交接。
谨慎迁移 OpenCode 1 与 OpenCode 2 beta 配置
OpenCode 官方 V2 文档说明，这个 beta 版本未来会成为 OpenCode 2.0，目前仍在变化，并以 opencode2 和 OpenCode 1 并行运行。官方 V1 迁移指南说明，V2 可以读取受支持的 V1 配置和旧版 Agent Markdown，所以已有 V1 文件不会自动失效。不过，原生 V2 字段使用不同的 schema；当等价的 V1/V2 顶层字段同时存在时，原生 V2 配置优先。
本文前面的 reviewer 示例属于 OpenCode 1；V2 可能通过兼容路径读取它，但不能假定把字段机械改名后行为就完全相同。如果要把某个条目迁移为原生 V2，应完整转换该嵌套 Agent、Provider、Command 或 Model 条目，不要在同一个条目内部混写 V1/V2 格式。先确认自己运行的是哪个二进制文件，再按官方迁移文档和其中的“Verify your setup”清单逐项核验，并重新检查迁移后的权限。
这条版本边界变化很快，内置 Agent 和默认行为也可能不同。例如，2026 年 9 月 1 日的 V2 beta 文档没有把 Scout 列为内置子代理。
这对 Agent.Space 用户意味着什么
OpenCode 的主 Agent 和子代理展示了：同一个 Agent harness 可以把规划、执行、探索和审查拆成不同角色，但不需要把每个角色都当作不同模型或不同产品。因此，真正有用的评估问题是：哪个 harness 负责当前任务？每个角色背后运行什么模型？角色能访问什么？谁批准敏感操作？结果怎样返回主流程？
Agent.Space 并未声称会创建、同步或强制执行本文展示的 OpenCode 配置。判断这些行为时，应以对应版本的 OpenCode 官方文档和你的本地配置为准。
准备把这些角色、权限和交接问题用于真实任务时，可以打开 Agent.Space，先从一个能够端到端检查的小型工作流开始。