OpenCode: OpenCode代理（Agent）
最后更新：2026-08-31
代理是 OpenCode 中专门化的 AI 助手，每个代理可配置独立的提示词、模型、工具和权限。
1. 你将学到
- 代理类型：主代理与子代理
- 内置代理详解
- 自定义代理配置
- 代理使用方式
2. 代理类型
| 类型 | 说明 | 切换方式 |
|---|---|---|
| 主代理（primary） | 直接交互的主要助手 | Tab 键切换 |
| 子代理（subagent） | 由主代理调用的专门助手 | @代理名 或自动调用 |
3. 内置代理
(1) Build（主代理）
默认主代理，启用所有工具，适合日常开发。
(2) Plan（主代理）
专为分析和规划设计，文件编辑和 bash 命令设为 ask，不会直接修改代码。
(3) General（子代理）
通用子代理，拥有完整工具权限，可修改文件。适合研究复杂问题和多步骤任务。
(4) Explore（子代理）
只读子代理，无法修改文件。适合快速查找和回答代码库结构问题。
(5) 系统代理（隐藏）
| 代理 | 职责 | 触发时机 |
|---|---|---|
| Compaction | 压缩过长上下文 | 上下文达到阈值时 |
| Title | 生成会话标题 | 新会话开始后 |
| Summary | 创建会话摘要 | 需要摘要时 |
4. 切换与调用代理
(1) 切换主代理
按 Tab 键在主代理间循环切换，Shift+Tab 反向切换。
(2) 调用子代理
TEXT
📖 仅展示
@explore 找出项目中所有使用 Redis 的地方
或让主代理自动判断并调用。
(3) 子会话导航
| 快捷键 | 操作 |
|---|---|
<Leader>+→ |
向前循环子会话 |
<Leader>+← |
向后循环子会话 |
<Leader>+↑ |
返回父会话 |
5. 自定义代理配置
(1) 在 opencode.json 中配置
JSON
{
"agent": {
"code-reviewer": {
"description": "Reviews code for best practices",
"mode": "subagent",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "You are a code reviewer. Focus on security and performance.",
"tools": {
"write": false,
"edit": false
}
}
}
}
(2) Markdown 文件配置
在 ~/.config/opencode/agents/（全局）或 .opencode/agents/（项目级）创建 .md 文件：
MARKDOWN
---
description: Reviews code for quality
mode: subagent
tools:
write: false
edit: false
---
You are a code reviewer. Focus on code quality and best practices.
文件名即为代理名称。
6. 配置选项详解
| 选项 | 说明 |
|---|---|
description |
代理功能描述（必填） |
mode |
primary / subagent / all |
model |
指定模型（格式：provider/model-id） |
prompt |
系统提示词，支持 {file:./path} 加载文件 |
temperature |
输出随机性（0.0-1.0） |
steps |
最大迭代次数 |
tools |
工具访问权限 |
permission |
细粒度权限控制 |
hidden |
从 @ 菜单中隐藏 |
color |
UI 显示颜色 |
disable |
禁用代理 |
(1) temperature 建议
| 范围 | 适用场景 |
|---|---|
| 0.0-0.2 | 代码分析、调试、审查 |
| 0.3-0.5 | 一般开发、文档编写 |
| 0.6-1.0 | 头脑风暴、方案探索 |
(2) permission 配置
JSON
{
"agent": {
"build": {
"permission": {
"bash": {
"*": "ask",
"git status *": "allow",
"grep *": "allow"
}
}
}
}
}
7. 快速创建代理
BASH
opencode agent create
交互式引导创建代理，自动生成配置文件。
8. 常见代理示例
(1) 文档写作代理
MARKDOWN
---
description: Writes project documentation
mode: subagent
tools:
bash: false
---
You are a technical writer. Create clear documentation with code examples.
(2) 安全审计代理
MARKDOWN
---
description: Security audit and vulnerability detection
mode: subagent
tools:
write: false
edit: false
---
You are a security expert. Identify vulnerabilities and security issues.
❓ 常见问题
Q 什么时候应该用 Plan 代理而不是 Build 代理？
A 当你想让 AI 分析代码、提供建议但不希望它修改文件时，切换到 Plan 代理。Plan 的编辑和 bash 权限设为 ask，不会直接动手。
Q 子代理可以调用子代理吗？
A 可以，通过 Task 工具。但要注意避免循环调用。可以通过 permission.task 配置控制哪些子代理可以被调用。
Q Alice 创建了 5 个自定义代理，Bob 只用内置代理，谁的工作效率更高？
A 取决于场景。简单任务内置代理够用；复杂工作流中，针对不同任务配置专门代理可以显著提高输出质量和效率。
📖 小节
- 代理分主代理（Tab 切换）和子代理（@ 调用）
- 内置 4 个可用代理 + 3 个系统代理
- 支持 JSON 和 Markdown 两种配置方式
- 可为代理指定模型、提示词、工具权限、温度等
- 用
opencode agent create快速创建
📝 作业
-
基础题：在 TUI 中用 Tab 键切换 Build 和 Plan 代理，体验两者区别。
-
进阶题：创建一个只读的代码审查代理，设置低温度和适当的工具权限。
-
挑战题：设计一套包含主代理 + 多个子代理的代理体系，用于处理一个完整的项目开发流程。
