OpenCode 多 Agent 系统完全指南：用专精智能体提升 AI 编程协作效率

在 OpenCode 已经发布的系列文章中，我们深入探讨了配置、工具、规则、插件等方方面面。今天要介绍的 Agent 系统，是 OpenCode 中一个极其强大但容易被忽视的特性——它允许你创建多个专精的 AI 智能体，每个承担不同的角色和职责，协同完成复杂的开发任务。

什么是 OpenCode Agent？

Agent（智能体）是 OpenCode 中专用的 AI 助手，每个 Agent 都可以配置独立的系统提示词、模型、工具权限和行为模式。简单来说，你可以为项目创建"建筑师"、"代码审查员"、"文档写手"等多个角色，在开发过程中灵活切换或并行调用。

Agent 分为两种类型：

• Primary Agent（主智能体）：可直接与之对话，通过 Tab 键或 switch_agent 快捷键切换。内置的 Build 和 Plan 就是典型的主智能体。
• SubAgent（子智能体）：由主智能体调用或通过 @ 提及手动触发，适合执行专业化子任务。内置的 General、Explore、Scout 均为此类。

内置 Agent 一览

OpenCode 出厂自带 8 个内置 Agent，覆盖了从开发到维护的主要场景：

Build（构建模式）

默认主智能体，拥有全部工具权限。这是日常开发的主力——写代码、改文件、运行命令，一切皆可。

Plan（计划模式）

受限主智能体，默认禁止文件编辑和命令执行。当你需要 AI 先分析代码、制定方案而不直接动手修改时，切换到 Plan 模式即可。按 Tab 键在 Build 和 Plan 之间切换，确保"先想清楚再动手"。

General（通用）

全能子智能体，可执行多步骤复杂任务。当主智能体需要并行处理时，可通过 Task 工具自动调用 General 帮忙。

Explore（探索）

只读子智能体，擅长代码库探索。当你需要快速查找文件、搜索代码模式或理解代码结构时，使用 @explore 让它帮忙而不干扰你的主会话。

Scout（侦察）

只读子智能体，专门用于外部依赖研究。可以克隆依赖仓库到 OpenCode 缓存中，检查库源码或对比上下游实现。

隐藏系统 Agent

Compaction、Title、Summary 三个隐藏 Agent 在后台自动运行，分别负责上下文压缩、会话标题生成和会话总结——用户无法直接交互，但它们在保持会话高效运作中扮演关键角色。

配置自定义 Agent

真正的威力来自自定义 Agent。你可以通过两种方式创建：

JSON 配置

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

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码中的最佳实践和潜在问题",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "你是一名资深代码审查员。重点关注安全性、性能、可维护性。",
      "permission": {
        "edit": "deny"
      }
    },
    "docs-writer": {
      "description": "编写和维护项目文档",
      "mode": "subagent",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "bash": "deny"
      }
    }
  }
}

Markdown 文件配置

也可以将 Agent 定义放在独立的 .md 文件中，放在 ~/.config/opencode/agents/（全局）或 .opencode/agents/（项目级）：

---
description: 安全审计，识别潜在漏洞
mode: subagent
permission:
  edit: deny
---

你是一名安全专家，专注于识别安全风险。
关注：输入验证漏洞、认证授权缺陷、数据暴露风险。

文件名即 Agent 名，例如 security-auditor.md 会创建一个名为 security-auditor 的 Agent。

核心配置选项详解

description（描述）

必填项，简要说明 Agent 的功能和使用场景。OpenCode 会根据描述自动决定何时调用子智能体。

temperature（温度）

控制模型回答的随机性和创造力：

• 0.0-0.2：高度专注和确定，适合代码分析、计划制定
• 0.3-0.5：平衡模式，适合日常开发
• 0.6-1.0：高创造力，适合头脑风暴和探索

未指定时使用模型默认值（大多数模型为 0）。

steps（最大步数）

