Agents

配置和使用专用 agents。

Agents 是可以为特定任务和工作流配置的专用 AI 助手。它们允许你创建具有自定义提示词、模型和工具访问权限的专注工具。

提示：使用 plan agent 来分析代码和审查建议，而不进行任何代码更改。

你可以在会话期间切换 agents，或使用 @ 提及来调用它们。

类型

OpenCode 中有两种类型的 agents：primary agents 和 subagents。

Primary agents

Primary agents 是你直接交互的主要助手。你可以使用 Tab 键或配置的 switch_agent 快捷键在它们之间循环切换。这些 agents 处理你的主要对话。工具访问通过权限配置——例如，Build 启用了所有工具，而 Plan 则受到限制。

提示：你可以在会话期间使用 Tab 键在 primary agents 之间切换。

OpenCode 内置了两个 primary agents：Build 和 Plan。我们将在下面详细介绍。

Subagents

Subagents 是 primary agents 可以为特定任务调用的专用助手。你也可以通过在消息中 @ 提及 它们来手动调用。

OpenCode 内置了两个 subagents：General 和 Explore。我们将在下面详细介绍。

内置 Agents

OpenCode 内置了两个 primary agents 和两个 subagents。

使用 build

模式：primary

Build 是启用了所有工具的默认 primary agent。这是用于开发工作的标准 agent，你需要完全访问文件操作和系统命令。

使用 plan

模式：primary

一个专为规划和分析设计的受限 agent。我们使用权限系统来给你更多控制并防止意外更改。默认情况下，以下所有选项都设置为 ask：

file edits：所有写入、补丁和编辑
bash：所有 bash 命令

当你希望 LLM 分析代码、建议更改或创建计划而不对代码库进行任何实际修改时，这个 agent 非常有用。

使用 general

模式：subagent

一个用于研究复杂问题和执行多步骤任务的通用 agent。具有完整的工具访问权限（除了 todo），因此可以在需要时进行文件更改。使用它来并行运行多个工作单元。

使用 explore

模式：subagent

一个用于探索代码库的快速只读 agent。无法修改文件。当你需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时使用它。

使用 compaction

模式：primary

隐藏的系统 agent，用于将长上下文压缩成较小的摘要。它在需要时自动运行，在 UI 中不可选择。

使用 title

模式：primary

隐藏的系统 agent，用于生成简短的会话标题。它自动运行，在 UI 中不可选择。

使用 summary

模式：primary

隐藏的系统 agent，用于创建会话摘要。它自动运行，在 UI 中不可选择。

使用方法

对于 primary agents，在会话期间使用 Tab 键在它们之间循环切换。你也可以使用配置的 switch_agent 快捷键。
Subagents 可以通过以下方式调用：
- 自动：primary agents 根据其描述为特定任务调用。
- 手动：在消息中 @ 提及 subagent。例如：
```
@general help me search for this function
```
会话间导航：当 subagents 创建自己的子会话时，你可以使用以下方式在父会话和所有子会话之间导航：
- <Leader>+Right（或配置的 session_child_cycle 快捷键）向前循环：父会话 → 子会话1 → 子会话2 → … → 父会话
- <Leader>+Left（或配置的 session_child_cycle_reverse 快捷键）向后循环：父会话 ← 子会话1 ← 子会话2 ← … ← 父会话
这允许你在主对话和专用 subagent 工作之间无缝切换。

配置

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

JSON

在 opencode.json 配置文件中配置 agents：

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 文件定义 agents。将它们放在：

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

~/.config/opencode/agents/review.md

---
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.

Markdown 文件名成为 agent 名称。例如，review.md 创建一个 review agent。

选项

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

Description

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

opencode.json

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

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

Temperature

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

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

opencode.json

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Temperature 值通常范围从 0.0 到 1.0：

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

opencode.json

{
  "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。

Max steps

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

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

opencode.json

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

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

注意：旧版 maxSteps 字段已弃用。请改用 steps。

Disable

设置为 true 以禁用 agent。

opencode.json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

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

opencode.json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

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

Model

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

提示：如果你不指定模型，primary agents 使用全局配置的模型，而 subagents 将使用调用它的 primary agent 的模型。

opencode.json

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

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

Tools

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

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

注意：agent 特定配置会覆盖全局配置。

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

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

了解更多关于工具的信息。

Permissions

你可以配置权限来管理 agent 可以执行的操作。目前，edit、bash 和 webfetch 工具的权限可以配置为：

"ask" — 运行工具前提示批准
"allow" — 允许所有操作无需批准
"deny" — 禁用工具

opencode.json

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

你可以为每个 agent 覆盖这些权限。

opencode.json

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

你也可以在 Markdown agents 中设置权限。

~/.config/opencode/agents/review.md

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
 
Only analyze code and suggest changes.

你可以为特定的 bash 命令设置权限。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

这可以使用 glob 模式。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

你也可以使用 * 通配符管理所有命令的权限。由于最后匹配的规则优先，将 * 通配符放在前面，特定规则放在后面。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

了解更多关于权限的信息。

Mode

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

opencode.json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

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

Hidden

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

opencode.json

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

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

注意：仅适用于 mode: subagent 的 agents。

Task permissions

使用 permission.task 控制 agent 可以通过 Task 工具调用哪些 subagents。使用 glob 模式进行灵活匹配。

opencode.json

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

当设置为 deny 时，subagent 将从 Task 工具描述中完全移除，因此模型不会尝试调用它。

提示：规则按顺序评估，最后匹配的规则获胜。在上面的示例中，orchestrator-planner 同时匹配 *（deny）和 orchestrator-*（allow），但由于 orchestrator-* 在 * 之后，结果是 allow。

提示：用户始终可以通过 @ 自动完成菜单直接调用任何 subagent，即使 agent 的任务权限会拒绝它。

Color

使用 color 选项自定义 agent 在 UI 中的视觉外观。这会影响 agent 在界面中的显示方式。

使用有效的十六进制颜色（例如 #FF5733）或主题颜色：primary、secondary、accent、success、warning、error、info。

opencode.json

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

Top P

使用 top_p 选项控制响应多样性。这是控制随机性的 temperature 替代方案。

opencode.json

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

值范围从 0.0 到 1.0。较低的值更集中，较高的值更多样化。

Additional

你在 agent 配置中指定的任何其他选项将直接传递给提供商作为模型选项。这允许你使用提供商特定的功能和参数。

例如，使用 OpenAI 的推理模型，你可以控制推理强度：

opencode.json

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

这些额外选项是模型和提供商特定的。查看你的提供商文档了解可用参数。

提示：运行 opencode models 查看可用模型列表。

创建 agents

你可以使用以下命令创建新的 agents：

opencode agent create

这个交互式命令将：

询问在哪里保存 agent：全局或项目特定。
agent 应该做什么的描述。
生成适当的系统提示和标识符。
让你选择 agent 可以访问哪些工具。
最后，创建一个包含 agent 配置的 markdown 文件。

使用场景

以下是不同 agents 的一些常见使用场景。

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

示例

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

提示：你有想要分享的 agent 吗？提交 PR (opens in a new tab)。

文档 agent

~/.config/opencode/agents/docs-writer.md

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

安全审计 agent

~/.config/opencode/agents/security-auditor.md

---
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

规则模型