OpenCode 进阶指南:Agent 模式配置与实战

作者:沙与沫2026.11.17 03:49浏览量:0

简介:OpenCode 的 Agent 模式决定了 AI 是"只会补全代码"还是"能自己规划、拆解、执行、复核"。本文从架构出发,讲清主 Agent 与子 Agent 的分工逻辑、Markdown + frontmatter 的自定义配置方法、权限与工具白名单控制,以及 plan/build 双模式协作的实战流程,并给出多模型混搭下的选型与成本控制思路——想快速对比不同模型的调用成本与能力边界,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比与统一 API 接入,方便你为不同 Agent 角色匹配合适的模型。

agent-">一、先看清 Agent 模式在架构中的位置

OpenCode 是运行在终端里的开源 AI 编码代理,整体可以拆成四层:用户界面层(CLI/TUI/Web)、AI 引擎层(Claude、GPT、Gemini、本地 Ollama 等)、核心能力层(Agent、Skills、MCP)、工具集成层(文件系统、Git、浏览器、API、数据库)。

Agent 模式属于核心能力层的最上层——它不直接调用模型,而是决定 “谁来调用模型、能调用哪些工具、以什么身份说话” 。同一个模型,配上不同的 Agent 定义,输出质量可能差出一个量级:受限的 Agent 只敢改一个文件,权限开放的 Agent 能跑测试、提交 Git、抓网页文档。

理解这一点,比记住任何配置字段都重要。

二、Agent 模式的三种形态

1. 内置主 Agent(primary)

OpenCode 默认提供 build 与 plan 两个主 Agent:

  • build:完整工具权限,可读写文件、执行命令,负责落地实现。
  • plan:只读为主,禁止改动文件,专注分析代码库、输出实施方案。

在 TUI 中通过 Tab 键即可切换。这是最容易被忽略的进阶技巧—— 先 plan 后 build ,能显著减少”AI 一上来就大改一通、方向全错”的返工。

2. 自定义主 Agent

用于固化你的个人或团队工作流,例如一个只做代码审查的 review Agent、一个只写测试的 tester Agent。

3. 子 Agent(subagent)

由主 Agent 通过任务工具自动调度,也可在输入框用 @ 手动唤起。子 Agent 有独立上下文,适合”大范围检索””批量分析”这类会污染主上下文的脏活。

三、自定义 Agent 的配置文件怎么写

Agent 用 Markdown 定义,正文即 system prompt,元信息写在 frontmatter 里。

