代理

对于主代理，在会话期间使用 Tab 键在它们之间循环切换。你也可以使用配置的 switch_agent 快捷键。
子代理可以被调用：
- 自动地 - 主代理根据描述为专门任务调用。
- 通过在消息中 @ 提及 子代理来手动调用。例如：
```
@general 帮我搜索这个函数
```
会话之间导航：当子代理创建自己的子会话时，你可以使用以下方式在父会话和所有子会话之间导航：
- <Leader>+Right（或配置的 session_child_cycle 快捷键）向前循环：父 → 子1 → 子2 → … → 父
- <Leader>+Left（或配置的 session_child_cycle_reverse 快捷键）向后循环：父 ← 子1 ← 子2 ← … ← 父
这允许你在主对话和专门的子代理工作之间无缝切换。

# 配置#

你可以通过配置自定义内置代理或创建自己的代理。代理可以通过两种方式配置：

## JSON#

在 opencode.json 配置文件中配置代理：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "agent": {
4    "build": {
5      "mode": "primary",
6      "model": "anthropic/claude-sonnet-4-20250514",
7      "prompt": "{file:./prompts/build.txt}",
8      "tools": {
9        "write": true,
10        "edit": true,
11        "bash": true
12      }
13    },
14    "plan": {
15      "mode": "primary",
16      "model": "anthropic/claude-haiku-4-20250514",
17      "tools": {
18        "write": false,
19        "edit": false,
20        "bash": false
21      }
22    },
23    "code-reviewer": {
24      "description": "审查代码的最佳实践和潜在问题",
25      "mode": "subagent",
26      "model": "anthropic/claude-sonnet-4-20250514",
27      "prompt": "你是一个代码审查员。专注于安全性、性能和可维护性。",
28      "tools": {
29        "write": false,
30        "edit": false
31      }
32    }
33  }
34}

## Markdown#

你也可以使用 markdown 文件定义代理。将它们放在：

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

markdown
1<!-- ~/.config/opencode/agents/review.md -->
2---
3description: 审查代码质量和最佳实践
4mode: subagent
5model: anthropic/claude-sonnet-4-20250514
6temperature: 0.1
7tools:
8  write: false
9  edit: false
10  bash: false
11---
12
13你处于代码审查模式。专注于：
14
15- 代码质量和最佳实践
16- 潜在的错误和边缘情况
17- 性能影响
18- 安全考虑
19
20提供建设性反馈，但不直接进行更改。

markdown 文件名成为代理名称。例如，review.md 创建一个 review 代理。

# 选项#

让我们详细了解这些配置选项。

## Description#

使用 description 选项提供代理功能和使用时机的简要描述。

json
1{
2  "agent": {
3    "review": {
4      "description": "审查代码的最佳实践和潜在问题"
5    }
6  }
7}

这是一个必需的配置选项。

## Temperature#

使用 temperature 配置控制 LLM 响应的随机性和创造性。

较低的值使响应更集中和确定性，而较高的值增加创造性和变化性。

json
1{
2  "agent": {
3    "plan": {
4      "temperature": 0.1
5    },
6    "creative": {
7      "temperature": 0.8
8    }
9  }
10}

温度值通常在 0.0 到 1.0 之间：

0.0-0.2：非常集中和确定性的响应，适合代码分析和规划
0.3-0.5：具有一定创造性的平衡响应，适合一般开发任务
0.6-1.0：更具创造性和变化的响应，适合头脑风暴和探索

如果未指定温度，OpenCode 使用模型特定的默认值；大多数模型通常为 0，Qwen 模型为 0.55。

## Max steps#

控制代理在被迫仅以文本响应之前可以执行的最大代理迭代次数。这允许希望控制成本的用户对代理操作设置限制。

如果未设置，代理将继续迭代，直到模型选择停止或用户中断会话。

json
1{
2  "agent": {
3    "quick-thinker": {
4      "description": "有限迭代的快速推理",
5      "prompt": "你是一个快速思考者。用最少的步骤解决问题。",
6      "maxSteps": 5
7    }
8  }
9}

当达到限制时，代理会收到一个特殊的系统提示，指示它以工作总结和推荐的剩余任务进行响应。

## Disable#

设置为 true 以禁用代理。

json
1{
2  "agent": {
3    "review": {
4      "disable": true
5    }
6  }
7}

## Prompt#

使用 prompt 配置为此代理指定自定义系统提示文件。提示文件应包含特定于代理目的的指令。

json
1{
2  "agent": {
3    "review": {
4      "prompt": "{file:./prompts/code-review.txt}"
5    }
6  }
7}

此路径相对于配置文件所在位置。因此这适用于全局 OpenCode 配置和项目特定配置。

## Model#

