OpenCode 子代理系统完全指南：用多 Agent 协作解锁 AI 编程的团队模式

OpenCode 子代理系统完全指南：用多 Agent 协作解锁 AI 编程的团队模式

在之前的系列文章中，我们已经深入探讨了 OpenCode 的规则系统、MCP 服务器、Agent Skills、Custom Tools 等核心功能。今天，我们来聊聊 OpenCode 中最具"团队协作"色彩的特性——Agent（代理）系统。

如果你曾觉得单个 AI 助手在处理复杂任务时力不从心——既要做架构设计，又要写代码，还要查文档——那么 OpenCode 的 Agent 系统就是为你准备的。它让你可以像管理一个开发团队一样，将不同职责分配给不同的 AI 代理，让它们各司其职、协同工作。

什么是 OpenCode Agent？

OpenCode 的 Agent 本质上是具有特定角色定位的 AI 助手实例。每个 Agent 可以拥有独立的系统提示词、模型配置、权限控制，甚至不同的"性格"（Temperature）。

Agent 分为两种类型：

Primary Agent（主代理）

主代理是你直接与之交互的主要助手。你可以通过 Tab 键在主代理之间快速切换。OpenCode 内置了两个主代理：

• Build（构建模式）：默认代理，拥有所有工具权限，适合开发工作
• Plan（计划模式）：受限代理，默认禁止文件编辑和 bash 执行，专为分析和规划设计

SubAgent（子代理）

子代理是主代理可以调用的专业化助手。你可以通过 @ 提及 来手动调用它们。OpenCode 内置了三个子代理：

• @general：通用研究型代理，可执行多步骤任务，拥有完整工具权限
• @explore：只读代理，专为快速探索代码库设计，不能修改文件
• @scout：只读代理，用于外部文档和依赖研究，可以克隆仓库到缓存区

此外，还有几个隐藏的系统代理：Compaction（上下文压缩）、Title（标题生成）、Summary（会话摘要），它们在后台自动运行，无需用户干预。

Plan 模式与 Build 模式：思考和行动的分离

这是 OpenCode Agent 系统中最实用的功能之一。在编程过程中，我们常常需要先思考再行动——Plan 和 Build 模式正是为此设计。

Plan 模式下，Agent 的所有写操作和 bash 命令都被设置为 ask 状态，这意味着它会向你提出修改建议，但不会直接执行。你可以放心地让它分析代码、设计方案、评估风险，而不必担心它擅自修改你的文件。

Build 模式则相反，它拥有完整的工具链，可以直接编辑文件、运行命令、创建新代码。

两者之间的切换只需要按下 Tab 键。一个典型的工作流是：

在 Plan 模式下让 AI 分析需求、设计方案

审查方案后切换到 Build 模式执行

发现问题后再切回 Plan 模式进行分析

这种"思考-行动-反馈"的循环，让 AI 编程变得更加可控和可靠。

如何调用子代理？

子代理的调用方式非常直观。在对话中输入 @ 符号，就会弹出自动补全菜单，列出所有可用的子代理：

@explore 帮我找到项目中所有使用 axios 的地方，并总结请求拦截器的逻辑

当你 @ 提及一个子代理时，OpenCode 会启动一个新的子会话，由该子代理独立完成任务。你可以在父子会话之间自由导航：

• <Leader>+Down：进入第一个子会话
• Right/Left：在子会话间切换
• Up：返回父会话

这种会话导航机制让你可以同时与多个 AI 代理协作，而不会让对话变得混乱。

使用 Task 工具自动委派

除了手动 @ 提及，OpenCode 的主代理还可以通过 Task 工具自动将任务委派给子代理。当主代理判断某个任务更适合由专门的子代理处理时，它会创建子代理会话，将任务分配出去，然后汇总结果。

这意味着你可以只描述需求，让主代理自行决定如何拆分任务、分派给谁。例如，一个开发任务可能被拆解为：

• 主代理负责整体架构和代码编写
• @explore 负责搜索代码库中的现有实现
• @scout 负责查阅外部依赖的文档
• @general 负责执行复杂的步骤

配置自定义 Agent

