OpenCode 内置了两类 agent：Primary agents（Build、Plan）直接对话，用 Tab 切换；Subagents（General、Explore）由主 agent 或 @ 调用执行子任务。本页覆盖所有内置 agent 的用途和限制、用 JSON 或 Markdown 文件自定义 agent、以及 model/permission/temperature/steps 等核心配置项详解。相比 Claude Code 的固定行为，OpenCode 的 agent 系统更灵活，可以精细控制每个 agent 能执行的工具。

OpenCode Agents 配置

OpenCode 中的 agent 是专用 AI 助手，可以针对不同任务配置不同的提示词、模型和工具权限。

提示：用 Plan agent 分析代码、审阅建议，不会产生任何代码变更。

可以在会话中随时切换 agent，也可以用 @ 调用 subagent。

---

Agent 类型

OpenCode 有两类 agent：Primary agents 和 Subagents。

Primary agents

Primary agents 是你直接对话的主 agent。用 Tab 键循环切换，也可以用配置的 switch_agent 快捷键。工具访问权限通过 permissions 配置——Build 默认开启所有工具，Plan 默认限制写入。

OpenCode 内置 Build 和 Plan 两个 primary agent。

Subagents

Subagents 是专用子助手，可以被 primary agent 自动调用，也可以在消息中用 @ 手动调用。

OpenCode 内置 General 和 Explore 两个 subagent。

---

内置 Agent

Build（默认主 agent）

类型：primary

Build 是默认 primary agent，开启了所有工具。适合日常开发工作，需要文件读写和执行命令时使用。

Plan（规划 agent）

类型：primary

专为规划和分析设计，限制了写入权限。以下操作默认设为 ask（执行前确认）：

• file edits：所有写入、patch、编辑操作
• bash：所有 bash 命令

适合想让 AI 分析代码、提建议或制定方案，但不希望它直接改动代码时使用。

General（通用子 agent）

类型：subagent

通用目的的子 agent，用于研究复杂问题和多步任务。拥有完整工具访问权限（除了 todo），可以修改文件。适合并行处理多个任务单元。

Explore（探索子 agent）

类型：subagent

快速只读的代码库探索 agent，不能修改文件。用于快速查找文件、搜索代码关键词、回答代码库相关问题。

---

切换与调用

1. Primary agents：按 Tab 键循环切换，或用 switch_agent 快捷键

2. Subagents 有两种调用方式：

   • 由 primary agent 根据任务自动调用

   • 在消息中 @ 提及手动调用：

     @general help me search for this function

3. 会话导航：subagent 创建子会话时：

   • <Leader>+Down：进入第一个子会话
   • Right：循环切换子会话
   • Left：反向循环
   • Up：回到父会话

---

配置 Agent

可以通过 JSON 或 Markdown 两种方式配置和自定义 agent。

JSON 配置

在 opencode.json 中配置：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown 配置（推荐）

也可以用 Markdown 文件定义 agent，放在：

• 全局：~/.config/opencode/agents/
• 项目级：.opencode/agents/

文件名即 agent 名，例如 review.md 创建名为 review 的 agent：

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

---

配置项详解

description

agent 的用途描述，决定它被自动调用的时机（必填）：

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

model

覆盖该 agent 使用的模型，适合给不同 agent 指定不同性能档次的模型：

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

模型 ID 格式为 provider/model-id。如果使用 OpenCode Zen，格式如 opencode/gpt-5.1-codex。

不指定时，primary agent 用全局配置的模型，subagent 用调用它的 primary agent 的模型。

temperature

控制输出的随机性和创造性（0.0 到 1.0）：

• 0.0-0.2：高度确定性，适合代码分析和规划
• 0.3-0.5：平衡，适合一般开发任务
• 0.6-1.0：更有创意，适合头脑风暴

{
  "agent": {
    "analyze": { "temperature": 0.1 },
    "brainstorm": { "temperature": 0.7 }
  }
}

未指定时使用模型默认值（大多数模型为 0，Qwen 系列为 0.55）。

steps（最大步数）

限制 agent 的最大 agentic 迭代次数，可用于控制成本：

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "steps": 5
    }
  }
}

超出限制后，agent 会被要求总结已完成的工作和建议的后续步骤。

maxSteps 已废弃，请用 steps。

permission

精细控制 agent 能执行的操作：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

取值："allow"（允许）、"ask"（执行前确认）、"deny"（禁止）。

对 bash 命令可以设置更细粒度的规则（支持 glob 模式，后匹配优先）：

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

mode

控制 agent 的类型：

• "primary"：主 agent，可通过 Tab 切换
• "subagent"：子 agent，通过 @ 或自动调用
• "all"：两种模式都支持（默认值）

hidden

设为 true 可将 subagent 从 @ 自动补全菜单隐藏，只允许其他 agent 通过 Task 工具调用：

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

color

自定义 agent 在 UI 中的颜色标识，支持十六进制或主题色（primary/accent/error 等）：

{
  "agent": {
    "code-reviewer": { "color": "accent" },
    "creative": { "color": "#ff6b6b" }
  }
}

---

创建新 Agent

用交互式命令快速创建 agent：

opencode agent create

会依次询问：保存位置（全局或项目级）、agent 用途描述、生成系统提示词、选择工具权限，最后生成 Markdown 配置文件。

---

实用 Agent 示例

文档写作 agent（Markdown 文件）：

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

安全审计 agent：

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks

---

常见问题

Q: Plan agent 和 Build agent 有什么区别？我什么时候用 Plan？

A: Plan agent 限制了写入和 bash 权限（执行前确认），相当于"只看不动"模式。在你想先了解 AI 打算怎么改、或者探索陌生代码库时用 Plan；确认方案后切回 Build 执行。

Q: 如何给不同 agent 用不同的模型，比如 Plan 用便宜小模型、Build 用强模型？

A: 在 opencode.json 中分别配置 model 字段即可。例如 Plan 用 anthropic/claude-haiku-4-20250514，Build 用 anthropic/claude-sonnet-4-20250514。

Q: 自定义 subagent 会出现在 @ 补全菜单里吗？

A: 是的，默认出现。如果是内部工具 agent 不想让用户直接调用，设 hidden: true 可以从菜单中隐藏，但其他 agent 仍可以通过 Task 工具调用它。