# OpenCode 多 Agent 怎么配置更稳？我的判断：模型放用户级，7 个 Agent 放项目级
> 作者/来源: admin
> 发布时间: 2026-08-13T10:14:15.896Z
> 分类: AI专区
> 标签: OpenCode, AI编程, 多Agent, 视觉模型, 成本控制
> 原文链接: http://117.50.162.249:3000/yun/articles/2689
---
## 一、问题背景：为什么我不建议一上来就用单 Agent 包打天下？
很多团队刚接入 AI 编程工具时，常见做法是：给一个 Agent 很大的权限，让它从需求分析、方案设计、代码实现、测试验证一路做完。
短期看，这种方式很爽；长期看，风险也很明显：
1. **职责混杂**：同一个 Agent 既做方案，又写代码，又自审，容易把错误判断带到后续步骤。
2. **权限过大**：如果主 Agent 能随意 edit、bash、websearch，一旦理解错需求，影响范围会比较大。
3. **验证不独立**：自己写的代码自己审，天然存在偏差。
4. **成本不可控**：如果为了偶尔读图，就让主模型一直使用视觉模型，可能不划算。
5. **团队不可复用**：如果每个人都靠口头 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。
链路大概是：
1. 用户把图片放到项目目录或本地路径；
2. 用户告诉 orchestrator：“看一下 xx.png”；
3. orchestrator 通过 task 调用 vision；
4. vision 用 read 读取图片；
5. vision 返回结构化描述；
6. 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 后共享同一套编排规则。
推荐目录结构如下：
```
~/.config/opencode/
└── opencode.json 项目目录/
├── .opencode/
│ └── agents/
│ ├── orchestrator.md
│ ├── architect.md
│ ├── executor.md
│ ├── reviewer.md
│ ├── bulk.md
│ ├── vision.md
│ └── commenter.md
```
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 中如果写：
```
model: modelverse/glm-5.2
```
那么 glm-5.2 必须已经在 provider.modelverse.models 中声明，否则 OpenCode 启动或调用时可能报错。
### 视觉模型最容易漏的两个字段
如果模型要处理图片，原文强调这两个字段都不能少：
```
{ "attachment": true, "modalities": { "input": ["text", "image"], "output": ["text"] }
}
```
含义是：
字段
作用
漏配后果
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、汇总结果、控制返工。
建议权限：
```
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
```
关键点：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 建议白名单：
```
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
```
注意这里的原则：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 五子棋游戏验证了完整流程。这个案例不是客户案例，也不是性能评测，而是一个功能闭环演示。
流程如下：
1. 用户对 orchestrator 提需求：“做一个 HTML 五子棋游戏，双人轮流落子，判断胜负”。
2. orchestrator 拆解需求，调用 architect。
3. architect 输出棋盘数据结构、胜负判定逻辑和交互流程。
4. orchestrator 派 executor 实现 `index.html` 和游戏逻辑。
5. executor 修改完成后，orchestrator 调 reviewer。
6. reviewer 读取 diff、运行验证命令，报告阻塞问题或放行。
7. 如需注释，再调用 commenter。
8. 最终五子棋可以运行，支持双人轮流落子并判断胜负。
> 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 能不能写代码”——这早就不是问题了。它真正回答的是工程化的事：**后厨一忙起来，怎么做到不抢灶、不串味、炒砸锅了能追责，而且明天换班，出品还是一个味。**