简介:OpenCode 的 Agent 模式决定了 AI 是"只会补全代码"还是"能自己规划、拆解、执行、复核"。本文从架构出发,讲清主 Agent 与子 Agent 的分工逻辑、Markdown + frontmatter 的自定义配置方法、权限与工具白名单控制,以及 plan/build 双模式协作的实战流程,并给出多模型混搭下的选型与成本控制思路——想快速对比不同模型的调用成本与能力边界,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比与统一 API 接入,方便你为不同 Agent 角色匹配合适的模型。
OpenCode 是运行在终端里的开源 AI 编码代理,整体可以拆成四层:用户界面层(CLI/TUI/Web)、AI 引擎层(Claude、GPT、Gemini、本地 Ollama 等)、核心能力层(Agent、Skills、MCP)、工具集成层(文件系统、Git、浏览器、API、数据库)。
Agent 模式属于核心能力层的最上层——它不直接调用模型,而是决定 “谁来调用模型、能调用哪些工具、以什么身份说话” 。同一个模型,配上不同的 Agent 定义,输出质量可能差出一个量级:受限的 Agent 只敢改一个文件,权限开放的 Agent 能跑测试、提交 Git、抓网页文档。
理解这一点,比记住任何配置字段都重要。
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 用 Markdown 定义,正文即 system prompt,元信息写在 frontmatter 里。
放置位置(两种任选,项目级优先):
# 全局~/.config/opencode/agent/*.md# 项目级(建议随仓库提交,团队共享).opencode/agent/*.md
一个实用的规划 Agent:
---description: 分析代码库并输出实施方案,不修改任何文件mode: primarymodel: anthropic/claude-sonnet-4temperature: 0.2permission:edit: denybash: askwebfetch: allow---你是一名资深架构师。请按以下顺序工作:1. 先用检索工具定位相关模块与调用链,不要凭猜测下结论;2. 列出 2-3 种可行方案,说明各自的改动面与风险;3. 输出分步实施清单,每步标注涉及的文件路径;4. 明确指出需要用户确认的歧义点。禁止直接给出完整代码实现。
一个只做审查的子 Agent:
---description: 代码审查专家,检查缺陷、安全隐患与性能问题mode: subagentmodel: anthropic/claude-opus-4temperature: 0tools:write: falseedit: falsebash: false---审查提供的 diff,按「阻塞问题 / 建议改进 / 可选优化」三档输出,每条给出文件行号、问题原因和修复建议。不要复述代码。
关键字段说明:
| 字段 | 作用 | 实践建议 |
|---|---|---|
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 模式最大的价值,是让你能 按角色分配模型 ,而不是全用一个最贵的:
在 opencode.json 中接入 OpenAI 兼容的服务商即可,配置方式与在 Roo Code 等工具中接入千帆的思路一致——Provider 选 OpenAI Compatible,Base URL 填服务地址,API Key 填控制台新建的密钥,Model 填具体模型名:
{"$schema": "https://opencode.ai/config.json","agent": {"plan": { "model": "myprovider/strong-reasoning-model" },"build": { "model": "myprovider/fast-coding-model" }},"provider": {"myprovider": {"npm": "@ai-sdk/openai-compatible","options": { "baseURL": "https://your-endpoint/v2" },"models": {"strong-reasoning-model": { "name": "强推理模型" },"fast-coding-model": { "name": "轻量编码模型" }}}}}
这里最容易踩的坑是 成本失控 :一个复杂任务里,子 Agent 可能反复检索、几十轮调用,如果全用旗舰模型,Token 消耗会非常可观。建议在词元所上先对比候选模型的单价与上下文长度,估算”单任务平均轮次 × 平均输入输出 Token”的大致成本,再决定哪个角色用哪个模型。若你已经在用 One API 之类的网关做多模型收口,也可以把网关地址直接填进上面的 baseURL,用统一接口屏蔽后端差异。
一个真实的中等复杂度需求(例如”给订单模块加幂等重试”),推荐这样跑:
plan Agent 读代码,产出改动清单。人工过一遍清单,纠正方向。这一步的成本远低于返工。build,把 plan 的输出作为输入,要求”严格按清单执行,每完成一步跑一次相关测试”。@review 审查 diff,用 @tester 补测试。子 Agent 上下文独立,不会把主对话撑爆。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 配置,这样后续换模型只需改一行配置,不必重搭流程。