中文
文档
Agents

Agents

配置并使用专门的 agent。

Agent 是可以为特定任务和工作流配置的专门 AI 助手。它们让你能够使用自定义的提示词、模型和工具访问权限，创建出聚焦的工具。

提示： 使用 plan agent 来分析代码并审查建议，而不做任何代码改动。

你可以在会话期间在不同 agent 之间切换，或用 @ 提及来调用它们。

类型

OpenCode 中有两种类型的 agent：主 agent 和子 agent。

主 agent

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

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

OpenCode 内置了两个主 agent，Build 和 Plan。我们将在下面介绍它们。

子 agent

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

OpenCode 内置了三个子 agent，General、Explore 和 Scout。我们将在下面介绍它们。

内置

OpenCode 内置了两个主 agent 和三个子 agent。

使用 build

模式：primary

Build 是默认的主 agent，启用了所有工具。这是用于开发工作的标准 agent，适用于你需要对文件操作和系统命令拥有完整访问权限的场景。

使用 plan

模式：primary

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

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

当你希望 LLM 分析代码、提出改动建议或制定计划，而不对你的代码库做任何实际修改时，这个 agent 很有用。

使用 general

模式：subagent

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

使用 explore

模式：subagent

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

使用 scout

模式：subagent

一个只读 agent，用于外部文档和依赖研究。当你需要将某个依赖仓库克隆到 OpenCode 托管的缓存中、查看库的源码，或在不修改你工作区的情况下将本地代码与上游实现进行交叉比对时使用它。

使用 compaction

模式：primary

隐藏的系统 agent，将长上下文压缩为更小的摘要。它会在需要时自动运行，且无法在 UI 中选择。

使用 title

模式：primary

隐藏的系统 agent，生成简短的会话标题。它会自动运行，且无法在 UI 中选择。

使用 summary

模式：primary

隐藏的系统 agent，创建会话摘要。它会自动运行，且无法在 UI 中选择。

使用

  1. 对于主 agent，在会话期间使用 Tab 键在它们之间循环切换。你也可以使用你配置的 switch_agent 快捷键。

  2. 子 agent 可以这样调用：

    • 由主 agent 根据它们的描述自动为专门任务调用。

    • 在你的消息中 @ 提及 某个子 agent 来手动调用。例如。

      @general help me search for this function

  3. 在会话之间导航：当子 agent 创建子会话时，使用 session_child_first（默认：<Leader>+Down）从父会话进入第一个子会话。

  4. 进入某个子会话后，使用：

    • session_child_cycle（默认：Right）切换到下一个子会话
    • session_child_cycle_reverse（默认：Left）切换到上一个子会话
    • session_parent（默认：Up）返回父会话

    这让你能够在主对话和专门的子 agent 工作之间切换。

配置

你可以通过配置来自定义内置 agent 或创建你自己的 agent。Agent 可以用两种方式配置：

JSON

在你的 opencode.json 配置文件中配置 agent：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "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.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Markdown

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

  • 全局：~/.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
permission:
  edit: deny
  bash: deny
---
 
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 式迭代次数。这让希望控制成本的用户能够为 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 覆盖模型。这对于针对不同任务使用不同优化模型很有用。例如，用更快的模型做规划，用更强的模型做实现。

提示： 如果你不指定模型，主 agent 会使用 全局配置的模型，而子 agent 会使用调用它的那个主 agent 的模型。

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

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

Tools（已弃用）

tools 已弃用。对于新配置、更新和更细粒度的控制，请优先使用 agent 的 permission 字段。

允许你控制此 agent 中可用哪些工具。你可以通过将工具设为 true 或 false 来启用或禁用特定工具。在一个 agent 的 tools 配置中，true 等同于 {"*": "allow"} 权限，false 等同于 {"*": "deny"} 权限。

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

注意： agent 专属的配置会覆盖全局配置。

你也可以在旧的 tools 条目中使用通配符，一次性控制多个工具。例如，要禁用某个 MCP 服务器的所有工具：

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

了解更多关于工具的内容。

Permissions

你可以配置权限来管理一个 agent 可以采取哪些操作。每个权限键可以设置为：

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

可用的权限键有：

键它所管控的工具
readread
editwrite、edit、apply_patch
globglob
grepgrep
listlist
bashbash
tasktask
external_directory任何在项目 worktree 之外读取或写入文件的工具
todowritetodowrite、todoread
webfetchwebfetch
websearchwebsearch
lsplsp
skillskill
questionquestion
doom_loop当某个 agent 看起来卡住时的恢复提示词

read、edit、glob、grep、list、bash、task、external_directory、lsp 和 skill 接受简写操作（"allow" | "ask" | "deny"），或一个 glob/模式 → 操作的对象以实现细粒度控制。其余的键只接受简写操作。

注意： 权限键作为通配符模式与底层工具名进行匹配，所以同样的语法适用于内置工具、自定义工具和 MCP 工具 —— 例如 "mymcp_*": "deny" 会拒绝某个 MCP 服务器的每一个工具，而 "mymcp_search": "ask" 则只针对其中一个。

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 agent 中设置权限。

~/.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 将某个子 agent 从 @ 自动补全菜单中隐藏。这对于那些只应由其他 agent 通过 Task 工具以编程方式调用的内部子 agent 很有用。

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

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

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

Task permissions

用 permission.task 控制一个 agent 可以通过 Task 工具调用哪些子 agent。使用 glob 模式以实现灵活匹配。

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

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

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

提示： 用户始终可以通过 @ 自动补全菜单直接调用任何子 agent，即使该 agent 的 task 权限本应拒绝它。

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 配置中指定的任何其他选项都会被直接透传给 provider 作为模型选项。这让你能够使用 provider 特定的功能和参数。

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

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

这些附加选项是模型和 provider 特定的。请查看你的 provider 文档了解可用参数。

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

创建 agent

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

opencode agent create

这个交互式命令将会：

  1. 询问将 agent 保存在何处；全局还是项目专属。
  2. 描述该 agent 应当做什么。
  3. 生成一个合适的系统提示词和标识符。
  4. 让你选择应当允许该 agent 拥有哪些权限（你未选择的任何项都会被拒绝）。
  5. 最后，创建一个包含该 agent 配置的 markdown 文件。

用例

下面是不同 agent 的一些常见用例。

  • Build agent：启用所有工具的完整开发工作
  • Plan agent：进行分析和规划而不做改动
  • Review agent：以只读访问权限加文档工具进行代码审查
  • Debug agent：聚焦于调查，启用 bash 和 read 工具
  • Docs agent：进行文档编写，拥有文件操作但无系统命令

示例

下面是一些你可能会觉得有用的示例 agent。

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

文档 agent

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

安全审计员

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---
 
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
规则模型