Agents

为不同任务配置专用 Agent。

英文原文较长，这里按照结构完整翻译，保留关键术语（agent / subagent 等）。

Agents 是 OpenCode 中“角色 + 能力 + 配置”的组合，用于针对不同任务（开发、规划、审查等）定制行为。

你可以：

使用内置 Agent（如 build、plan 等）；
在配置文件中定义自定义 Agent；
通过 Markdown 文件管理更复杂的 Agent 配置和说明。

基本概念

一个 Agent 通常包含：

使用的模型（model）
系统提示词（prompt / instructions）
可用工具（tools）
权限（permissions）
是否作为主 Agent 还是子 Agent（subagent）

你可以在 TUI 底部看到当前选中的 Agent，并通过快捷键/命令切换。

在配置中定义 Agent

在 opencode.json / opencode.jsonc 中使用 agent 字段：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // review-only，不允许直接修改文件
        "write": false,
        "edit": false
      }
    }
  }
}

这里我们定义了一个 code-reviewer Agent：

使用指定模型；
使用特定系统提示词；
禁用改写文件相关工具，只允许阅读和分析。

Markdown 方式定义 Agent

也可以在以下目录中通过 Markdown 定义 Agent：

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

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.

YAML frontmatter 中的字段会被解析为 Agent 配置，正文可以作为说明文档或额外指令。

默认 Agent

可以通过 default_agent 设置默认使用的 Agent：

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

要求：

默认 Agent 必须是“主 Agent”（primary），不能是 subagent；
可以是内置的 build、plan，也可以是你自定义的 Agent；
如果指定的 Agent 不存在或是 subagent，OpenCode 会回退到 build 并给出警告。

该设置会在 TUI、CLI（opencode run）、桌面应用和 GitHub Action 中统一生效。

工具与权限（per Agent）

Agent 可以覆盖全局工具/权限配置，只在特定 Agent 中启用或禁用某些工具。

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

Agent 内的 permission 会和全局 permission 合并，且优先级更高。

关于权限系统的详情见：Permissions 文档。

同理，agent.tools 也可以单独为某个 Agent 打开/关闭工具，比如按 Agent 控制 MCP 服务器，详见 MCP 文档。

Subagents（子 Agent）

为避免污染主对话上下文，你可以让某些 Agent 作为“子 Agent”运行，专门处理子任务。常见场景：

代码审查子 Agent
重构/格式化子 Agent
只读分析子 Agent（不改任何文件）

通过配置 mode: subagent 或在 JSON 中使用 mode: "subagent" 即可。

当调用带有 mode: subagent 的 Agent 时：

会在单独的上下文中运行；
可以选择是否继承主会话历史；
任务完成后只把结果合并回主会话。

你可以通过：

在命令中显式指定 Agent；
或在自定义命令（command）中指定 agent 字段；

来触发特定 subagent。

更多关于 subagent 的使用模式，参见英文文档中的 subtask、task 工具说明（本仓库里 commands.mdx / permissions.mdx 等已有中文版本）。