OpenCode Agent 与 Sub-Agent 系统完全指南

OpenCode 的 Agent 系统是其最核心的架构设计之一。不同于简单的「对话机器人」，OpenCode 通过 Agent 机制实现了多角色分工、权限隔离和并行协作。本文将深入解析 Agent 的配置、Sub-Agent 的工作原理以及多 Agent 协作的最佳实践。

Agent 是什么？

在 OpenCode 中，Agent 是一个拥有特定能力集的 AI 角色。每个 Agent 可以：

• 使用不同的工具集（读文件、写代码、执行命令等）
• 拥有独立的权限边界（能做什么、不能做什么）
• 遵循特定的行为指令（Rules、Skills）
• 运行在独立的上下文中（隔离记忆）

Sub-Agent（子代理）则是由主 Agent 调度的下级 Agent，可以并行处理多个子任务，完成后将结果返回给主 Agent。

内置 Agent

OpenCode 预置了两个 Agent，通过 Tab 键切换：

Build Agent（默认）

{
  "agent": "build",
  "agents": {
    "build": {
      "description": "全权限开发 Agent，负责创建、编辑、执行",
      "permissions": {
        "edit": true,
        "bash": true,
        "network": true
      },
      "tools": ["read", "write", "edit", "bash", "glob", "grep", "task", "webfetch"]
    }
  }
}

• 角色定位：你的一线开发者
• 能力范围：读写文件、执行命令、网络请求
• 适用场景：功能开发、Bug 修复、代码重构

Plan Agent（只读）

{
  "agents": {
    "plan": {
      "description": "只读分析 Agent，用于代码探索和方案规划",
      "permissions": {
        "edit": false,
        "bash": "ask",
        "network": true
      },
      "tools": ["read", "glob", "grep", "webfetch", "task"]
    }
  }
}

• 角色定位：你的技术顾问和架构师
• 能力范围：只能读文件和搜索，无法修改代码
• 适用场景：探索陌生代码库、分析技术方案、Code Review

General Sub-Agent

OpenCode 还内置了一个名为 general 的 Sub-Agent，当主 Agent 遇到复杂的多步骤搜索任务时，会自动调度它来完成。用户也可以在消息中显式调用：

@general 帮我在整个项目中找到所有 API 调用的地方，并分析它们使用的认证方式

自定义 Agent

除了内置的 Agent，你可以在 opencode.json 中定义无限数量的自定义 Agent。

基础示例

{
  "agents": {
    "reviewer": {
      "description": "专注于代码审查的 Agent",
      "permissions": {
        "edit": false,
        "bash": false,
        "network": true
      },
      "tools": ["read", "grep", "glob"],
      "instructions": "你是一个严格的代码审查员。请仔细检查代码的逻辑正确性、安全漏洞和性能问题。"
    },
    "test-expert": {
      "description": "专注于测试用例编写",
      "permissions": {
        "edit": true,
        "bash": true,
        "network": false
      },
      "tools": ["read", "write", "edit", "bash", "glob", "grep"],
      "instructions": "你是一个测试专家。请为给定的代码编写全面的单元测试和集成测试。"
    },
    "documenter": {
      "description": "自动生成项目文档",
      "permissions": {
        "edit": true,
        "bash": false
      },
      "tools": ["read", "write", "glob", "grep"]
    }
  }
}

为 Agent 绑定 Skill

可以将特定的 Skill 绑定到 Agent 上，使其获得领域专长：

{
  "agents": {
    "frontend-dev": {
      "description": "前端开发专家",
      "permissions": {
        "edit": true,
        "bash": true,
        "network": true
      },
      "skills": ["frontend-design", "ui-ux-pro-max"]
    },
    "devops": {
      "description": "DevOps 运维专家",
      "permissions": {
        "edit": true,
        "bash": true,
        "network": true
      },
      "skills": ["docker", "kubernetes", "terraform"]
    }
  }
}

Agent 权限配置详解

{
  "permissions": {
    "edit": true,
    "bash": "ask",
    "network": true,
    "allow": ["src/**", "tests/**"],
    "deny": [".env", "**/secrets/**", "production/**"],
    "ask": ["config/**"]
  }
}

权限值可以是：

• true：始终允许
• false：始终拒绝
• "ask"：每次操作前请求用户确认

启动时指定 Agent

指定启动 Agent

# 以非默认 Agent 启动
opencode --agent reviewer

