Agents（智能代理）
Agents 是一种专门化的 AI 助手，可以针对特定任务和工作流进行配置。它们允许你创建聚焦型工具，支持自定义 prompts、models 和 tools 访问权限。
你可以在一个 session 中在不同 agents 之间切换，或者通过 @ mention 的方式来调用它们。
Types（类型）
在 OpenCode 中有两种类型的 agents：primary agents 和 subagents。
Primary agents（主代理）
Primary agents 是你直接交互的主要助手。你可以使用 Tab 键，或者你配置的 switch_agent 快捷键，在它们之间循环切换。这些 agents 会处理你的主对话，并且可以访问所有已配置的 tools。
OpenCode 内置了两个 primary agents：Build 和 Plan。下面会分别介绍它们。
Subagents（子代理）
Subagents 是专门化的助手，primary agents 可以在特定任务中调用它们。你也可以在消息中通过 @ mention 的方式手动调用它们。
OpenCode 内置了两个 subagents：General 和 Explore。下面会分别介绍。
Built-in（内置代理）
OpenCode 内置了两个 primary agents 和两个 subagents。
Build
Mode: primary
Build 是默认的 primary agent，启用了所有 tools。它是进行开发工作的标准 agent，你可以完整访问文件操作和系统命令。
Plan
Mode: primary
Plan 是一个用于规划和分析的受限 agent。系统通过权限机制来提升可控性，防止产生意外修改。
默认情况下，以下权限都设置为 ask：
file edits：所有写入、patch 和编辑操作bash：所有 bash 命令
当你希望 LLM 分析代码、提出修改建议或制定计划，但又不希望实际修改代码库时，这个 agent 非常适合。
General
Mode: subagent
一个通用型 agent，用于研究复杂问题、搜索代码以及执行多步骤任务。当你需要搜索关键词或文件，并且不确定第一次就能找到正确结果时，可以使用它。
Explore
Mode: subagent
一个专门用于快速探索 codebase 的高性能 agent。当你需要按模式查找文件、搜索代码关键词，或者快速回答有关 codebase 的问题时，非常适合使用。
Usage（使用方式）
对于 primary agents，可以在 session 中使用 Tab 键进行切换，也可以使用你配置的
switch_agent快捷键。Subagents 的调用方式：
- 自动调用：primary agents 会根据任务描述自动调用合适的 subagent。
手动调用：在消息中通过 @ mention 一个 subagent，例如：
@general help me search for this function
Session 导航：当 subagents 创建了自己的 child sessions 后，你可以在 parent session 和所有 child sessions 之间切换：
+Right （或你配置的session_child_cycle快捷键）：按顺序在 parent → child1 → child2 → … → parent 之间切换+Left （或你配置的session_child_cycle_reverse快捷键）：按相反顺序在 parent ← child1 ← child2 ← … ← parent 之间切换
这样可以在主对话和子代理的专项工作之间无缝切换。
Configure（配置）
你可以通过配置来自定义内置 agents，或者创建自己的 agents。配置方式有两种：
JSON
在 opencode.json 配置文件中配置 agents：
（示例配置保持原样，不再重复翻译）
Markdown
你也可以使用 markdown 文件来定义 agents，把文件放在：
- 全局：
~/.config/opencode/agent/ - 项目级：
.opencode/agent/
Markdown 文件名会成为 agent 名称。例如，review.md 会创建一个名为 review 的 agent。
Options（配置项）
下面详细说明各个配置项。
Description（描述）
使用 description 配置项来描述 agent 的用途和适用场景。
这是一个 必填 配置项。
Temperature（温度）
使用 temperature 配置来控制 LLM 输出的随机性和创造性。
较低的值会让回答更加聚焦和确定；较高的值会提高创造力和多样性。
Temperature 的常见取值范围是 0.0 到 1.0：
- 0.0–0.2：高度聚焦、结果稳定，适合代码分析和规划
- 0.3–0.5：适度平衡，适合一般开发任务
- 0.6–1.0：更具创造性，适合头脑风暴和探索
如果未指定 temperature，OpenCode 会使用 model 的默认值；通常大多数 models 为 0，Qwen models 为 0.55。
Max steps（最大步数）
用于控制 agent 在被强制只返回文本之前，最多可以执行多少次 agentic 迭代。这有助于希望控制成本的用户限制 agent 的行为次数。
如果未设置，agent 会持续迭代，直到 model 自行停止或用户中断 session。
当达到限制时，agent 会收到一个特殊的 system prompt，要求它以总结形式返回当前工作成果以及剩余建议任务。
Disable（禁用）
将其设置为 true 可以禁用该 agent。
Prompt（提示词）
使用 prompt 配置项为 agent 指定自定义 system prompt 文件，用于定义该 agent 的行为和职责。
路径相对于配置文件所在位置，无论是全局 OpenCode config 还是项目级 config 都适用。
Model（模型）
使用 model 配置项为该 agent 指定不同的 model，适用于为不同任务选择性能或速度更优的模型。
在 OpenCode 中，model ID 使用 provider/model-id 格式。例如在使用 OpenCode Zen 时，可以使用 opencode/gpt-5.1-codex。
Tools（工具）
通过 tools 配置项控制该 agent 可以使用哪些 tools。可以通过 true 或 false 来启用或禁用具体工具。
你也可以使用通配符（wildcards）来一次性控制多个 tools。
更多信息可参考 [tools 文档]。
Permissions（权限）
可以通过 permissions 来管理 agent 可以执行哪些操作。目前支持配置 edit、bash 和 webfetch：
"ask"：执行前需要确认"allow"：无需确认，允许执行"deny"：完全禁止
权限可以在全局配置中设置，也可以在 agent 级别进行覆盖。 同时支持针对具体 bash 命令或 glob pattern 进行细粒度控制。
规则匹配遵循：最后一个匹配规则生效（last matching rule wins）。
Mode（模式）
使用 mode 配置项控制 agent 的使用方式：
primarysubagentall（默认）
Hidden（隐藏）
通过设置 hidden: true，可以让 subagent 不出现在 @ 自动补全菜单中，适用于仅供内部 agent 通过 Task tool 调用的场景。
Task permissions（任务权限）
通过 permission.task 控制一个 agent 可以通过 Task tool 调用哪些 subagents，支持 glob pattern。
当设置为 deny 时，该 subagent 会从 Task tool 描述中完全移除，模型不会尝试调用它。
Additional（额外参数）
任何额外的配置项都会直接透传给 model provider，允许使用 provider 专有参数。
例如，在 OpenAI reasoning models 中，可以配置 reasoningEffort 和 textVerbosity。
具体可用参数请参考对应 provider 的文档。
Create agents（创建 agent）
可以使用以下命令创建新的 agent：
opencode agent create
该交互式命令将：
- 询问保存位置（全局或项目级）
- 询问 agent 的功能描述
- 自动生成合适的 system prompt 和 identifier
- 让你选择 agent 可访问的 tools
- 最终创建一个包含 agent 配置的 markdown 文件
Use cases（使用场景）
常见的 agent 使用场景包括：
- Build agent：启用所有 tools，适合完整开发工作
- Plan agent：仅分析和规划，不修改代码
- Review agent：只读代码审查，支持文档工具
- Debug agent：专注问题排查，启用 bash 和读取工具
- Docs agent：编写文档，可操作文件但不执行系统命令
Examples（示例）
以下是一些实用的 agent 示例。
Documentation agent（文档代理）
用于编写和维护项目文档的 subagent。
Security auditor（安全审计代理）
用于执行安全审计并识别潜在安全漏洞的 subagent，重点关注：
- 输入校验漏洞
- 身份认证与授权缺陷
- 数据暴露风险
- 依赖项漏洞
- 配置安全问题
若有收获，就点个赞吧
0 人点赞