使用 model 配置覆盖此代理的模型。适用于为不同任务使用优化的不同模型。例如，用于规划的较快模型，用于实现的更强大模型。

提示： 如果你不指定模型，主代理使用全局配置的模型，而子代理将使用调用子代理的主代理的模型。

json
1{
2  "agent": {
3    "plan": {
4      "model": "anthropic/claude-haiku-4-20250514"
5    }
6  }
7}

OpenCode 配置中的模型 ID 使用格式 provider/model-id。例如，如果你使用 OpenCode Zen，你可以使用 opencode/gpt-5.1-codex 来使用 GPT 5.1 Codex。

## Tools#

使用 tools 配置控制此代理中可用的工具。你可以通过将特定工具设置为 true 或 false 来启用或禁用它们。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "write": true,
5    "bash": true
6  },
7  "agent": {
8    "plan": {
9      "tools": {
10        "write": false,
11        "bash": false
12      }
13    }
14  }
15}

注意： 代理特定的配置会覆盖全局配置。

你也可以使用通配符一次控制多个工具。例如，要禁用 MCP 服务器的所有工具：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "agent": {
4    "readonly": {
5      "tools": {
6        "mymcp_*": false,
7        "write": false,
8        "edit": false
9      }
10    }
11  }
12}

了解更多关于工具。

## Permissions#

你可以配置权限来管理代理可以执行的操作。OpenCode 支持简单的字符串权限（"ask" / "allow" / "deny"）或细粒度的对象权限。

支持的权限类型包括 edit、bash、webfetch 以及 task（控制子代理调用）等。

简单配置

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "permission": {
4    "edit": "deny"
5  }
6}

细粒度配置

你可以使用 glob 模式对特定命令或任务进行控制：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "agent": {
4    "build": {
5      "permission": {
6        "bash": {
7          "git push": "ask",
8          "git *": "allow",
9          "*": "deny"
10        },
11        "task": {
12          "orchestrator-*": "allow",
13          "*": "ask"
14        }
15      }
16    }
17  }
18}

了解更多关于权限。

## Additional Options#

除了上述标准配置外，任何未定义的选项都会直接传递给模型提供商。这允许你使用特定于提供商的功能。

json
1{
2  "agent": {
3    "reasoning": {
4      "model": "openai/o3-mini",
5      "reasoningEffort": "high"
6    }
7  }
8}

## Mode#

使用 mode 配置控制代理的模式。mode 选项用于确定代理如何使用。

json
1{
2  "agent": {
3    "review": {
4      "mode": "subagent"
5    }
6  }
7}

mode 选项可以设置为 primary、subagent 或 all。如果未指定 mode，默认为 all。

## Hidden#

使用 hidden: true 从 @ 自动完成菜单中隐藏子代理。适用于只应由其他代理通过 Task 工具以编程方式调用的内部子代理。

json
1{
2  "agent": {
3    "internal-helper": {
4      "mode": "subagent",
5      "hidden": true
6    }
7  }
8}

这只影响自动完成菜单中的用户可见性。如果权限允许，隐藏的代理仍然可以被模型通过 Task 工具调用。

注意： 仅适用于 mode: subagent 代理。

# 创建代理#

你可以使用以下命令创建新代理：

bash
opencode agent create

此交互式命令将：

询问保存代理的位置；全局或项目特定。
代理应该做什么的描述。
生成适当的系统提示和标识符。
让你选择代理可以访问的工具。
最后，使用代理配置创建一个 markdown 文件。

# 用例#

以下是不同代理的一些常见用例。

Build 代理：启用所有工具的完整开发工作
Plan 代理：分析和规划而不进行更改
Review 代理：具有只读访问权限和文档工具的代码审查
Debug 代理：专注于启用 bash 和 read 工具的调查
Docs 代理：具有文件操作但没有系统命令的文档编写

# 示例#

以下是你可能会发现有用的一些示例代理。

提示： 你有想分享的代理吗？提交 PR↗。

## 文档代理#

markdown
1<!-- ~/.config/opencode/agents/docs-writer.md -->
2---
3description: 编写和维护项目文档
4mode: subagent
5tools:
6  bash: false
7---
8
9你是一名技术作家。创建清晰、全面的文档。
10
11专注于：
12
13- 清晰的解释
14- 适当的结构
15- 代码示例
16- 用户友好的语言

## 安全审计员#

markdown
1<!-- ~/.config/opencode/agents/security-auditor.md -->
2---
3description: 执行安全审计并识别漏洞
4mode: subagent
5tools:
6  write: false
7  edit: false
8---
9
10你是安全专家。专注于识别潜在的安全问题。
11
12寻找：
13
14- 输入验证漏洞
15- 身份验证和授权缺陷
16- 数据暴露风险
17- 依赖项漏洞
18- 配置安全问题

代理

简单配置

细粒度配置

相关文档