在 opencode.json 中切换默认 Agent

{
  "agent": "reviewer"
}

在对话中切换 Agent

在对话中输入 /agent <name> 可以动态切换：

/agent reviewer
/agent build

Sub-Agent 系统

Sub-Agent 是 OpenCode 实现「分而治之」的关键机制。主 Agent 可以将复杂任务拆解为多个子任务，分别交给不同的 Sub-Agent 并行处理。

工作原理

用户: 分析这个项目的安全性，包括依赖漏洞和代码安全

主 Agent (build):
  ├── Sub-Agent 1: 运行 npm audit 检查依赖漏洞
  ├── Sub-Agent 2: 扫描 src/ 目录中的安全模式
  └── Sub-Agent 3: 检查配置文件中是否有硬编码密钥

主 Agent 汇总结果 → 输出安全分析报告

创建自定义 Sub-Agent

在 .opencode/agents/ 目录下创建 Sub-Agent 定义文件：

// .opencode/agents/security-scanner.json
{
  "name": "security-scanner",
  "type": "subagent",
  "description": "安全漏洞扫描专家",
  "permissions": {
    "edit": false,
    "bash": true,
    "network": true
  },
  "tools": ["read", "bash", "glob", "grep"],
  "instructions": "你是安全扫描专家。请使用工具检查代码中的安全漏洞。"
}

在消息中调用 Sub-Agent

@security-scanner 扫描 src/auth/ 目录下的认证逻辑

并行 Sub-Agent 任务

OpenCode 会自动将独立的子任务并行分发给多个 Sub-Agent：

请同时完成以下任务：
- 检查 src/api/ 中的所有 TypeScript 类型错误
- 运行 test/ 目录下的所有单元测试
- 分析 package.json 中是否有过期的依赖

OpenCode 会创建 3 个 Sub-Agent 并行执行这些任务

高级实战：完整 Agent 团队

以下配置展示了一个完整的 Agent 团队设置，覆盖从开发到上线的全流程：

{
  "agent": "build",
  "agents": {
    "build": {
      "description": "主力开发 Agent",
      "permissions": {
        "edit": true,
        "bash": true,
        "network": true,
        "deny": [".env", "**/credentials.*"]
      },
      "tools": ["*"],
      "skills": ["systematic-debugging", "test-driven-development"]
    },
    "plan": {
      "description": "架构规划 Agent",
      "permissions": {
        "edit": false,
        "bash": "ask",
        "network": true
      },
      "tools": ["read", "glob", "grep", "webfetch", "task"],
      "skills": ["brainstorming", "writing-plans"]
    },
    "reviewer": {
      "description": "Code Review Agent",
      "permissions": {
        "edit": false,
        "bash": false,
        "network": true
      },
      "tools": ["read", "grep", "glob", "webfetch"],
      "skills": ["requesting-code-review", "receiving-code-review"]
    },
    "devops": {
      "description": "部署运维 Agent",
      "permissions": {
        "edit": true,
        "bash": true,
        "network": true,
        "allow": ["Dockerfile", "docker-compose.yml", ".github/**"]
      },
      "tools": ["*"],
      "skills": ["docker", "ci-cd"]
    }
  }
}

使用 Sub-Agent 的最佳实践

1. 适合用 Sub-Agent 的场景

• 彼此独立的并行任务：运行测试、代码检查、依赖分析可以同时进行
• 搜索密集型任务：在大型代码库中搜索多个模式
• 批量文件操作：对多个文件做同样类型的修改
• 信息收集：同时从多个来源获取信息

2. 不适合用 Sub-Agent 的场景

• 有严格先后顺序的任务：必须先 A 后 B 的操作
• 需要共享大量上下文：Sub-Agent 之间上下文不互通
• 简单单步操作：没必要为一行代码创建 Sub-Agent

3. 性能优化

{
  "advanced": {
    "maxConcurrency": 4
  }
}

控制并行 Sub-Agent 的最大数量，避免过多并发消耗大量 Token。

小结

Agent 系统让 OpenCode 从一个「对话助手」变成了一个「开发团队」。Build 负责执行，Plan 负责规划，自定义 Agent 负责专业领域，Sub-Agent 负责并行任务——这种架构让 AI 辅助编程从单兵作战升级为团队协作。

下一篇我们将深入 OpenCode 的 Skills 技能系统，学习如何创建可复用的专业指令模块。