最近折腾了一下 OpenCode V2 的子代理编排。
起初只是想给两个子代理指定模型：探索任务用 GLM，复杂任务用 GPT。后来顺手调研了社区的多 Agent 工作流，又看了 Superpowers，最后还把一份 Codex 的编排配置迁移到了 OpenCode。
绕了一圈，最终没装完整的编排框架，而是保留 OpenCode 原生子代理，加上几条明确的委派、复用和验证规则。
配置并不复杂，不过中间几个问题值得记下来。尤其是：能配置，不代表配置方式合理；能调用多个 Agent，也不代表每个任务都应该拆出去。
本文记录的是 2026 年 10 月这次配置过程，运行环境为 OpenCode V2 2.0.22。第三方项目的兼容情况会变化，不能把这次调研结果当成永久结论。
先弄清楚：子代理到底在用什么模型
OpenCode 内置了 explore 和 general 两个子代理。
explore 负责只读搜索和调查，general 负责研究以及多步骤任务。但这两个名字代表的是角色，不代表它们天然使用不同模型。
按照 V2 的规则，子代理没有配置模型时，会继承父会话模型。
也就是说，主代理用了 GPT，派出去查几个文件的 explore，可能也在用同一个 GPT。不会因为名字叫 Explore，就自动切到便宜模型。
我最初给两个角色分别指定模型，随后又补了审查和实施角色。最终配置是：
| 角色 | 模型 | 推理等级 | 用途 |
|---|---|---|---|
explore |
zai/glm-5.3-flash |
high |
只读探索 |
reviewer |
openai/gpt-6.1-sol |
high |
独立审查 |
general |
openai/gpt-6.1-sol |
high |
没有专职角色匹配时兜底 |
worker |
zai/glm-5.3-flash |
high |
明确委派的代码实施 |
这只是我的角色分配，不是什么经过基准测试得出的最优组合。
最初两个角色配置完成后，实际调用过子代理，并从会话记录核对了模型和推理等级。后面安装完整的四角色方案，验证的重点则是配置加载、角色提示词和权限，没有顺手编造一套“效率提升多少”的结论。
社区编排方案，主要是在解决两类问题
调研时看了 Superpowers、oh-my-opencode-slim，以及其他几个编排项目的文档和实现。
归纳下来，比较值得参考的是两种流程。
一种是 Superpowers 的任务级实施和评审：
另一种是主代理调度不同专家：
前者强调任务完成质量，后者强调分工和并行。都能借鉴，但不能只看项目介绍就直接安装。
这次核查时，Superpowers 和 slim 都已有 V2 适配；完整版 oh-my-openagent 仍有公开的 V2 加载和迁移问题。另外还有专门面向 V2 的编排器，但社区规模较小，暂时没有足够依据把它当成成熟的通用方案。
这里最有用的结论，其实不是选出了哪个插件，而是它们共同提醒的一件事：
并行调查和并行改代码，不是一回事。
两个代理分别调查互不相关的问题，通常比较容易划清边界。两个代理同时修改一个模块，就很容易互相踩文件。
按文件数量拆任务也不一定合理。一个业务修改可能横跨多个文件，强行拆给不同代理，只是把原本主代理需要理解的依赖，变成了几个代理之间的协调问题。
Superpowers 会不会给强模型加 DEBUFF？
这是我没有直接安装完整 Superpowers 的一个重要原因。
随着模型能力提高，社区开始出现一些反馈：原本用于补足模型规划和执行能力的流程，现在可能反过来增加负担。
比如，需求已经写得很明确，模型却仍然被要求重新 brainstorming；一个紧密关联的修改，被拆成多个任务、多个会话；简单修复也要经过文档、计划、实施、审查、复审。
流程确实完整了，但用户要解决的问题可能并没有更快完成。
Superpowers 的公开讨论中有重复规划、过度构建和成本增加的反馈，也有强模型任务中出现大量协调开销的报告。
不过，这里不能偷换概念。
耗时增加、会话增多、Token 消耗变大，是效率问题。它们不自动等于代码准确率下降。社区案例也不等于严格的对照实验。
所以我不会直接下结论说“Superpowers 对 GPT-6 一定是负收益”。但对我当前的需求，确实没有必要为了获得实施和评审纪律，把整套默认流程一起装进来。
我想保留的是独立审查、写入边界和真实验证，不是每次修改都重新走一遍需求讨论。
从 Codex 迁移过来，不能只替换工具名
接下来，我拿了一份给 Codex 使用的用户级编排配置，让代理转换成 OpenCode V2 的版本。
这一步不能机械照搬。角色名、会话续接方式、并发控制和沙箱能力，都不完全一样。
最终做了这些对应：
| Codex 方案 | 当前 OpenCode V2 方案 |
|---|---|
explorer |
内置 explore |
default |
内置 general |
reviewer、worker |
新增自定义子代理 |
| Agent TOML | Agent Markdown |
model_reasoning_effort |
model 中的 #high |
wait_agent |
前台 subagent 调用等待 |
followup_task |
传入原 sessionID 续接 |
还有两个不能装作等价的地方。
最多四个，是约定，不是硬上限
原参考配置有每会话并发数量设置，但这次核查的 V2 没有可直接对应的配置项。
我的处理是把“最多四个活动子代理”写进编排规则，要求主代理记录目标、控制派发数量。
这属于执行约定，不是运行时强制限制。
不能因为 AGENTS.md 写了“四个”，就宣称系统一定拦得住第五个。也不能为了看起来完整，往配置里塞一个猜出来的字段。
只读工具权限，不是操作系统沙箱
explore 和 reviewer 使用拒绝默认权限加只读工具白名单，禁止编辑、shell、Code Mode，以及其他没有放行的工具。
这样做的一个实际代价是，它们不能自己执行 git diff、测试或诊断命令。
这些证据由主代理提供，子代理再读取相关代码交叉核验。审查者不能把主代理的总结当成已经检查过的事实，也不能声称亲自运行了没有运行的测试。
这套限制仍然不是操作系统级只读沙箱。两者保护的层次不同，不能混着说。
我接受这些原生能力边界，没有为了补齐它们再引入一套调度系统。
Agent 配置应该放在哪里？
安装时还出现了一个很典型的问题。
代理最初把四个角色的模型放在 opencode.json，把提示词和权限放在各自 Markdown 文件里。
语法没有错，OpenCode 也能正常加载。但维护起来就不太对了：修改一个角色，需要同时看两个文件。
官方文档明明支持在 Markdown frontmatter 中指定 model，为什么还要人为拆开？
最后调整成了下面的结构：
~/.config/opencode/
├── AGENTS.md
├── opencode.json
└── agents/
├── explore.md
├── general.md
├── reviewer.md
└── worker.md
AGENTS.md 管主代理的编排规则。
四个 Agent 文件各自包含模型、描述、权限和提示词。opencode.json 不再保留这四个角色的模型覆盖，其他 Provider、MCP、插件配置不动。
以 worker.md 为例，文件开头是：
---
description: Implement features and fixes as an execution-focused subagent; use only when explicitly delegated.
mode: subagent
model: zai/glm-5.3-flash#high
permissions:
- action: subagent
resource: "*"
effect: deny
- action: question
resource: "*"
effect: deny
---
正文继续写角色提示词和输出契约。
这里也有个容易误解的地方：explore 和 general 已经是内置角色，为什么还要有对应 Markdown？
因为 OpenCode 允许使用相同 ID 覆盖内置 Agent。这不是再创建两个同名副本，而是给现有角色定制模型、提示词和权限。实际运行接口里，每个 ID 也只有一个实例。
如果只想指定模型，确实不需要重写提示词。这次还要加入明确的角色边界和报告格式，所以保留了同名覆盖。
另一个问题是语言。
原参考文件的子代理提示词都是英文，安装时却被全部翻译成了中文。我要求恢复了英文，只保留必要的 V2 适配。
不是说英文提示词一定比中文好，而是用户提供的生产快照，不应该被代理顺手“优化”。要求中文回复，也不意味着可以擅自翻译配置里的英文提示词。
当前流程怎么决定是否委派？
没有安装完整框架之后，主代理仍然负责判断任务是否需要拆出去。
已知位置的小修改、单一事实、即将修改的确切代码，由主代理直接处理。只有能明显减少主线程上下文负担，或者需要独立核验时，才使用子代理。
这也解释了安装过程中一个看似矛盾的现象：配好了 worker，但修改配置时为什么还是主代理自己做？
因为这就是一个已知位置的小型配置任务，参考文件也明确要求不要委派。
worker 的含义是：决定委派实施任务后，由它承担实施。 不是任何文件修改都必须经过它。
探索任务的门槛则更具体。位置未知、需要跨多个目录或命名方式检索、预计超过三轮独立搜索，而且主代理只需要结论和定位时，才适合交给 explore。
如果目标文件已经知道，主代理下一步就要修改它，再派一个代理把这个文件读一遍，通常没什么收益。
委托本身也要写清楚，至少包括目标、背景、范围、权限、禁止事项、成功标准和所需证据。不能只丢一句“帮我看看”。
返回格式统一为：
status: complete | blocked | failed
summary: ...
evidence: ...
gaps: ...
这样主代理拿到的是可点验的结果，而不是一大段“我已经完成了”的自述。
当前方案使用前台调用，需要并发时通过宿主实际提供的并行机制成组派发。等待期间不另开一堆工作，也不派“监工 Agent”轮询进度。四个子代理都不开放下级派生。
改错了，能不能让原子代理接着修？
可以。
“报告一次后停止”不代表子会话被销毁。OpenCode 的 subagent 支持传入之前返回的 sessionID，继续同一个子会话。
比如，一个 worker 已经实施完成，主代理检查后发现错误。目标和授权范围没有变化，原上下文也仍然有价值，就可以续接它：
{
"agent": "worker",
"description": "修复同一任务的验证错误",
"sessionID": "之前返回的子会话 ID",
"prompt": "继续原任务，目标和文件范围不变。根据以下实际错误证据修复，并重新执行相关验证。不得修改范围外文件。……",
"background": false
}
不需要每次发现错误，都让一个新代理重新读完整个任务。
但也不能无限复用。
目标改变、需要独立复核，或者原来的错误方案需要推倒重做时，应该新建 Agent。同一失败策略最多重试一次，避免带着同一套错误思路反复尝试。
审查也是类似的处理。
首次独立审查使用新上下文；修复影响了原来的审查结论，可以续接对应 reviewer，提供实际差异和新的验证证据。局部、机械的修复已经有针对性验证覆盖时，则由主代理核验，不必为了走流程再安排一轮完整复审。
所以当前流程不是固定流水线，而是按任务需要选择：
主代理直接处理"] A --> C["宽泛调查
explore"] A --> D["明确实施
worker"] A --> E["独立审查
reviewer"] A --> F["无专职角色匹配
general"] B --> G["主代理点验与最终验证"] C --> G D --> G E --> G F --> G
最后怎么确认配置真的生效？
这次没有把“文件写成功”当成安装完成。
静态检查先确认：
- JSON 和 Markdown frontmatter 能正确解析；
- 编排章节只有一个，章节外内容没变；
- 四个模型和
high配置正确； - 提示词、权限符合确认后的版本；
- Provider、密钥、MCP、插件和其他 Agent 没有被顺手改动。
然后再看运行服务：
opencode api get /api/info
opencode api get /api/agent
核对实际加载的角色、模型 variant、提示词和合并后的权限，同时检查用户级位置与当前会话位置的结果。
这轮修改中，服务进程没有变化，运行接口已经加载了新配置，因此没有重启共享服务。
但这只能说明这轮配置完成了热加载，不能推导出所有配置修改都不需要重启。API 里出现正确的模型，也不等于已经验证了完整业务任务、实际权限拒绝或多代理协作效果。
验证到哪一层，就说到哪一层。
回头看，这次真正留下来的东西很少：四个自包含的角色文件，一段主代理编排规则，以及几条不能含糊的能力边界。
我没有因此认定 Superpowers 不好，只是目前不需要把它整套装进来。主代理能直接做的小事就直接做；需要隔离探索上下文、并行调查或独立审查时，再把任务派出去。
折腾编排，最后还是要回到具体任务。配置了多少 Agent、会话列表有多热闹，都不是验收结果。