OpenCode 的强大之处在于，你可以创建自己的 Agent。有两种配置方式：

JSON 方式

在 opencode.json 的 agent 字段中定义：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码质量和潜在问题",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "prompt": "{file:./prompts/code-review.txt}",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Markdown 方式

将 Markdown 文件放在 ~/.config/opencode/agents/（全局）或 .opencode/agents/（项目级）：

---
description: 安全审计代理，检查代码中的安全漏洞
mode: subagent
model: openai/gpt-5
temperature: 0.2
permission:
  edit: deny
  bash:
    "*": deny
    "git diff": allow
    "git log*": allow
---

你是一名安全审计专家。请重点关注：
- 输入验证漏洞（SQL 注入、XSS、命令注入）
- 认证和授权缺陷
- 敏感数据泄露风险
- 依赖库安全漏洞
- 配置安全隐患

文件名为代理名称，例如 security-auditor.md 会创建一个名为 security-auditor 的代理。

关键配置选项详解

每个 Agent 都有丰富的配置选项：

• description：描述代理的用途，主代理会根据它自动判断何时调用子代理（必填）
• temperature：控制创造力和随机性，0.0-0.2 适合分析任务，0.3-0.5 适合编码，0.6-1.0 适合头脑风暴
• steps：限制最大迭代步数，超过后强制返回文本结果，适合控制成本
• model：为特定 Agent 指定不同的模型，例如用 Haiku 做规划，用 Sonnet 做实现
• permission：精细控制每个工具的权限（allow/ask/deny），支持 glob 模式匹配 bash 命令
• color：设置代理在 UI 中的主题色，方便视觉区分
• hidden：隐藏子代理，使其不出现在 @ 自动补全菜单中，仅供 Task 工具调用
• task：控制该代理可以调用哪些子代理，支持 glob 模式

实战：搭建你的 AI 开发团队

让我用一个实际场景来展示 Agent 系统的威力。假设你要为一个 Laravel 项目添加用户活动日志功能：

---
description: 数据库专家，负责 Schema 设计和迁移
mode: subagent
permission:
  edit: allow
  bash:
    "php artisan *": allow
---
你是一名 Laravel 数据库专家。专注于数据迁移、模型关系和查询优化。

---
description: 测试工程师，负责编写测试用例
mode: subagent
temperature: 0.3
permission:
  edit: allow
  bash:
    "php artisan test": allow
    "phpunit": allow
---
你是一名测试工程师。为 Laravel 编写 Feature Test 和 Unit Test。
确保覆盖正常路径和边界情况。

在对话中，你可以这样使用：

@db-expert 创建一个活动日志表迁移，包含 user_id、action、description、ip_address、user_agent 字段

@test-engineer 为活动日志功能编写测试

也可以让主代理自动调度：

为项目添加活动日志功能，跟踪用户的关键操作

主代理会自动判断需要数据库迁移、模型、控制器、测试等多方面工作，并调用相应的子代理协同完成。

注意事项与最佳实践

子代理权限隔离：为不同子代理设置不同的权限级别，审计代理只读，开发代理可写，这样可以防止误操作

合理使用 Temperature：分析任务用低温（0.1），创意任务用高温（0.7+）

prompt 文件化管理：将系统提示词放在独立的文本文件中，用 {file:./path} 引用，便于维护

模型差异化：规划任务使用快速便宜的模型，实现任务使用能力更强的模型，平衡成本与效果

Task 权限控制：如果某个子代理不应被主代理自动调用，通过 permission.task 配置精确控制

总结

OpenCode 的 Agent 系统将 AI 编程助手从"一个人"升级成了"一个团队"。通过 Plan/Build 模式分离思考与执行，通过子代理系统实现专业化分工，通过自定义配置构建专属的 AI 开发团队，这一切都在一个终端中完成。

相比其他 AI 编程工具的单代理模式，OpenCode 的多 Agent 协作架构让你可以像管理一个开发团队一样管理 AI 助手——每个代理各司其职，协同完成复杂的软件工程任务。

现在，打开你的终端，运行 opencode agent create 创建你的第一个自定义代理，体验 AI 编程的"团队模式"吧。