OpenCode 多 Agent 怎么配置更稳？我的判断：模型放用户级，7 个 Agent 放项目级
本文针对AI编程中单Agent包打天下的风险，提出OpenCode多Agent配置方案，通过职责与权限隔离实现稳定开发，适用于追求低成本、高复用性的团队协作场景。
一、问题背景：为什么我不建议一上来就用单 Agent 包打天下？
很多团队刚接入 AI 编程工具时，常见做法是：给一个 Agent 很大的权限，让它从需求分析、方案设计、代码实现、测试验证一路做完。
短期看，这种方式很爽；长期看，风险也很明显：
- 职责混杂：同一个 Agent 既做方案，又写代码，又自审，容易把错误判断带到后续步骤。
- 权限过大：如果主 Agent 能随意 edit、bash、websearch，一旦理解错需求，影响范围会比较大。
- 验证不独立：自己写的代码自己审，天然存在偏差。
- 成本不可控：如果为了偶尔读图，就让主模型一直使用视觉模型，可能不划算。
- 团队不可复用：如果每个人都靠口头 prompt，团队很难沉淀统一流程。
所以，我更倾向于把 OpenCode 配成“多 Agent 工作流”，而不是“万能 Agent”。
二、核心痛点：多 Agent 配置真正要解决什么？
这套方案不是为了炫技，而是解决三个实际问题。
1. 职责隔离
把开发流程拆成不同角色：
| Agent | 类型 | 职责 |
|---|---|---|
| orchestrator | primary | 拆解需求、路由任务、汇总结果、控制返工 |
| architect | subagent | 需求澄清、方案设计、接口划分、测试矩阵 |
| executor | subagent | 按方案实现、调试、运行验证命令 |
| reviewer | subagent | 读取 diff、运行验证、报告阻塞问题 |
| bulk | subagent | 变量重命名、样板代码、测试补齐等机械任务 |
| vision | subagent | 读取图片、UI 截图、设计稿、错误截图 |
| commenter | subagent | 补充代码注释和文档注释 |
核心思想是：让合适的模型做合适的事。
2. 权限隔离
不是每个 Agent 都应该能改代码，也不是每个 Agent 都应该能执行命令。
例如：
- orchestrator：只路由，不 edit，不 bash；
- architect：只读代码，不改文件，不执行命令；
- executor：可以 edit，但 bash 建议 ask；
- reviewer：只读 diff，bash 只允许 test / lint / typecheck / git diff 等验证命令；
- vision：只读图，不做架构判断，不写代码。
3. 成本控制
如果读图只是偶发需求，我不建议主 Agent 直接挂视觉模型。更合理的做法是：
- 主 Agent 使用纯文本模型做编排；
- 需要读图时，再委托 vision 子 Agent；
- vision 子 Agent 单独绑定支持图片输入的模型。
这样不会为了低频视觉能力，给高频编排任务长期增加成本。
三、不同方案对比：主模型到底要不要支持 vision？
这是很多人配置时最容易纠结的点。
方案 A：主模型直接支持 vision
也就是 orchestrator 本身就用视觉模型。你贴图后，图片直接进入 orchestrator 上下文。
适合：
- 高频处理 UI 截图；
- 高频看设计稿；
- 高频分析错误截图；
- 不想做 vision 子 Agent 委托。
优点是简单直接。
缺点是：编排任务本身并不总需要视觉能力，如果主 Agent 全程使用视觉模型，成本和模型选择都会被 vision 需求绑定。
方案 B：主模型不支持 vision，通过 vision 子 Agent 委托
本案例采用的是这个方案：
- orchestrator 使用纯文本
glm-5.2； - vision 子 Agent 使用
kimi-k2.6； - 需要读图时，由 orchestrator 调用 vision；
- vision 读取图片后返回结构化描述；
- orchestrator 再把描述交给 architect / executor / commenter。
链路大概是：
- 用户把图片放到项目目录或本地路径；
- 用户告诉 orchestrator：“看一下 xx.png”；
- orchestrator 通过 task 调用 vision；
- vision 用 read 读取图片；
- vision 返回结构化描述；
- orchestrator 根据描述继续派发任务。
我的判断是：
| 场景 | 更推荐 |
|---|---|
| 高频读图 | 主模型直接支持 vision |
| 低频读图 | vision 子 Agent 委托 |
| 主要是代码开发 | 主 Agent 保持纯文本，读图按需委托 |
| 主要是 UI / 设计稿分析 | 可以考虑主模型 vision |
本案例读图不是高频需求，所以选择方案 B。
四、为什么选择“用户级模型配置 + 项目级 Agent 文件”？
这是我认为最重要的工程决策。
OpenCode 配置分两层：
| 层级 | 路径 | 适合放什么 |
|---|---|---|
| 用户级 | ~/.config/opencode/opencode.json | provider、model、mcp、default_agent、API Key |
| 项目级 | 仓库根目录 opencode.json 或 .opencode/opencode.json | 与项目强绑定的配置 |
| 项目级 Agent | .opencode/agents/ | 团队共用的 Agent markdown 文件 |
两层同时存在时，OpenCode 会深度合并，规则是：项目级覆盖用户级。
所以我的建议是：
- 模型接入和 API Key 放用户级：避免真实 key 进仓库；
- Agent 文件放项目级：跟随代码库版本管理，团队成员 clone 后共享同一套编排规则。
推荐目录结构如下：
<code class="language-text">~/.config/opencode/
└── opencode.json 项目目录/
├── .opencode/
│ └── agents/
│ ├── orchestrator.md
│ ├── architect.md
│ ├── executor.md
│ ├── reviewer.md
│ ├── bulk.md
│ ├── vision.md
│ └── commenter.md
</code>
Y-3xo2p">这不是唯一标准，但原则很清楚：
通用模型接入放用户级，项目专属 Agent 放项目级。
五、模型配置要注意什么？尤其是视觉能力字段
以原文中的 ModelVerse 接入点为例，provider 关键字段包括：
字段 含义 name 展示名 npm SDK 包名，OpenAI 兼容接入点使用 @ai-sdk/openai-compatible options.apiKey 接入点密钥 options.baseURL OpenAI 兼容接口地址，示例为 https:// api.modelverse.cn/v1 models 声明可用模型
Agent 中如果写：
<code class="language-text">model: modelverse/glm-5.2
</code>
那么 glm-5.2 必须已经在 provider.modelverse.models 中声明，否则 OpenCode 启动或调用时可能报错。
视觉模型最容易漏的两个字段
如果模型要处理图片，原文强调这两个字段都不能少：
<code class="language-text">{ "<span>attachment</span>": true, "<span>modalities</span>": { "input": ["text", "image"], "output": ["text"] }
}
</code>
含义是：
字段 作用 漏配后果 modalities.input 包含 image 告诉 OpenCode 该模型支持图片输入 客户端可能直接拦截图片 attachment: true 告诉 OpenCode 该模型支持附件上传 附件链路可能断掉
但这里有一个前提：
这些字段只是让 OpenCode 放行，不代表模型和接入点本身真的支持视觉。
上线前应该通过接入点官方文档，或最小多模态请求验证模型确实能读图。
原文案例中：
- kimi-k2.6 和 glm-5v-turbo 配置了视觉能力；
- 实际 vision 子 Agent 使用 kimi-k2.6；
- glm-5v-turbo 作为备选视觉模型；
- 其余纯文本模型只需要声明 name。
六、Agent 文件怎么写？关键在 description、mode、model、permission
在 OpenCode 里，一个 Agent 通常是一份带 frontmatter 的 markdown 文件。frontmatter 控制 Agent 的身份、模型和权限，正文 prompt 控制行为边界。
常见字段：
字段 作用 description Agent 描述，也是 orchestrator 路由的重要依据 mode primary 表示主 Agent，subagent 表示子 Agent model 绑定模型，例如 modelverse/glm-5.2 permission 工具权限控制 hidden 是否隐藏，适合 vision 这类专用委托 Agent
我特别建议把 description 写清楚，最好包含“当需要……时使用”。因为 orchestrator 会依赖 description 判断应该把任务派给谁。
七、7 个 Agent 的配置思路
1. orchestrator：只编排，不写代码
定位：主 Agent，负责拆解需求、调用子 Agent、汇总结果、控制返工。
建议权限：
<code class="language-text">mode: primary
model: modelverse/glm-5.2
permission: read: allow glob: allow grep: allow edit: deny bash: deny webfetch: deny websearch: deny lsp: deny todowrite: allow question: allow task: '*': deny architect: allow executor: allow reviewer: allow bulk: allow vision: allow commenter: allow
</code>
关键点：orchestrator 不应该自己写代码，也不应该自己给最终技术方案。它的价值是拆、派、收、验。
2. architect：只做规划和架构
定位：子 Agent，负责需求澄清、方案设计、接口划分、数据流、测试矩阵和验收标准。
原文示例中使用 claude-opus-4-8，因为规划任务更依赖强推理和结构化输出。
权限建议：只读，禁 edit，禁 bash，禁联网。
3. executor：负责实现
定位：子 Agent，根据 architect 的方案完成代码修改。
原文示例中使用 glm-5.2。
权限建议：
- read / glob / grep：allow；
- edit：allow；
- bash：ask。
这样执行命令前会询问用户，比较适合团队场景。
4. reviewer：独立审查和验证
定位：子 Agent，读取 diff，运行验证命令，只报告阻塞性问题。
原文示例中使用 gpt-5.5，与 executor 不同源，目的是降低同源自审偏差。
bash 建议白名单：
<code class="language-text">bash: '*': deny 'git status': allow 'git diff*': allow 'git show*': allow 'git log*': allow 'npm test*': allow 'pnpm test*': allow 'yarn test*': allow 'go test*': allow 'pytest*': allow 'mvn test*': allow 'gradle test*': allow 'make test*': allow 'npm run lint*': allow 'npm run typecheck*': allow 'tsc*': allow
</code>
注意这里的原则：reviewer 可以验证，但不改代码。
5. bulk：处理低风险机械任务
适合变量重命名、样板代码、测试补齐等明确、机械、低风险任务。
权限建议：可 edit，但禁 bash。
遇到需要架构判断、业务判断或跨模块影响的问题，bulk 应该停止并交回 orchestrator。
6. vision：专门读图
定位：隐藏子 Agent，只负责读取图片并返回结构化描述。
原文示例中：
- mode: subagent；
- model: modelverse/kimi-k2.6；
- hidden: true；
- 只允许 read；
- 禁止 edit、bash、webfetch、websearch。
它不做架构判断，不写代码，不给验收结论，只把图片里的内容结构化表达出来。
7. commenter：只补注释，不改业务逻辑
定位：子 Agent，用于补充函数注释、类注释、复杂逻辑说明。
原文示例中使用 glm-5.1，因为注释类任务相对机械，可以用更便宜的模型。
权限建议：可 edit，但禁 bash 和联网。
八、权限配置怎么判断？我的经验是“默认收紧，按职责放开”
OpenCode permission 里常见动作有三个：
| 动作 | 含义 |
|---|---|
| allow | 直接放行 |
| ask | 执行前询问 |
| deny | 禁用 |
常见权限字段包括：
| 字段 | 控制内容 |
|---|---|
| read | 读文件 |
| glob | 按文件名模式找文件 |
| grep | 按内容搜索文件 |
| list | 列目录 |
| edit | 修改文件 |
| bash | 执行 shell 命令 |
| task | 调用子 Agent |
| webfetch | 抓网页 |
| websearch | 联网搜索 |
| lsp | LSP 查询 |
| todowrite | 写任务清单 |
| question | 执行中向用户提问 |
| external_directory | 访问项目目录外路径 |
| skill | 加载 skill |
| doom_loop | 循环保护 |
其中 task 和 bash 可以做白名单。规则是 last match wins，所以通常先写 '*': deny，再写具体允许项。
我的配置原则是：
- 主 Agent 不给 edit / bash；
- 规划 Agent 不给 edit / bash；
- 实现 Agent 给 edit，bash 用 ask；
- 审查 Agent 不给 edit，bash 只放验证命令；
- 视觉 Agent 只读图；
- 注释 Agent 只能改注释，不碰业务逻辑。
九、实际使用建议：不要一开始就全量推广
如果团队要采用这套方案，我建议按下面顺序推进。
第一步：先在低风险项目试点
不要直接放到核心仓库。先找一个低风险项目，验证：
- provider 是否能正常调用；
- 模型 ID 是否匹配；
- Agent 路由是否准确；
- reviewer 是否能跑验证命令；
- vision 是否能正常读图；
- API Key 是否没有进入仓库。
第二步：补齐项目验证命令
多 Agent 流程里，reviewer 的价值依赖可执行验证命令。
如果项目没有 test、lint、typecheck，reviewer 的验证闭环会变弱。
第三步：把 description 写具体
例如不要只写“负责审查”，而要写：
当需要读取 diff、运行验证命令、发现阻塞问题或判断是否返工时使用。
越具体，orchestrator 越容易路由准确。
第四步：控制 bash 权限
bash 是高风险工具。我的建议是：
- executor：bash ask；
- reviewer：bash 白名单；
- orchestrator / architect / vision / commenter：默认禁 bash。
第五步：视觉能力上线前单独验证
不要只看配置字段。attachment 和 modalities 只是客户端放行，最终还要看模型和接入点是否真实支持图片输入。
十、实测验证：HTML 五子棋游戏如何跑通链路？
原文用一个 HTML 五子棋游戏验证了完整流程。这个案例不是客户案例，也不是性能评测，而是一个功能闭环演示。
流程如下：
- 用户对 orchestrator 提需求：“做一个 HTML 五子棋游戏，双人轮流落子，判断胜负”。
- orchestrator 拆解需求，调用 architect。
- architect 输出棋盘数据结构、胜负判定逻辑和交互流程。
- orchestrator 派 executor 实现
index.html和游戏逻辑。 - executor 修改完成后，orchestrator 调 reviewer。
- reviewer 读取 diff、运行验证命令，报告阻塞问题或放行。
- 如需注释，再调用 commenter。
- 最终五子棋可以运行，支持双人轮流落子并判断胜负。
orchestrator 收到需求，开始拆解
architect 给出棋盘数据结构、胜负判定、交互逻辑的方案
executor 按 architect 方案落地 index.html 和游戏逻辑
executor 按 architect 方案落地 index.html 和游戏逻辑
reviewer 读 diff、跑验证，报告阻塞性问题或放行
reviewer 读 diff、跑验证，报告阻塞性问题或放行
五子棋跑起来，双人轮流落子，能判胜负
这个验证说明链路是能跑通的：orchestrator 全程不碰代码，只负责拆、派、收、验；architect 出方案，executor 落地，reviewer 把关，commenter 补注释。
十一、适合 / 不适合场景
适合采用这套方案的场景
- 团队希望标准化 AI 编程流程；
- 项目需要多人共享 Agent 编排规则；
- 开发任务包含方案设计、实现、审查、注释、读图等不同工作；
- 希望通过权限隔离降低误改代码、误执行命令的风险；
- 读图是偶发需求，不希望主 Agent 全程使用视觉模型；
- 项目有 test、lint、typecheck 等可验证命令。
不太适合的场景
- 只是一次性小脚本，单 Agent 足够；
- 团队还没确定模型接入点和 API Key 管理方式；
- 项目没有任何自动化验证命令；
- 高频视觉任务占主导，主模型直接支持 vision 可能更简单；
- 团队不愿维护 Agent markdown 文件和权限策略。
十二、上线前检查清单
| 检查项 | 判断标准 |
|---|---|
| provider 可用 | API Key、baseURL、SDK 包名正确 |
| 模型 ID 可用 | Agent 引用的模型都已在 provider models 中声明 |
| 视觉模型可用 | modalities.input 包含 image，attachment: true，且接入点实际支持图片输入 |
| Agent 路由清晰 | 每个 description 都写明“什么时候使用” |
| 权限最小化 | 主 Agent 禁 edit/bash，reviewer 禁 edit |
| 验证命令存在 | 项目有 test、lint、typecheck 或等效验证命令 |
| API Key 安全 | 真实密钥不进入仓库 |
| 实测闭环完成 | 至少跑通一次需求 → 方案 → 实现 → 审查 → 运行 |
十三、FAQ
Q1：为什么 orchestrator 不直接写代码？
因为 orchestrator 的核心价值是编排。如果它既写代码又审查，很容易出现权限过大和自我验证偏差。更稳妥的方式是让 executor 写代码，再由 reviewer 独立验证。
Q2：Agent 为什么要用 markdown 文件？
因为 markdown 易读、易改、易进 Git review。相比把 prompt 塞进 JSON，markdown 更适合团队维护职责边界和行为约束。
Q3：为什么 reviewer 要和 executor 使用不同模型？
原文的设计意图是降低同源自审偏差。executor 使用 glm-5.2，reviewer 使用 gpt-5.5，通过不同模型做交叉验证。但这只是设计原则，不代表这些模型是唯一选择。
Q4：配置了 modalities 和 attachment 就一定能读图吗？
不一定。这两个字段只是让 OpenCode 客户端放行图片输入。模型和接入点本身仍然必须真实支持视觉能力。上线前要用官方文档或最小多模态请求验证。
Q5：低频读图为什么推荐 vision 子 Agent？
因为主 Agent 的主要工作是拆解和路由，通常不需要视觉能力。把读图交给 vision 子 Agent，可以让主模型保持纯文本，只在需要时调用视觉模型。
Q6：这套 7 Agent 配置能直接复制到任何项目吗？
可以作为模板，但不建议无脑复制。需要根据团队实际模型、OpenCode 版本、接入点能力、验证命令和权限要求调整，尤其不能把真实 API Key 提交进仓库。
Q7：skill 在这里怎么用？
原文只提到 skill 是 OpenCode permission 中的一个权限字段，用于控制 Agent 是否可以加载 skill，但没有提供具体 skill 配置样例。因此这里不扩展虚构用法。实际使用时应以团队的 OpenCode 版本和官方文档为准。
总结建议
自己临时写点代码，单 Agent 完全够用——就像一个人在家炒蛋炒饭，洗切炒尝一条龙，自在得很。
但如果是团队想把 AI 编程正经跑起来，就不能再搞“私房菜”模式了，得搭个正儿八经的后厨。我的配置思路是：模型跟着厨师走（用户级），Agent 跟着菜单走（项目级）。
具体分工上，你可以这么理解：
- orchestrator 当调度员，只喊号、不动手；
- architect 负责画菜谱、定方案；
- executor 是掌勺大厨，专门掂锅落地；
- reviewer 当试菜员，每道菜出锅前必须过嘴；
- vision 像临时请来的鉴图师，有图要认时才喊过来；
- bulk 和 commenter 就是后厨小弟，专职批量改注释这类不用动脑的杂活。
所以你看，这套东西要解决的压根不是“AI 能不能写代码”——这早就不是问题了。它真正回答的是工程化的事：后厨一忙起来，怎么做到不抢灶、不串味、炒砸锅了能追责，而且明天换班，出品还是一个味。