在AI辅助编程快速迭代的今天，单一智能体已难以应对日益复杂的软件开发需求。OpenCode —— 这款开源、厂商中立的AI编程智能体 —— 通过其精巧的 Subagent（子智能体）体系，正在重新定义开发者与AI的协作方式。
本文将从首批资深使用者的视角，系统性地为你拆解 OpenCode Subagent 的设计理念、配置方法、实战案例与最佳实践。无论你是刚转型的程序员，还是已有经验的AI工具使用者，这篇文章都能帮你建立起对 Subagent 体系的完整认知。
一、什么是 Subagent？为什么需要它？
简单来说，Subagent 是 OpenCode 中可以被主智能体（Primary Agent）“召唤”的专业化助手。它们拥有独立的上下文窗口、独立的系统提示词、独立的工具权限，彼此隔离运作。
这种架构解决了一个核心问题：一个通用智能体难以在所有任务上都表现出色。就像人类的软件开发团队需要前端工程师、后端工程师、测试工程师各司其职一样，Subagent 体系让每个智能体只专注于自己最擅长的领域。
关键优势
职责分离：规划智能体只做架构设计，编码智能体只写代码，审查智能体只审查质量。每个智能体的上下文窗口不会被无关信息污染。
权限隔离：审查智能体可以被设置为只读权限（不能修改文件），安全审查智能体不能执行Shell命令。你不用担心一个智能体"越界操作"。
模型差异化：可以为不同的 Subagent 指定不同的模型。比如让轻量模型（Haiku/GPT-4o-mini）处理代码搜索，让强推理模型（Sonnet/O1）处理复杂编码，在成本和效果之间取得最优平衡。
并行执行：Subagent 可以在后台独立运行，主智能体可以同时派发多个子任务，然后汇总结果。
独立上下文：每个 Subagent 拥有独立的会话上下文，不会相互污染。一个 Subagent 的中间推理过程不会影响另一个的判断。
二、OpenCode 的智能体类型体系
OpenCode 将智能体分为两大类：Primary Agent（主智能体） 和 Subagent（子智能体）。
Primary Agent（主智能体）
主智能体是你直接交互的对话对象。OpenCode 内置了两个主智能体：
- Build 智能体：完整的工具权限，可以读写文件、执行命令、搜索代码。适合大多数编码任务。
- Plan 智能体：受限的权限（默认禁止编辑和执行命令）。专注于架构规划、代码分析、方案设计。这个分离的设计理念很值得关注 —— 它强制你在"规划阶段"不要动手编码，先想清楚再做。
Subagent（子智能体）
子智能体是主智能体可以调用的专用助手。OpenCode 内置了三个 Subagent：
General（通用型）
模式为 subagent，拥有完整的工具权限（除 todo 工具外），可以修改文件。适合执行多步骤的复杂子任务，可以并行运行多个工作单元。当你需要让主智能体同时在多个方向上推进工作时，General 是最常用的选择。
Explore（探索型）
模式为 subagent，纯只读权限，不能修改任何文件。专为快速浏览代码库而设计 —— 按模式查找文件、搜索代码关键词、回答关于代码库的问题。它速度快、专注，不会因为想修改代码而分心。
Scout（侦察型）
模式为 subagent，也是只读权限，但用途不同。它用于外部文档和依赖库研究 —— 克隆依赖仓库到 OpenCode 的托管缓存、审查库源码、交叉比对本地代码与上游实现。当你需要搞清楚某个第三方库的内部实现时，Scout 是最佳选择。
三、创建自定义 Subagent 的三种方式
你可以通过三种不同的方式创建自己的 Subagent。每种方式适用于不同的场景。
方式一：通过 opencode.json 配置文件
这种方式适合简单配置，直接在项目根目录的 opencode.json 中添加 agent 字段：
{
"agent": {
"code-reviewer": {
"description": "审查代码质量和最佳实践",
"mode": "subagent",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "你是一名资深代码审查员...",
"permission": {
"edit": "deny",
"bash": "deny"
}
}
}
}
这是最快捷的方式，但受限于 JSON 格式，不适合编写超长的系统提示词。
方式二：通过 .opencode/agents/ 目录的 Markdown 文件
这是推荐的方式，特别适合需要详细系统提示词的复杂 Subagent。文件放在以下两个位置：
- 全局配置：
~/.config/opencode/agents/ - 项目配置：
.opencode/agents/
每个 Markdown 文件定义一个 Subagent，文件名就是智能体名称。例如创建一个 test-writer.md 文件：
---
description: 编写全面覆盖的测试用例
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
permission:
edit: allow
bash: allow
task: false
---
你是一名资深测试工程师。遵循以下原则：
第一，RED 阶段：先编写失败的测试用例，运行确认失败。
第二，GREEN 阶段：编写最小实现代码使测试通过。
第三，REFACTOR 阶段：优化代码结构但保持测试通过。
测试覆盖要求：所有公共方法必须有单元测试；关键路径必须有集成测试；边界条件和异常场景必须覆盖。
编写测试时优先使用 Arrange-Act-Assert 模式。
这种方式最灵活，系统提示词可以写任意长，且文件名就是智能体名称，便于管理和分享。
方式三：通过 opencode agent create 交互式命令
如果你不想手写配置，可以使用交互式命令：
opencode agent create
这个命令会引导你一步步完成：
- 选择存放位置（全局还是项目）
- 描述智能体用途
- 自动生成系统提示词
- 选择允许的权限（未选的权限默认禁止）
- 创建 Markdown 文件
你也可以通过参数实现非交互式创建：
opencode agent create \
--path .opencode/agents \
--description "前端React专家" \
--mode subagent \
--tools "read,edit,glob,grep,bash" \
--model anthropic/claude-sonnet-4-20250514
四、Subagent 的权限体系
Subagent 的权限控制是它的核心安全特性。权限系统基于**“默认拒绝”**的原则 —— 你没有明确允许的操作，就是禁止的。
三级权限值
| 权限值 | 含义 |
|---|---|
| allow | 允许操作，无需审批 |
| ask | 需要用户审批后才允许 |
| deny | 完全禁用 |
可用权限键
| 权限键 | 控制目标 |
|---|---|
| read | 读取文件 |
| edit | 写入和编辑文件 |
| glob | 文件模式搜索 |
| grep | 文件内容搜索 |
| list | 列出目录 |
| bash | 执行Shell命令 |
| task | 向其他 Subagent 派发任务 |
| websearch | 网络搜索 |
| webfetch | 抓取网页 |
| skill | 加载技能 |
| lsp | 语言服务器协议 |
典型的只读审查型 Subagent 配置
---
description: 安全审计专家
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
edit: deny
bash: deny
task: deny
---
精细的通配符权限控制
更精细的权限控制支持通配符模式和对象语法。例如限制某些 Subagent 只能调用特定名称的子智能体：
{
"agent": {
"orchestrator": {
"mode": "primary",
"permission": {
"task": {
"*": "deny",
"orchestrator-*": "allow",
"code-*": "ask"
}
}
}
}
}
在这个配置中，orchestrator 主智能体默认不能调用任何 Subagent，但名称以 orchestrator- 开头的可以直接调用，名称以 code- 开头的需要用户审批。权限规则按顺序匹配，最后匹配的规则生效。
五、调用 Subagent 的两种方式
方式一：手动通过 @ 提及
在对话中直接 @ 智能体名称，就像聊天群里 @ 某人：
@explore 帮我找一下项目中所有处理认证的代码文件
@general 重构这个函数的实现方式
但需要注意的是，@ 提及实际上是一个**“建议"而非"硬派发”**。主智能体可能选择自己处理请求，而不实际创建 Subagent 会话。如果需要确保 Subagent 被调用，建议使用更明确的措辞：“创建一个 general Subagent 来处理这个任务”。
方式二：主智能体自动调用
这是更常用的方式 —— 在主智能体的系统提示词中描述应该在什么场景下调用哪个 Subagent，然后主智能体在遇到匹配的任务时自动通过 Task 工具派发。例如：
---
mode: primary
model: anthropic/claude-sonnet-4-20250514
---
你是一名架构师。根据任务类型派发给对应的专家：
- 当用户要求代码审查时，使用 @code-reviewer
- 当用户要求安全审计时，使用 @security-reviewer
- 当用户开始新功能开发时，使用 @planner
- 当用户提到测试时，使用 @tdd-guide
Subagent 启动后，会在一个独立的会话中工作。你可以通过快捷键在会话树中导航：
| 快捷键 | 功能 |
|---|---|
| Ctrl+Down | 进入第一个子会话 |
| Right / Left | 在同级子会话间切换 |
| Up | 返回父会话 |
六、Subagent 到 Subagent 的级联委托
在最新的 OpenCode 版本中，Subagent 可以进一步委托任务给其他 Subagent，形成多级层次化的智能体协作结构。这一功能默认是关闭的，需要在 opencode.json 中显式启用。
为智能体设置 task_budget（任务预算）来控制委托深度：
{
"agent": {
"partner": {
"mode": "subagent",
"task_budget": 10,
"permission": {
"task": {
"assistant-*": "allow"
}
}
},
"assistant-sonnet": {
"mode": "subagent",
"task_budget": 3
},
"assistant-flash": {
"mode": "subagent",
"task_budget": 2
}
}
}
在这个层级结构中：
partner有 10 次调用预算，可以调用assistant-*系列子智能体assistant层级的智能体只能调用 2-3 次，防止无限循环- 还有一个全局
level_limit深度限制（默认 5 层）
这种设计使得你可以构建类似 “首席架构师 -> 高级工程师 -> 执行工程师” 的团队层级，每一层都有预算约束。
七、隐藏 Subagent 与 Task 权限
有时候你需要创建仅供程序化调用、不应出现在 @ 自动补全菜单中的 Subagent。设置 hidden: true 即可：
---
description: 内部专用：数据迁移工具
mode: subagent
hidden: true
permission:
bash: allow
---
隐藏后的 Subagent 仍然可以被主智能体通过 Task 工具调用，但不会出现在 @ 菜单中，适合内部基础设施类智能体。
Task 权限可以用通配符精确控制哪些 Subagent 可以被哪些智能体调用：
{
"agent": {
"build": {
"permission": {
"task": {
"db-*": "allow"
}
}
}
}
}
八、实战案例：构建一个微服务开发团队
让我用一个小型微服务开发场景来展示 Subagent 的完整应用。
假设你要开发一个用户管理服务，包含 API 端点、数据库交互、单元测试。你可以创建以下 Subagent：
创建 API 设计专家
---
description: RESTful API 设计专家
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
read: allow
edit: allow
bash: deny
task: false
---
你是一名 API 设计专家。遵循 RESTful 最佳实践：
- 资源命名使用复数名词
- 使用标准的 HTTP 方法语义
- 版本控制通过 URL 路径实现
- 错误响应使用一致的结构
---
创建数据库模型设计专家
---
description: 数据库模型设计专家
mode: subagent
permission:
read: allow
edit: allow
bash: allow
---
你专注于数据库设计。优先使用 ORM，确保索引覆盖查询模式，考虑迁移脚本的前向和后向兼容性。
创建测试编写专家
---
description: 测试编写专家
mode: subagent
model: anthropic/claude-haiku-4-20250514
temperature: 0.2
permission:
read: allow
edit: allow
bash: allow
---
你遵循测试金字塔原则。每个端点至少包含：
- 正常路径测试
- 错误输入测试
- 边界条件测试
创建 Orchestrator 主智能体
---
mode: primary
model: anthropic/claude-sonnet-4-20250514
---
你是一个微服务开发团队负责人。项目启动时，先调用 @api-designer 设计 API 接口。API 设计通过后，并行调用 @db-designer 设计数据库模型和 @test-writer 为接口编写测试。确保每个环节的输出都经过审查。
实际对话流程
你：开发一个用户注册接口
主智能体：
1. 调用 @api-designer 设计接口
2. @api-designer 创建了 POST /api/v1/users 的设计方案
3. 方案评审通过
4. 并行推进实现：
- @db-designer 创建 User 实体和数据库迁移脚本
- @test-writer 为注册接口编写了三种场景的测试用例
5. 主智能体实现控制器逻辑
6. 运行测试全部通过
整个流程自动完成，你只需给出需求。
九、Subagent 与 Skills 的配合
Subagent 和 Skills 是 OpenCode 中两个互补的扩展机制：
- Subagent 控制**“谁来做事”**（角色和权限）
- Skills 控制**“怎么做事的标准流程”**（知识和方法）
Skills 是存放在 .opencode/skills/ 目录下的 SKILL.md 文件。当主智能体或 Subagent 遇到匹配的任务时，会自动通过 skill 工具加载对应的 Skill。
配合场景示例
一个典型的配合场景：
@security-reviewerSubagent 负责安全审查（角色）security-review-guidelinesSkill 提供审查清单和 OWASP 检查项（知识）- Subagent 决定"我需要做安全审查"，Skill 告诉它"按什么标准审查"
权限控制
可以通过权限体系精确控制哪些智能体能加载哪些 Skills：
permission:
skill:
"*": allow
"internal-*": deny
"experimental-*": ask
十、最佳实践总结
经过实际使用，我总结出以下关键经验：
1. 先从小处开始
先为最频繁的任务创建一个 Subagent，比如代码审查或测试编写。迭代优化系统提示词后再扩展。
2. 权限遵循最小化原则
只给 Subagent 完成其任务所需的最小权限集。审查型 Subagent 默认禁用编辑和执行权限。
3. 模型选择差异化
高频简单任务用低成本模型（如 Haiku），复杂推理任务用强模型（如 Sonnet）。不同 Subagent 可以使用不同厂商的模型。
4. 编写高质量的系统提示词
包含具体的行为规范，给出正反示例。明确 Subagent 应该在什么场景下被触发，以及应该输出什么格式的结果。
5. 主智能体提示词中编排 Subagent
在主智能体的系统提示词中清晰定义任务路由规则，让 Subagent 的调用自动化。
6. 注意预算控制
在多级委托场景下设置合理的 task_budget，防止无限循环和失控的 API 调用成本。
7. 注意上下文隔离
独立的上下文窗口意味着每个 Subagent 的上下文是独立的 —— 主智能体塞满上下文时不会影响 Subagent 的推理质量。
8. @ 提及不保证调用
如果你需要确保 Subagent 被实际创建，使用明确的指令措辞，而不仅仅是通过 @ 提及。
结语
OpenCode 的 Subagent 体系代表了一种新的 AI 编程范式 —— 从单个"超级智能体"转向多个"专业智能体"的协作网络。Subagent 不是取代开发者的判断力，而是将通用 AI 能力专业化、可控化。通过精心设计的 Subagent 体系，一个复杂的软件开发任务可以被拆解为多个专注于单一职责的子任务，互相协作，互为审查。
随着 Subagent-to-Subagent 委托、Agent Teams、持久化会话等功能的持续进化，我们正在从"一个人带着一个AI助手"走向"一个人带领一个AI团队"的全新时代。
参考链接
如果你觉得这篇文章有帮助，欢迎分享和讨论。作为一名从传统开发转型 AI 辅助开发的程序员，我认为 Subagent 体系将是未来一年内每个开发者都应该掌握的核心技能之一。