OpenCode 代理（Agent）配置详解
代理是 OpenCode 中专门化的 AI 助手，每个代理可以配置独立的系统提示词、模型、工具访问权限和行为约束，用于处理特定类型的任务和工作流程。你可以在会话期间随时切换代理，或通过 @代理名称 的方式直接调用特定代理。
代理类型
OpenCode 中的代理分为两种类型，它们的调用方式和职责不同：
| 类型 | 说明 | 切换方式 |
|---|---|---|
| 主代理（primary） | 你直接交互的主要助手，处理主要对话流程。工具访问权限通过 permission 配置 |
按 Tab 键循环切换，或使用配置的 agent_cycle 快捷键 |
| 子代理（subagent） | 由主代理调用来执行专门任务的助手，运行在独立的子会话中，不影响主会话上下文 | 主代理自动调用，或在消息中用 @代理名称 手动调用 |
内置代理
OpenCode 内置了 4 个开箱即用的代理，以及 3 个自动运行的系统代理：
1、Build（主代理）
默认的主代理，启用了所有工具，适合需要完整文件操作和系统命令访问权限的日常开发工作。这是你最常使用的代理。
2、Plan（主代理）
专为代码分析和规划设计的受限代理。默认情况下，以下操作均会触发审批提示（设为 ask）：
- file edits：所有写入、补丁和编辑操作
- bash：所有 bash 命令
当你希望 LLM 分析代码、提出建议或创建执行计划，但不希望它对代码库进行任何实际修改时，请切换到 Plan 代理。
3、General（子代理）
通用子代理，拥有完整的工具访问权限（todo 工具除外），可以修改文件。适用于研究复杂问题和执行多步骤任务，也可以并行运行多个独立的工作单元。
4、Explore（子代理）
只读子代理，无法修改任何文件。适合快速查找文件、搜索代码关键字或回答关于代码库结构的问题，速度快且不会产生副作用。
5、系统代理（隐藏）
以下三个代理由 OpenCode 自动管理，不会出现在代理切换列表中，无需也无法手动选择：
| 代理名称 | 职责 | 触发时机 |
|---|---|---|
| Compaction | 将过长的上下文压缩为较小的摘要，防止超出模型上下文限制 | 上下文长度达到阈值时自动运行 |
| Title | 为会话生成简短标题 | 新会话开始后自动运行 |
| Summary | 为会话创建摘要 | 需要会话摘要时自动运行 |
代理的使用方式
1、切换主代理
在会话期间按 Tab 键可以在所有主代理之间循环切换，按 Shift+Tab 反向切换。也可以使用 <Leader>a 打开代理列表直接选择。
2、调用子代理
子代理有两种调用方式：
- 自动调用：主代理根据任务性质判断需要某个子代理时，会自动调用并将任务委派给它
- 手动 @ 调用：在消息中使用
@代理名称直接指定由哪个子代理处理
@general help me search for this function across the codebase
3、在父子会话间导航
子代理运行时会创建独立的子会话，可以使用快捷键在父会话和各子会话之间导航：
| 快捷键 | 操作 |
|---|---|
<Leader>+→（session_child_cycle） |
向前循环：父会话 → 子会话1 → 子会话2 → … → 父会话 |
<Leader>+←（session_child_cycle_reverse） |
向后循环：父会话 ← 子会话1 ← 子会话2 ← … ← 父会话 |
<Leader>+↑（session_parent） |
直接返回父会话 |
两种配置方式
代理可以通过 JSON 配置或 Markdown 文件两种方式定义，效果相同，按需选择：
方式一：在 opencode.json 中配置
实例
"$schema": "https://opencode.ai/config.json",
"agent": {
"build": { // 覆盖内置 build 代理的配置
"mode": "primary",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "{file:./prompts/build.txt}", // 从文件加载系统提示词
"tools": {
"write": true,
"edit": true,
"bash": true
}
},
"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 文件
在以下路径创建 .md 文件，文件名即为代理名称（如 review.md 对应代理名 review）：
- 全局：
~/.config/opencode/agents/（对所有项目有效） - 项目级：
.opencode/agents/（仅对当前项目有效）
实例
---
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": {
"review": {
"description": "Reviews code for best practices and potential issues"
}
}
}
mode（模式）
控制代理的使用方式，可以设置为以下三个值：
| 值 | 说明 |
|---|---|
"primary" |
主代理，出现在 Tab 切换列表中，用于主对话 |
"subagent" |
子代理，不在 Tab 切换列表中，由主代理调用或通过 @ 手动调用 |
"all" |
同时作为主代理和子代理使用（未指定 mode 时的默认值） |
实例
"agent": {
"review": {
"mode": "subagent" // 只作为子代理使用，不出现在主代理切换列表中
}
}
}
model（模型）
为代理指定特定的模型，覆盖全局配置的默认模型。格式为 provider/model-id。适合针对不同任务使用不同的模型，例如规划任务用较快的小模型，代码生成用较强大的大模型：
实例
"agent": {
"plan": {
"model": "anthropic/claude-haiku-4-20250514" // 规划任务使用速度更快的 Haiku 模型
},
"build": {
"model": "anthropic/claude-sonnet-4-20250514" // 开发任务使用能力更强的 Sonnet 模型
}
}
}
如果未指定
model，主代理会使用全局配置的默认模型，子代理会继承调用它的主代理所使用的模型。运行opencode models可查看所有可用模型列表。
prompt（系统提示词）
为代理指定自定义系统提示词，可以直接写字符串，也可以通过 {file:./路径} 语法从外部文件加载。路径相对于配置文件所在位置：
实例
"agent": {
"review": {
"prompt": "{file:./prompts/code-review.txt}"
// 从 opencode.json 同目录下的 prompts/code-review.txt 读取提示词
// 适合提示词内容较长时，将其单独维护在文本文件中
}
}
}
temperature（温度）
控制模型输出的随机性。值越低输出越确定，适合需要精确结果的任务；值越高输出越多样，适合创意类任务：
| 温度范围 | 输出特点 | 适用场景 |
|---|---|---|
| 0.0 – 0.2 | 高度集中、确定性强 | 代码分析、规划、调试、审查 |
| 0.3 – 0.5 | 平衡，兼顾准确与灵活 | 一般开发任务、文档编写 |
| 0.6 – 1.0 | 较有创意和多样性 | 头脑风暴、方案探索、创意写作 |
实例
"agent": {
"analyze": {
"temperature": 0.1, // 分析任务：高确定性
"prompt": "{file:./prompts/analysis.txt}"
},
"build": {
"temperature": 0.3 // 开发任务：平衡
},
"brainstorm": {
"temperature": 0.7, // 头脑风暴：更有创意
"prompt": "{file:./prompts/creative.txt}"
}
}
}
未指定
temperature时，OpenCode 使用模型的默认值——大多数模型默认为0，Qwen 系列模型默认为0.55。
steps（最大步数）
控制代理在被强制以纯文本响应之前，最多可以执行的迭代次数（即调用工具的轮数）。适合需要控制成本或防止代理无限循环的场景：
实例
"agent": {
"quick-thinker": {
"description": "Fast reasoning with limited iterations",
"prompt": "You are a quick thinker. Solve problems with minimal steps.",
"steps": 5 // 最多执行 5 次迭代，超出后代理会输出当前进度摘要和剩余建议任务
}
}
}
未设置 steps 时，代理会持续迭代直到模型主动停止，或用户手动中断。
旧版
maxSteps字段已弃用，请统一使用steps。
tools（工具访问）
控制该代理可以使用哪些工具，将工具名设为 true 或 false。代理级配置会覆盖全局配置：
实例
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": true, // 全局：允许写文件
"bash": true // 全局：允许 bash 命令
},
"agent": {
"plan": {
"tools": {
"write": false, // plan 代理：覆盖全局设置，禁用写文件
"bash": false // plan 代理：覆盖全局设置，禁用 bash
}
}
}
}
也可以使用通配符批量控制工具，例如禁用某个 MCP 服务器的所有工具：
实例
"agent": {
"readonly": {
"tools": {
"mymcp_*": false, // 禁用 mymcp 服务器的所有工具（Glob 匹配）
"write": false,
"edit": false
}
}
}
}
permission（权限）
为代理配置更细粒度的权限控制，可以针对每种操作设置 "allow"（允许）、"ask"（询问）或 "deny"（拒绝）：
实例
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "deny" // 全局：默认禁止所有文件编辑
},
"agent": {
"build": {
"permission": {
"edit": "ask" // build 代理：覆盖全局设置，编辑前需要审批
}
}
}
}
对于 bash 工具，还可以精细到具体命令，支持 Glob 通配符，且最后匹配的规则优先（建议将 * 通配规则放前面，具体规则放后面）：
实例
"agent": {
"build": {
"permission": {
"bash": {
"*": "ask", // 兜底：所有 bash 命令默认需要审批
"git status *": "allow",// git status 相关命令直接允许（更具体，优先匹配）
"grep *": "allow" // grep 搜索命令直接允许
}
}
}
}
}
在 Markdown 代理文件中，也可以在 frontmatter 中配置权限：
实例
---
description: Code review without edits
mode: subagent
permission:
edit: deny # 禁止所有文件编辑
bash:
"*": ask # bash 命令默认需要审批
"git diff": allow # 允许 git diff
"git log*": allow # 允许 git log 及其变体
"grep *": allow # 允许 grep 搜索
webfetch: deny # 禁止访问外部 URL
---
Only analyze code and suggest changes.
permission.task（任务权限）
控制该代理可以通过 Task 工具调用哪些子代理，支持 Glob 匹配。设为 "deny" 时，子代理会从 Task 工具描述中完全移除，模型不会尝试调用它：
实例
"agent": {
"orchestrator": {
"mode": "primary",
"permission": {
"task": {
"*": "deny", // 兜底：默认禁止调用所有子代理
"orchestrator-*": "allow", // 允许调用 orchestrator- 开头的子代理
"code-reviewer": "ask" // 调用 code-reviewer 前需要用户确认
// 最后匹配的规则优先：orchestrator-planner 同时匹配 * 和 orchestrator-*，
// 因为 orchestrator-* 在后面，所以结果为 allow
}
}
}
}
}
hidden（隐藏）
将子代理从 @ 自动补全菜单中隐藏，仅允许通过 Task 工具以编程方式调用，适合只应由其他代理内部调用的工具代理：
实例
"agent": {
"internal-helper": {
"mode": "subagent", // hidden 仅对 subagent 有效
"hidden": true // 隐藏后，用户的 @ 补全菜单中不会出现此代理，
// 但权限允许时，模型仍可通过 Task 工具调用它
}
}
}
color（颜色）
自定义代理在 UI 中的显示颜色。支持十六进制颜色值或主题颜色关键字（primary、secondary、accent、success、warning、error、info）：
实例
"agent": {
"creative": {
"color": "#ff6b6b" // 使用十六进制颜色
},
"code-reviewer": {
"color": "accent" // 使用主题颜色关键字
}
}
}
top_p（采样多样性）
top_p 是 temperature 之外的另一种控制输出多样性的参数，值范围 0.0 – 1.0，值越低输出越集中，值越高输出越多样：
实例
"agent": {
"brainstorm": {
"top_p": 0.9 // 较高的 top_p，增加输出多样性
}
}
}
disable（禁用）
将代理设为禁用状态，禁用后代理不会出现在选择列表中：
实例
"agent": {
"review": {
"disable": true // 禁用该代理，不影响其他代理
}
}
}
其他模型参数
代理配置中任何未被识别的字段，都会作为模型参数直接传递给服务提供商。这允许你使用提供商特定的高级功能：
实例
"agent": {
"deep-thinker": {
"description": "Agent that uses high reasoning effort for complex problems",
"model": "openai/gpt-5",
"reasoningEffort": "high", // OpenAI 推理力度参数，直接透传给 OpenAI API
"textVerbosity": "low" // OpenAI 响应详细程度参数
}
}
}
透传参数因服务提供商和模型而异，请查阅对应提供商的 API 文档确认可用参数名称。
快速创建代理
除了手动编写配置文件，也可以使用交互式命令行工具快速生成代理：
opencode agent create
该命令会依次引导你完成以下步骤：
- 选择代理的保存位置（全局
~/.config/opencode/agents/或项目级.opencode/agents/） - 描述代理的职责和目标
- 自动生成合适的系统提示词和代理标识符
- 选择代理可以访问的工具
- 在选定位置生成包含完整配置的 Markdown 文件
代理示例
文档写作代理
实例
---
description: Writes and maintains project documentation
mode: subagent
tools:
bash: false # 禁用 bash，文档写作不需要执行命令
---
You are a technical writer. Create clear, comprehensive documentation.
Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language
安全审计代理
实例
---
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
- Dependency vulnerabilities
- Configuration security issues
常见使用场景
| 场景 | 推荐代理配置 |
|---|---|
| 日常开发，需要完整工具权限 | 使用内置 Build 代理 |
| 分析代码、制定方案，不希望修改文件 | 切换到内置 Plan 代理 |
| 只读查询代码库结构或关键字 | 通过 @explore 调用内置 Explore 子代理 |
| 并行执行多个独立任务 | 通过 @general 调用多个 General 子代理并行处理 |
| 对代码进行安全性或质量审查 | 自定义只读子代理（禁用 write/edit），设置低温度（0.1） |
| 控制成本，限制 AI 执行步数 | 配置 steps 参数限制最大迭代次数 |
点我分享笔记