opencode-map
English
← guides/

opencode 的 agent:内置 agent 与自定义 subagent

进阶最后更新: 2026年10月21日

opencode 把工作分给两类 agent:直接对话的主 agent(primary)和被委派任务的 subagent。两类都可以自定义——本文先讲内置 agent,再讲怎么写自己的。

内置主 agent

会话中按 Tab 循环切换主 agent(Shift+Tab 反向)。

  • build——默认 agent,所有工具开放,日常开发用它。
  • plan——受限的规划分析 agent。默认拒绝修改 plan 目录 ~/.opencode/plan/ 之外的文件(edit/write/patch 直接拒绝,不弹确认),保留 question 工具向你提问,shell 命令遵循你的 permission 配置。

用 plan 做只读的方案评审与设计,定稿后 Tab 回 build 执行。

plan 的默认权限在你的顶层 permission 之前生效,最后命中的规则胜出——所以全局 "edit": "allow" 会把 plan 也放开。要保住只读,给它单独设权限:

{
  "agent": {
    "plan": {
      "permission": {
        "edit": { "*": "deny", "~/.opencode/plan/*": "allow" },
        "shell": "ask"
      }
    }
  }
}

内置 subagent

主 agent 会按 description 自动调用 subagent;你也可以在消息里用 @ 提及手动调用:

@general 帮我找一下这个函数
  • general——全工具权限,处理复杂问题和多步骤任务,可并行执行多份工作。
  • explore——快速只读代码库探索:按模式找文件、搜关键字、回答代码问题。
  • scout——只读外部调研:把依赖仓库克隆进 opencode 托管缓存,翻库源码、对照上游实现,不碰你的工作区。

另有三个隐藏系统 agent(compaction、title、summary)自动处理上下文压缩和会话元数据,不可手动选择。

subagent 在子会话中运行。父会话里按 leader+down 进入第一个子会话(session_child_first),right/left 在子会话间切换,up 回到父会话。这些默认值来自 tui.json 的键位配置。

自定义 agent

两种方式。Markdown——把文件放进 .opencode/agents/(项目级)或 ~/.config/opencode/agents/(全局),文件名即 agent 名:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  shell: deny
---

You are in code review mode. Focus on quality, bugs, performance, and security.
Provide constructive feedback without making direct changes.

或者 JSON——opencode.json 里的 agent 键:

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": { "edit": "deny" }
    }
  }
}

也可以跑交互命令 opencode agent create:选全局还是项目、写描述、生成 system prompt、勾选权限,最后落成 markdown 文件。

常用配置项

键 作用
description agent 做什么、何时用。必填。主 agent 靠它挑 subagent。
mode primary、subagent 或 all(默认)。
model provider/model-id 覆盖。未设置时 subagent 继承调用方的模型。
prompt 自定义 system prompt——内联或 {file:./prompts/x.txt}(相对配置文件)。
permission 按工具设 allow/ask/deny,shell、edit 等键支持 glob 模式。
steps 限制 agentic 迭代次数,到顶后 agent 只能用文本总结。
temperature / top_p 采样控制。
hidden 把 subagent 从 @ 补全里隐藏,仍可通过 Task 工具调用。
color UI 颜色——十六进制或主题色名。
disable 停用该 agent。

tools 已废弃,新配置用 permission。权限键包括 read、edit、glob、grep、list、shell、task、webfetch、websearch、lsp、skill、question、external_directory、doom_loop。permission.task 用 glob 规则控制 agent 能启动哪些 subagent;用户始终可以用 @ 提及直接调用任意 subagent。

v2 差异

v2 文档重构了 agent 配置:agents(复数)键替代 agent,prompt 改为 system,permission 和 tools 并入 permissions 下的 {action, resource, effect} 有序规则列表,disable 改名 disabled,variant 并入模型引用变成 provider/model#high,temperature/top_p/options 移入 request.body(保留但暂不随请求发送——生效的请求设置请配置在 provider/model/variant 上),maxSteps 改为 steps。v2 没有内置 scout,default_agent 沿用 v1 语义继续指定启动时的主 agent;嵌套目录计入 agent 名——.opencode/agents/team/reviewer.md 生成 team/reviewer。

延伸阅读