放置位置(两种任选,项目级优先):

  1. # 全局
  2. ~/.config/opencode/agent/*.md
  3. # 项目级(建议随仓库提交,团队共享)
  4. .opencode/agent/*.md

一个实用的规划 Agent:

  1. ---
  2. description: 分析代码库并输出实施方案,不修改任何文件
  3. mode: primary
  4. model: anthropic/claude-sonnet-4
  5. temperature: 0.2
  6. permission:
  7. edit: deny
  8. bash: ask
  9. webfetch: allow
  10. ---
  11. 你是一名资深架构师。请按以下顺序工作:
  12. 1. 先用检索工具定位相关模块与调用链,不要凭猜测下结论;
  13. 2. 列出 2-3 种可行方案,说明各自的改动面与风险;
  14. 3. 输出分步实施清单,每步标注涉及的文件路径;
  15. 4. 明确指出需要用户确认的歧义点。
  16. 禁止直接给出完整代码实现。

一个只做审查的子 Agent:

  1. ---
  2. description: 代码审查专家,检查缺陷、安全隐患与性能问题
  3. mode: subagent
  4. model: anthropic/claude-opus-4
  5. temperature: 0
  6. tools:
  7. write: false
  8. edit: false
  9. bash: false
  10. ---
  11. 审查提供的 diff,按「阻塞问题 / 建议改进 / 可选优化」三档输出,
  12. 每条给出文件行号、问题原因和修复建议。不要复述代码。

关键字段说明:

字段 作用 实践建议
mode primary / subagent / all 审查、检索类设为 subagent,避免抢占主流程
model 指定该 Agent 使用的模型 规划/审查用强模型,批量执行用轻量模型
temperature 采样温度 审查、生成测试用例设 0~0.2;创意命名可放宽
tools 工具级开关 只读 Agent 关掉 write/edit/bash
permission edit/bash/webfetch 的 allow/ask/deny 生产仓库建议 bash: ask,防止误删
prompt 追加或替换默认提示词 团队规范写进这里,比每次手打可靠

四、多模型混搭:Agent 模式的真正杠杆

Agent 模式最大的价值,是让你能 按角色分配模型 ,而不是全用一个最贵的:

  • 规划、架构评审、疑难 Bug 定位 → 推理能力强的旗舰模型;
  • 单文件改写、格式化、写注释、跑批量重构 → 性价比高的中小模型;
  • 敏感代码不出内网 → 本地 Ollama 模型。

在 opencode.json 中接入 OpenAI 兼容的服务商即可,配置方式与在 Roo Code 等工具中接入千帆的思路一致——Provider 选 OpenAI Compatible,Base URL 填服务地址,API Key 填控制台新建的密钥,Model 填具体模型名:

  1. {
  2. "$schema": "https://opencode.ai/config.json",
  3. "agent": {
  4. "plan": { "model": "myprovider/strong-reasoning-model" },
  5. "build": { "model": "myprovider/fast-coding-model" }
  6. },
  7. "provider": {
  8. "myprovider": {
  9. "npm": "@ai-sdk/openai-compatible",
  10. "options": { "baseURL": "https://your-endpoint/v2" },
  11. "models": {
  12. "strong-reasoning-model": { "name": "强推理模型" },
  13. "fast-coding-model": { "name": "轻量编码模型" }
  14. }
  15. }
  16. }
  17. }

这里最容易踩的坑是 成本失控 :一个复杂任务里,子 Agent 可能反复检索、几十轮调用,如果全用旗舰模型,Token 消耗会非常可观。建议在词元所上先对比候选模型的单价与上下文长度,估算”单任务平均轮次 × 平均输入输出 Token”的大致成本,再决定哪个角色用哪个模型。若你已经在用 One API 之类的网关做多模型收口,也可以把网关地址直接填进上面的 baseURL,用统一接口屏蔽后端差异。

五、实战流程:plan → build → subagent 三段式

一个真实的中等复杂度需求(例如”给订单模块加幂等重试”),推荐这样跑:

  1. plan 阶段 :只让 plan Agent 读代码,产出改动清单。人工过一遍清单,纠正方向。这一步的成本远低于返工。
  2. build 阶段 :切到 build,把 plan 的输出作为输入,要求”严格按清单执行,每完成一步跑一次相关测试”。
  3. subagent 阶段 :用 @review 审查 diff,用 @tester 补测试。子 Agent 上下文独立,不会把主对话撑爆。
  4. 非交互执行 :已验证的机械任务可用 opencode run --agent build "..." 放进 CI 或脚本里批量跑。

配合 MCP 接入外部系统(数据库、浏览器、内部 API)后,Agent 的能力边界会从”改代码”扩展到”查数据、验接口”,这也是 OpenCode 相比纯补全工具的核心差异——它走的是 Agent 框架而非单一模型调用的路线。

六、常见问题排查

现象 常见原因 处理方式
Agent 无视约束直接改文件 permission.edit 未设为 deny,或 prompt 里约束太弱 权限用配置硬约束,不要只靠提示词
自定义 Agent 不出现 文件目录不对、frontmatter YAML 格式错误 检查 .opencode/agent/ 路径与 --- 闭合
子 Agent 不干活 mode 写成 primary 或 description 缺失 改为 subagent 并补全描述
上下文很快溢出 大范围检索放在主 Agent 里做 把检索类工作下沉给子 Agent
模型调用 401/404 baseURL 少了 /v2、模型名与服务端不一致 对照服务商模型列表逐字核对
任务越跑越贵 全角色使用旗舰模型 按角色分层选模型,先做成本估算

七、小结

Agent 模式的进阶路线可以概括成三步: 先用 plan/build 分离把方向管住,再用自定义 Agent 把团队规范固化进配置,最后用多模型分层把成本和效果调到平衡点 。工具只是外壳,真正决定产出质量的是这套角色分工与约束设计。落地前建议在百度智能云词元所上完成模型选型与价格测算,并通过统一 API 接入你的 OpenCode 配置,这样后续换模型只需改一行配置,不必重搭流程。