引言

在传统 AI 编程助手中，所有任务都由同一个"全能型"模型处理——无论是编写复杂代码、搜索文件，还是生成简短的会话标题。这种"一刀切"的方式既浪费资源，又无法针对特定任务优化效果。

OpenCode 的代理系统采用了完全不同的设计理念：为不同任务分配专属的 AI 代理。每个代理都有明确的职责边界、独立的模型配置和差异化的工具权限。这种精细化分工让整个系统更高效、更安全、更灵活。本文将带你深入理解 OpenCode 的代理架构，掌握配置技巧，并了解 Agent Tool 这一强大的"元工具"机制。

一、为什么需要多种代理

1.1 单一模型的困境

想象一下，如果用 GPT-4 来处理所有任务会怎样？

单一模型配置要么"杀鸡用牛刀"，要么关键任务能力不足。OpenCode 的代理系统正是为了解决这个问题。

1.2 代理分工的价值

多代理架构带来三重收益：

1. 成本优化：轻量任务用轻量模型，复杂任务用强力模型
2. 性能提升：每个代理专注自己的领域，响应更快
3. 安全隔离：不同代理拥有不同的工具权限，降低风险

二、四种内置代理详解

OpenCode 内置四种代理类型，每种都有独特的职责和权限设计。

2.1 Coder Agent：主编码代理

Coder Agent 是 OpenCode 的"主力军"，承担所有需要修改代码、执行命令的任务。

核心特性：

• 完整工具权限：可使用 Edit、Write、Patch、Bash、LSP 等所有工具
• 元工具能力：拥有 Agent Tool，可生成子代理
• MCP 扩展：自动继承所有配置的 MCP 工具

典型配置：

agents:
  coder:
    model: claude-4-sonnet
    maxTokens: 5000
    reasoningEffort: medium

适用场景：代码编写、重构、Bug 修复、命令执行、文件操作等所有"写"操作。

2.2 Task Agent：只读子任务代理

Task Agent 是 Coder Agent 的"侦察兵"，专门处理代码搜索和探索任务。

核心特性：

• 只读权限：只能使用 Glob、Grep、LS、View、Sourcegraph
• 无状态执行：每次调用都是独立会话
• 轻量高效：适合使用更快、更便宜的模型

典型配置：

agents:
  task:
    model: gpt-4.1-mini
    maxTokens: 5000

适用场景：代码搜索、项目探索、文档查阅、代码审查（只读）等"读"操作。

2.3 Title Agent：会话标题生成

Title Agent 负责为会话生成简短、描述性的标题。

核心特性：

• 无工具权限：纯文本生成，不需要任何工具
• 极短输出：maxTokens 通常设为 80
• 自动触发：新会话开始时自动调用

典型配置：