如果你想在 OpenCode 里配置一套可复用的多 Agent 项目开发流程推荐采用下面这套结构模型配置放用户级~/.config/opencode/opencode.json适合放 provider、model、MCP、default_agent 和 API Key。Agent 文件放项目级.opencode/agents/适合进 Git团队共享和 review。主 Agent 只做编排orchestrator 负责拆解、路由、汇总和验收判断不直接写代码。子 Agent 分工执行architect 做方案executor 写代码reviewer 审查验证bulk 做机械修改vision 读图commenter 补注释。视觉能力低频使用时走委托主模型保持纯文本只有需要读图时才调用 vision 子 Agent。这套方案的核心是问题拆解 → 子 Agent 分工 → 权限隔离 → reviewer 验证闭环。一、场景背景单 Agent 做项目开发时经常会遇到几个问题职责混乱同一个 Agent 同时做需求分析、方案设计、代码实现和自我审查。权限过大Agent 既能改文件又能执行 bash还能联网误操作风险较高。自审偏差实现和审查由同一个模型完成容易漏掉自己生成代码里的问题。视觉成本难控偶尔需要读截图或设计稿但如果主 Agent 一直用视觉模型成本和模型选择都会被绑定。团队难复用每个人临时写 prompt流程无法标准化也不方便 code review。所以更工程化的做法是把开发流程拆成多个职责清晰的 Agent并用权限配置限制每个 Agent 能做什么。本文使用 7 个 AgentAgent类型职责示例模型权限原则orchestratorprimary需求拆解、任务路由、结果汇总、验收判断glm-5.2只读和调用子 Agent禁止 edit/bash/联网architectsubagent需求澄清、方案设计、接口划分、测试矩阵claude-opus-4-8只读不改代码executorsubagent按方案实现、调试、运行验证命令glm-5.2可 editbash 需确认reviewersubagent读 diff、运行验证、报告阻塞问题gpt-5.5只读bash 白名单限验证命令bulksubagent变量重命名、样板代码、测试补齐等机械任务glm-5.2可 edit禁 bashvisionsubagent读取截图、设计稿、错误截图、代码图片kimi-k2.6hidden只读图不做技术决策commentersubagent补充代码注释和文档注释glm-5.1可 edit禁 bash/联网二、技术方案2.1 推荐目录结构OpenCode 配置分两层用户级和项目级。推荐结构如下~/.config/opencode/ └── opencode.json 项目目录/ ├── .opencode/ │ └── agents/ │ ├── orchestrator.md │ ├── architect.md │ ├── executor.md │ ├── reviewer.md │ ├── bulk.md │ ├── vision.md │ └── commenter.md两层配置的建议分工层级路径放什么原因用户级~/.config/opencode/opencode.jsonprovider、model、MCP、API Key、default_agent跨项目复用避免密钥进仓库项目级配置opencode.json或.opencode/opencode.json与项目强绑定的配置团队共享项目级 Agent.opencode/agents/Agent markdown 文件便于 Git 管理和 review当用户级和项目级同时存在时OpenCode 会做深度合并同名字段以项目级为准。也就是说团队强约束放项目级个人密钥和偏好放用户级。2.2 配置 provider 和 model以原文中的 ModelVerse 接入点为例OpenAI 兼容接入点通常需要配置name展示名。npmSDK 包名OpenAI 兼容接入点使用ai-sdk/openai-compatible。options.apiKey接入点密钥。options.baseURL接口地址示例为https://api.modelverse.cn/v1。models模型声明Agent 中引用的模型 ID 必须提前声明。示例配置如下真实 API Key 不要提交进仓库{ $schema: https://opencode.ai/config.json, default_agent: orchestrator, mcp: { playwright: { command: [npx, -y, playwright/mcplatest], enabled: true, type: local } }, provider: { modelverse: { name: ModelVerse, npm: ai-sdk/openai-compatible, options: { apiKey: your-modelverse-api-key, baseURL: https://api.modelverse.cn/v1 }, models: { glm-5.2: { name: GLM-5.2 }, glm-5.1: { name: GLM-5.1 }, claude-opus-4-8: { name: Claude Opus 4.8 }, gpt-5.5: { name: GPT-5.5 }, kimi-k2.6: { name: KiMi-2.6, attachment: true, tool_call: true, temperature: true, modalities: { input: [text, image, pdf], output: [text] }, family: kimi, limit: { context: 128000, output: 16000 } }, glm-5v-turbo: { name: GLM-5V-Turbo, attachment: true, tool_call: true, temperature: true, modalities: { input: [text, image], output: [text] }, family: glm, limit: { context: 128000, output: 8192 } } } } } }这里有一个常见坑如果 Agent 中写了model: modelverse/glm-5.2那么glm-5.2必须存在于provider.modelverse.models中否则 OpenCode 启动或调用时可能直接报错。2.3 视觉模型配置modalities 和 attachment 必须同时声明如果某个模型需要处理图片必须关注两个字段字段作用漏配后果modalities.input包含image告诉 OpenCode 该模型支持图片输入客户端可能直接拦截图片输入提示模型不支持 image inputattachment: true告诉 OpenCode 该模型支持附件上传附件链路可能无法工作但要注意这两个字段只是让 OpenCode 客户端放行并不代表模型服务端一定支持视觉能力。模型和接入点本身也必须真实支持图片输入。上线前建议用官方文档或最小多模态请求验证。2.4 配置 Agent一个 Agent 就是一份 Markdown 文件在 OpenCode 中一个 Agent 通常是一份带 frontmatter 的 Markdown 文件。frontmatter 负责声明descriptionAgent 描述也是 orchestrator 路由的重要依据。modeprimary表示主 Agentsubagent表示子 Agent。model绑定模型如modelverse/glm-5.2。permission工具权限。hidden是否隐藏适合 vision 这种只希望被委托调用的 Agent。description很关键建议写清楚“当需要什么时使用”。如果描述太模糊orchestrator 的任务路由就容易出错。2.5 主 Agentorchestratororchestrator 是唯一主 Agent只做编排不直接写代码。--- description: 主编排。拆解需求、调用规划 Agent、派发实现与审查任务、控制返工与验收。默认不直接修改代码。 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 --- 你是编排者职责严格限定为需求拆解、任务路由、汇总子 Agent 结果、控制返工与验收。 绝对禁止 - 禁止自行产出代码实现、补丁、命令脚本。 - 禁止自行产出审查结论或最终技术方案。 - 禁止自行回答本应由子 Agent 完成的工作。 - 禁止编辑文件、执行 bash、联网搜索。 你必须做且只做以下动作 1. 读取需求与上下文明确目标、边界、验收标准和风险等级。 2. 复杂任务或者目标不够清晰的任务调用 architect。 3. 方案明确后调用 executor 实现。 4. 低风险机械任务调用 bulk。 5. 每次代码修改后调用 reviewer 审查和验证。 6. 若验证失败返回 executor 修复不要自己改。 7. 只根据 reviewer 的客观验证结果和风险等级做验收判断。2.6 子 Agentarchitect / executor / reviewer / bulk / vision / commenterarchitect方案设计--- description: 规划与架构。当需要需求澄清、方案设计、接口划分、数据流设计、测试矩阵或验收标准时使用。只读代码库产出决策完整的方案不修改代码。 mode: subagent model: modelverse/claude-opus-4-8 permission: read: allow glob: allow grep: allow edit: deny bash: deny webfetch: deny websearch: deny --- 你负责规划与架构。先理解相关代码和约束再输出决策完整的方案。 方案必须包括模块划分、接口变化、数据流、错误处理边界、测试矩阵和验收标准。 不写实现代码不修改文件。executor代码实现--- description: 实现与执行。当需要跨文件修改、调试、构建、运行测试或修复返工时使用。根据既定方案完成代码修改运行项目规定的验证命令。 mode: subagent model: modelverse/glm-5.2 permission: read: allow glob: allow grep: allow edit: allow bash: ask --- 你负责按方案实现。修改前先确认影响范围修改后运行项目规定的验证命令。 返回内容必须包括修改摘要、影响文件、运行命令、测试结果和未解决风险。reviewer审查验证--- description: 审查与验证。当需要读取 diff、运行验证命令、发现阻塞问题或判断是否返工时使用。只读 diff运行项目规定的验证命令只报告阻塞性问题不修改代码。 mode: subagent model: modelverse/gpt-5.5 permission: read: allow glob: allow grep: allow edit: deny 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 --- 你负责在独立上下文中审查代码。只报告阻塞性问题。 必须读取 diff并尽可能运行项目声明的验证命令。 不修改代码不提出无关风格建议。 返回内容必须包括验证命令、执行结果、阻塞问题、是否建议返工。bulk低风险批量修改--- description: 当需要变量重命名、样板代码、测试补齐等低风险机械任务时使用。处理明确、机械性的修改遇复杂问题停止并交回编排者。 mode: subagent model: modelverse/glm-5.2 permission: read: allow glob: allow grep: allow edit: allow bash: deny --- 你只处理明确、低风险、机械性的修改。 遇到需要架构判断、业务判断或跨模块影响的问题必须停止并交回编排者。 你的修改结果必须进入 reviewer 验证不能直接合并。vision视觉读图--- description: 视觉读图。当需要读取图片内容、分析 UI 截图、比对设计稿或提取图片中的文字/代码/结构信息时使用。只读图并返回结构化描述不做架构判断或代码实现。 mode: subagent model: modelverse/kimi-k2.6 hidden: true permission: read: allow glob: deny grep: deny edit: deny bash: deny webfetch: deny websearch: deny --- 你是专用的视觉读图 Agent职责严格限定为读取图片内容并返回结构化描述。 绝对禁止 - 禁止产出代码实现、架构方案或技术决策。 - 禁止产出审查结论或验收判断。 - 禁止修改文件、执行命令或联网搜索。 - 禁止对图片内容进行推测性补充。 你必须做且只做以下动作 - 读取用户提供的图片。 - 准确描述图片中的可见内容。 - 以结构化格式返回便于编排者分发给其他 Agent。 - 若图片模糊、不完整或无法识别明确说明限制不要猜测。commenter代码注释--- description: 代码注释。当需要为代码补充或完善注释、文档注释、函数说明时使用。只加注释不改业务逻辑不执行命令。 mode: subagent model: modelverse/glm-5.1 permission: read: allow glob: allow grep: allow edit: allow bash: deny webfetch: deny websearch: deny --- 你是专用的代码注释 Agent职责严格限定为为代码补充和完善注释不改业务逻辑。 绝对禁止 - 禁止修改函数签名、业务逻辑、控制流、数据结构。 - 禁止执行命令、联网搜索。 - 禁止产出架构方案或审查结论。 你必须做且只做以下动作 - 读取目标代码理解其功能与边界。 - 为函数、类、复杂逻辑补充注释。 - 优先使用项目已有注释风格。 - 不为显而易见的代码加冗余注释。 - 修改结果必须进入 reviewer 验证。三、核心指标这套多 Agent 配置不是看“Agent 数量多不多”而是看下面几个工程指标是否达标。3.1 权限隔离是否清晰关键检查项orchestrator 是否禁止edit和bash。architect 是否只读。executor 是否可写但 bash 需要确认。reviewer 是否禁止改代码只允许运行验证命令。vision 是否只负责读图不参与架构和实现。3.2 路由是否稳定路由稳定性主要依赖description。建议每个 Agent 的 description 都写成类似当需要 xxx 时使用。负责 xxx不负责 xxx。否则 orchestrator 可能会把实现任务派给 architect或者把架构判断派给 bulk。3.3 验证闭环是否成立至少要形成这个闭环需求 → architect 出方案 → executor 实现 → reviewer 读 diff 和运行验证 → orchestrator 汇总验收如果项目没有测试、lint、typecheck 或类似验证命令reviewer 的价值会下降。3.4 视觉能力是否按需使用主模型是否需要支持 vision取决于读图频率方案适合场景优点代价主模型直接支持 vision高频截图、设计稿、图片输入任务简单直接主 Agent 长期绑定视觉模型成本和模型选择受影响vision 子 Agent 委托低频读图主要是文本开发任务主 Agent 可用纯文本模型按需读图多一层委托需要配置正确本文采用第二种方案orchestrator 使用纯文本glm-5.2vision 使用kimi-k2.6。四、实测验证用 HTML 五子棋跑通链路原文使用一个 HTML 五子棋游戏验证了整套多 Agent 流程。需求是做一个 HTML 五子棋游戏双人轮流落子判断胜负。执行链路如下用户把需求发给 orchestrator。orchestrator 拆解需求调用 architect。architect 输出棋盘数据结构、胜负判定逻辑、交互流程和验收标准。orchestrator 派 executor 实现index.html和游戏逻辑。executor 修改完成后orchestrator 调 reviewer。reviewer 读取 diff运行可用验证命令报告阻塞问题或放行。如果需要补注释再调用 commenter。最终五子棋可以运行支持双人轮流落子和胜负判断。orchestrator 收到需求开始拆解architect 给出棋盘数据结构、胜负判定、交互逻辑的方案executor 按 architect 方案落地 index.html 和游戏逻辑reviewer 读 diff、跑验证报告阻塞性问题或放行五子棋跑起来双人轮流落子能判胜负这个实测的价值不在于五子棋本身而在于验证了这条链路问题单 Agent 职责混杂、权限过大、验证不独立 解决方案7 个 Agent 分工 权限隔离 reviewer 验证 验证用 HTML 五子棋跑通需求、方案、实现、审查和运行结果五、适用 / 不适用场景5.1 适合使用这套方案的场景团队希望标准化 AI 编程流程而不是每个人随意 prompt。项目需要共享 Agent 编排规则。开发任务经常包含需求澄清、方案设计、代码实现、审查验证、注释等环节。希望通过权限隔离降低误改代码、误执行命令的风险。读图是低频需求但偶尔需要分析截图、设计稿、错误截图。希望不同模型承担不同任务降低同源自审偏差。5.2 不适合或不建议直接使用的场景只是一次性小脚本单 Agent 就够。团队还没有明确模型接入点和 API Key 管理方式。项目没有任何测试、lint、typecheck 或验证命令reviewer 闭环较弱。高频视觉任务占主导此时主 Agent 直接使用视觉模型可能更简单。不愿意维护 Agent Markdown 和权限策略只想快速试验。六、常见坑6.1 把真实 API Key 提交进仓库模型配置如果放项目级一定要注意密钥泄露风险。更稳妥的方式是把含 API Key 的 provider 配置放在用户级~/.config/opencode/opencode.json6.2 Agent 引用的模型没有在 provider 中声明例如 Agent 中写model: modelverse/gpt-5.5但 provider models 里没有gpt-5.5就可能启动或调用失败。6.3 视觉模型漏配 attachment 或 modalities需要读图的模型必须同时满足{ attachment: true, modalities: { input: [text, image], output: [text] } }只配其中一个不够。6.4 orchestrator 权限过大如果 orchestrator 既能 edit 又能 bash它很容易绕过子 Agent 分工直接实现或执行命令。这样多 Agent 编排就失去意义。6.5 reviewer 没有验证命令reviewer 最好至少能运行git diffnpm test/pnpm testnpm run lintnpm run typecheckpytestgo testmvn test具体命令按项目技术栈调整。七、FAQQ1为什么 orchestrator 不直接写代码因为 orchestrator 的职责是编排。如果它同时负责方案、实现和审查会导致权限过大和自审偏差。更稳妥的做法是executor 写代码reviewer 独立验证orchestrator 只汇总和判断是否返工。Q2为什么 Agent 要用 Markdown 文件Markdown 易读、易改、易进 Git review。相比把 prompt 塞进 JSONMarkdown 更适合团队维护职责说明、行为约束和权限边界。Q3为什么 reviewer 要用和 executor 不同的模型原文设计思路是降低同源自审偏差。executor 使用glm-5.2reviewer 使用gpt-5.5。这不是唯一选择核心原则是实现和审查尽量分离。Q4配置了modalities.input和attachment就一定能读图吗不一定。这两个字段只是让 OpenCode 客户端放行图片输入。模型和接入点服务端仍然必须真实支持视觉能力。上线前应查官方文档或用最小多模态请求验证。Q5低频读图为什么推荐 vision 子 Agent因为主 Agent 的大部分工作是拆解、路由和汇总并不需要视觉能力。用 vision 子 Agent 可以让主模型保持纯文本只在需要时调用视觉模型。Q6这套 7 Agent 配置可以直接复制到任何项目吗可以作为模板但不建议无脑复制。你需要根据实际 OpenCode 版本、模型接入点、模型 ID、权限要求和项目验证命令做调整尤其不要提交真实 API Key。Q7skill 在这里怎么用原文只提到skill是 permission 字段之一用于控制 Agent 是否可以加载 skill但没有提供具体 skill 配置样例。因此本文不扩展虚构用法。九、参考链接OpenCode 配置 schema 示例https://opencode.ai/config.json示例 ModelVerse baseURLhttps://api.modelverse.cn/v1
报错？（100%复现的5类格式陷阱+自动修复prompt模板）)