限制 Agent 的迭代次数。设置为 5 表示最多执行 5 次工具调用后必须返回文本响应。适合控制成本的场景。注意旧版 maxSteps 已废弃，请使用 steps。

model（模型）

为特定 Agent 覆盖全局模型配置。例如计划 Agent 使用快速便宜的 Haiku，构建 Agent 使用强大的 Sonnet：

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

permission（权限）

细粒度控制 Agent 能做什么。比旧的 tools 字段更灵活：

{
  "agent": {
    "reviewer": {
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "ask",
          "git diff": "allow",
          "grep *": "allow"
        }
      }
    }
  }
}

权限键包括：read、edit、glob、grep、list、bash、task、webfetch、websearch、lsp、skill 等。每个可设为 allow（允许）、ask（询问）、deny（禁止）。

color（颜色）

在 UI 中为 Agent 设置颜色，使用十六进制或主题色：

{
  "agent": {
    "creative": { "color": "#ff6b6b" },
    "reviewer": { "color": "accent" }
  }
}

hidden（隐藏）

设为 true 可从 @ 自动补全菜单中隐藏该子智能体，但仍可通过 Task 工具由其他 Agent 调用。

task 权限

控制主智能体可以调用哪些子智能体，支持 glob 模式匹配：

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow"
        }
      }
    }
  }
}

额外参数

任何未识别的配置项会直接透传给模型提供商。例如 OpenAI 的 reasoningEffort：

{
  "agent": {
    "deep-thinker": {
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

实战案例

代码审查自动化

创建一个只读的代码审查 Agent，配合 git diff 查看变更：

---
description: 对代码变更进行审查
mode: subagent
permission:
  edit: deny
  bash:
    "*": "deny"
    "git diff*": "allow"
    "git log*": "allow"
    "grep *": "allow"
---

你是一名高级代码审查员。每次收到审查请求时：
1. 先运行 git diff 了解变更内容
2. 检查代码质量、安全性、性能
3. 给出具体的改进建议
4. 不直接修改任何文件

文档工作流

创建一个文档 Agent，专门负责从代码生成文档：

{
  "agent": {
    "docs-gen": {
      "description": "从源码生成和更新文档",
      "mode": "subagent",
      "prompt": "你是技术文档写手。分析代码结构后生成清晰的 API 文档。包含参数说明、返回值类型、使用示例。",
      "permission": {
        "edit": "allow",
        "bash": "deny",
        "webfetch": "allow"
      }
    }
  }
}

多模型协作

利用不同模型的优势：用 Haiku 做快速代码搜索，用 Sonnet 做深度审查，用 GPT-5 做架构设计。在 opencode.json 中为每个 Agent 指定不同的模型即可。

使用技巧与最佳实践

Tab 键切换主智能体：在 Build 和 Plan 之间快速切换，先计划再执行。

@ 调用子智能体：对话中输入 @reviewer 即可临时唤起代码审查 Agent。

子会话导航：子智能体创建子会话后，用 Ctrl+Down 进入，Right/Left 切换，Up 返回父会话。

权限最小化：为每个 Agent 只授予完成任务所需的最小权限——审查 Agent 不需要编辑权限。

模型匹配任务：简单任务用低成本模型，复杂任务用高性能模型，优化 Token 消耗。

利用 describe 自动调度：description 写得越准确，OpenCode 越能在适当时机自动调用你的智能体。

总结

OpenCode 的 Agent 系统为 AI 辅助编程带来了全新的协作范式。通过创建多个专精智能体，你可以像带领一个 AI 开发团队一样工作——有建筑师、审查员、文档写手、安全专家，各司其职。结合模型选择、权限控制和自定义提示词，Agent 系统让 OpenCode 从一个对话式编程助手蜕变为一个可编排的 AI 开发平台。

赶快打开你的 opencode.json，开始创建你的第一个自定义 Agent 吧。