OpenCode Agent 配置实战指南：玩转 Build / Plan 与自定义智能体

引言

很多用过 OpenCode 的同学都遇到过这样的场景：想让它先分析一遍代码、出一个改造方案再动手，结果它话不多说直接就改了；或者想让一个"只读审查"的助手去检查代码质量，却担心它会顺手修改文件。这些痛点，其实都源于对 OpenCode Agent（智能体）系统的不了解。

OpenCode 的本质是"多智能体"架构：不同的 Agent 拥有不同的系统提示词（system prompt）、模型和工具权限，可以被切换、被 @ 调用、甚至相互嵌套。合理配置 Agent，等于把一台"万能工具车"拆成了"巡逻车 + 挖掘机 + 质检员"，各司其职，效率和安全性都会大幅提升。本文会从内置 Agent 讲起，带你彻底搞懂 Agent 的配置体系，并给出可直接复用的实战案例。

一、Agent 的两种类型：Primary 与 Subagent

OpenCode 的 Agent 分为两类：

  • Primary agents（主智能体）：你直接对话的对象，通过 Tab 键或 switch_agent 键位来回切换。它们处理主线对话，工具权限由 permission 系统控制。
  • Subagents（子智能体）：由主智能体按需调用的"专业外援"，也可以手动用 @ 提及调用，例如 @general 帮我查一下这个函数的调用链。

这种分层设计的好处很明显：主智能体负责统筹，子智能体负责专项，长任务还能并行推进。

二、内置 Agent 一览

OpenCode 内置了两个主智能体和三个子智能体，开箱即用：

| Agent | 类型 | 用途 |
| --- | --- | --- |
| build | primary（默认） | 开发主力，所有工具全开，负责实际编码 |
| plan | primary | 规划与分析，edit 和 bash 默认全部 ask，只做方案不动代码 |
| general | subagent | 通用研究，可执行多步骤任务，全工具权限 |
| explore | subagent | 只读代码探索，快速定位文件、搜索关键字 |
| scout | subagent | 只读外部文档与依赖研究，可克隆依赖仓库到缓存区排查源码 |

另外还有 compaction（上下文压缩）、title（生成会话标题）、summary（生成会话摘要）三个隐藏的系统 Agent，由 OpenCode 自动触发，不需要也不应该手动配置。

关键使用技巧：Tab 键在主智能体间切换；@ 提及子智能体；子智能体创建的子会话用 session_child_first（默认 <Leader>+Down）进入，session_child_cycle（Right/Left）在子会话间跳转，session_parent（Up）返回主会话。

三、配置 Agent 的两种方式

方式一：opencode.json 的 agent 字段

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码最佳实践与潜在问题",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一名资深代码审查员，重点检查安全性、性能与可维护性。",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

方式二：Markdown 文件（推荐）

把文件放在全局 ~/.config/opencode/agents/ 或项目级 .opencode/agents/ 目录，文件名即 Agent 名。例如 .opencode/agents/review.md：

---
description: 审查代码质量与最佳实践
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

你处于代码审查模式，重点检查：
- 代码质量与最佳实践
- 潜在 Bug 与边界情况
- 性能影响
- 安全风险

给出建设性意见，但不要直接修改代码。

相比 JSON，Markdown 方式把提示词和配置写在一起，更易读、易维护，强烈推荐。

四、核心配置项逐项拆解

1. mode：决定 Agent 的定位

primary、subagent 或 all（默认）。subagent 只能在 @ 提及或被 Task 工具调用时出现；primary 会进入 Tab 切换列表。还可以用 hidden: true 把子智能体从 @ 自动补全菜单中隐藏，仅供其他 Agent 通过 Task 工具程序化调用。

2. model 与全局模型

不配置 model 时，主智能体使用全局配置的 model，子智能体继承调用它的主智能体的模型。可按任务类型分流：规划用轻量快的模型，实现用能力强的模型。

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-5"
    }
  }
}

