Agent 系统

两类 Agent

类型	说明	切换方式
Primary Agent（主 Agent）	直接对话的主体，负责主对话	`Tab` 键循环切换，或配置的 `switch_agent` 快捷键
Subagent（子 Agent）	由主 Agent 调用的专项助手，也可 `@mention` 手动调用	`@agent名`

内置 Agent 清单

Primary（2 个）

名称	说明
build	默认主 Agent，全工具权限，标准开发场景
plan	只读分析型，`edit`/`bash` 默认设为 `ask`，适合先分析不动代码

Subagent（3 个可见 + 3 个隐藏系统 Agent）

名称	说明
general	通用子 Agent，除 todo 外全权限，可并行跑多个任务单元
explore	只读，快速按 pattern 找文件/关键词搜索，不能改文件
scout	只读，专职外部文档/依赖调研：clone 依赖仓库到 OpenCode 缓存、查库源码、和本地代码比对，不改工作区
compaction（隐藏）	系统自动压缩长上下文，不可在 UI 选择
title（隐藏）	系统自动生成 session 标题
summary（隐藏）	系统自动生成 session 摘要

Claude Code 对照：build≈默认主循环，plan≈Plan Mode，general≈general-purpose subagent，explore≈Explore agent。三者概念高度相似，命名与权限模型基本对应。

子 Agent 的会话导航

子 Agent 创建子 session 后，用 session_child_first（默认 <Leader>+Down）进入
子 session 内：session_child_cycle(→)/session_child_cycle_reverse(←) 切换同级子 session，session_parent(↑) 返回父 session

配置方式

支持两种定义方式，等价：

JSON（写在 opencode.json 的 agent 字段）：

{
  "agent": {
    "build": { "mode": "primary", "model": "anthropic/claude-sonnet-4-20250514", "permission": {"edit":"allow","bash":"allow"} },
    "code-reviewer": { "description": "...", "mode": "subagent", "permission": {"edit":"deny"} }
  }
}

Markdown（文件名即 Agent 名）：放在 ~/.config/opencode/agents/ 或 .opencode/agents/，frontmatter 定义元数据，正文即 system prompt。这与 Claude Code 的 Skill/Subagent 定义方式（frontmatter + 正文）思路一致。

关键配置项

配置项	作用
`description`	必填，决定何时被主 Agent 自动调用
`temperature`	0.0-0.2 聚焦确定，0.6-1.0 发散创意；默认多数模型 0，Qwen 系 0.55
`steps`（原 `maxSteps`，已废弃）	限制单个 Agent 最大迭代步数，超限后强制输出总结+剩余任务建议
`disable`	禁用该 Agent
`prompt`	自定义 system prompt 文件路径（`{file:...}`）
`model`	覆盖模型；子 Agent 未指定则继承调用它的主 Agent 模型
`mode`	`primary`/`subagent`/`all`（默认 `all`）
`hidden`	仅对 subagent 生效，隐藏于 `@` 自动补全，但仍可被主 Agent 通过 Task 工具调用
`permission.task`	用 glob 控制该 Agent 可调用哪些子 Agent，最后匹配规则生效（后写的优先）
`color`/`top_p`	UI 展示色 / 采样多样性
其他任意字段	直接透传给 model provider（如 OpenAI `reasoningEffort`）

权限系统（Permission）

三态：ask（需批准）/ allow（放行）/ deny（禁用）。

Key	网关工具
`read`	read
`edit`	write, edit, apply_patch
`glob`/`grep`/`list`	对应工具
`bash`	bash（支持按具体命令/glob 细粒度控制，如 `"git push": "ask"`）
`task`	task（子 Agent 调用权限）
`external_directory`	读写工作区外文件的任意工具
`todowrite`	todowrite, todoread
`webfetch`/`websearch`/`lsp`/`skill`/`question`	对应工具
`doom_loop`	Agent 卡死时的恢复提示

规则用通配符匹配工具名，* 通配符 + 具体规则时最后一条匹配规则生效（建议把 * 放最前）。

创建新 Agent

交互式命令：opencode agent create，依次询问保存位置（全局/项目）、描述、权限勾选（未勾选=deny）、生成 markdown 文件。

Skill（Agent Skills）

定义文件：SKILL.md，遵循 frontmatter + 正文的懒加载机制——与 Claude Code Skill 机制几乎一致
存放位置：全局/项目 skills/ 目录
通过 skill permission key 控制是否可用

Rules（自定义指令）

项目级：AGENTS.md（等价于 Claude Code 的 CLAUDE.md）
全局级：~/.config/opencode/AGENTS.md
显式声明兼容 Claude Code：可读取 .claude 目录下的 prompt 与 skills（OPENCODE_DISABLE_CLAUDE_CODE 系列环境变量可关闭）
支持 instructions 配置项引入外部文件/glob（如 CONTRIBUTING.md、.cursor/rules/*.md）

关联

索引 — 返回总索引
配置系统 — Agent 的配置最终落在 opencode.json 的多层合并体系里
工具与集成 — Agent 权限门控的是这里列出的工具
对比Claude-Code — 与 Claude Code Agent/Skill 体系对照

来源

https://opencode.ai/docs/agents、https://opencode.ai/docs/skills、https://opencode.ai/docs/rules（dev 分支）。整理：赵卫国 2026-07-07。

Wiki AI

目录

OpenCode Agent 系统