3. temperature 与 top_p：控制创造力

  • 0.0~0.2：聚焦、确定性高，适合代码分析与规划
  • 0.3~0.5：平衡，适合常规开发
  • 0.6~1.0：更具创造性，适合头脑风暴

top_p 是 temperature 的替代方案，同样的随机性控制，二选一即可。未配置时使用模型默认值（多数模型为 0，Qwen 系为 0.55）。

4. steps：限制代理迭代次数

steps 控制 Agent 在被迫转成纯文本回复前最多执行多少次"思考-行动"迭代，适合控制成本：

{
  "agent": {
    "quick-thinker": {
      "description": "快速思考，限制迭代次数",
      "prompt": "用最少的步骤解决问题。",
      "steps": 5
    }
  }
}

注意：旧的 maxSteps 字段已废弃，请使用 steps。

5. permission：每个 Agent 的权限边界

权限值是 ask（询问确认）/ allow（直接放行）/ deny（禁用），支持通配符模式，内置工具、自定义工具、MCP 工具一视同仁：

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow"
        },
        "edit": "ask"
      }
    }
  }
}

规则按顺序匹配，最后一条匹配的规则生效，所以要把通配的 * 放在前面，具体规则放后面。permission.task 还能控制某个 Agent 可以调用哪些子智能体：

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

6. prompt：注入外部提示词文件

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

路径相对配置文件所在目录，全局配置和项目配置都适用。配置里的 {env:VAR} 还能引用环境变量，方便按环境切换配置。

7. 其他实用项

  • disable: true：停用某个 Agent
  • color：定制 Agent 在 UI 中的颜色（hex 或主题色）
  • additional：直接透传给模型提供商的额外参数，如 OpenAI 推理模型的 reasoningEffort、textVerbosity

五、实战：三个可直接复用的 Agent

案例 1：文档写作 Agent

~/.config/opencode/agents/docs-writer.md：

---
description: 编写和维护项目文档
mode: subagent
permission:
  bash: deny
---

你是一名技术文档作者。输出清晰、结构完整的文档，注意：
- 条理清晰、结构合理
- 包含必要的代码示例
- 使用通俗易懂的语言

案例 2：安全审计 Agent

~/.config/opencode/agents/security-auditor.md：

---
description: 执行安全审计并识别漏洞
mode: subagent
permission:
  edit: deny
---

你是安全专家，重点排查：
- 输入校验漏洞
- 认证与授权缺陷
- 敏感数据泄露风险
- 依赖漏洞与配置安全隐患

案例 3：一键创建 Agent

命令行交互式创建，免去手写文件：

opencode agent create

它会依次询问：保存位置（全局/项目级）→ Agent 功能描述 → 自动生成系统提示词与标识符 → 选择允许的权限（未选中的一律 deny）→ 生成 Markdown 配置文件。

六、组合拳：如何在日常工作中用好 Agent

先规划后实施：用 default_agent 把默认主智能体设为 plan，或者会话开始时 Tab 切到 plan 出一份方案，确认后再切回 build 执行：

{
  "default_agent": "plan"
}

审查隔离：把代码审查交给只读的 security-auditor，用 @security-auditor 审查 src/ 下的改动，从机制上杜绝审查员顺手改代码。

并行提速：把"查源码 + 写文档 + 跑测试"分别 @ 给不同子智能体，子会话并行执行，最后在主会话汇总。

成本控制：给辅助性 Agent 设置 steps 上限，并让规划 Agent 用更便宜的模型。

总结

OpenCode 的 Agent 体系，本质是把"一个全能助手"拆解为"一支各有所长的团队"：build 负责执行，plan 负责谋略，explore 负责侦察，自定义 Agent 则补齐文档、审查、安全等专业分工。通过 mode、model、permission、steps 等配置项的组合，你既能提升任务效率，又能把 AI 的权限牢牢锁在安全边界内。

上手建议：先跑一次 opencode agent create 建一个文档 Agent，再给 build 配置一组带通配符的 bash 权限规则，你会立刻感受到多智能体工作流的威力。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客