OpenCode自定义代理配置指南：为不同任务分配专属AI

你是否还在使用一个“全能”的AI助手来处理所有编程任务？从编写复杂功能到搜索一个简单的文件关键词，都让同一个大模型来干，不仅响应慢、成本高，效果也未必理想。

OpenCode 的代理系统采用了截然不同的思路：为不同类型的任务分配专属的 AI 代理。每个代理都有清晰的职责、独立的模型配置和差异化的工具权限。这种精细化的分工，让整个系统变得更高效、更安全，也更具性价比。

一、为什么需要多种代理

1.1 单一模型的困境

想象一下，如果强迫 GPT-4 或 Claude 去处理所有任务会怎样？

任务	实际需求	用单一强力模型的问题
生成会话标题	10 个词以内的摘要	大材小用，响应慢
搜索代码关键词	简单的文件查找	模型推理过程冗长，没必要
编写复杂功能	深度推理、代码生成	恰好匹配，但成本高
会话摘要	压缩历史记录	完全可以用更快、更便宜的小模型

单一模型配置往往面临“杀鸡用牛刀”或“小马拉大车”的两难境地。OpenCode 的多代理架构正是为了解决这个问题而生。

1.2 代理分工的价值

多代理设计主要带来三重收益：

1. 成本优化：轻量任务用轻量模型，复杂任务才动用“重型武器”。
2. 性能提升：每个代理专注自己的领域，响应速度更快。
3. 安全隔离：不同代理拥有差异化的工具权限，有效降低了操作风险。

二、四种内置代理详解

OpenCode 默认内置了四种代理类型，它们各司其职。

2.1 Coder Agent：主编程代理

这是 OpenCode 的“主力军”，承担所有需要修改代码、执行命令的核心任务。

• 核心特性：
  • 完整工具权限：可使用 Edit、Write、Patch、Bash、LS 等所有工具。
  • 元工具能力：拥有 Agent Tool，可动态生成子代理。
  • MCP 扩展：自动继承所有已配置的 MCP 工具。
• 典型配置：

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

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

2.2 Task Agent：只读子任务代理

作为 Coder Agent 的“侦察兵”，专门处理代码搜索和探索类任务。

• 核心特性：
  • 只读权限：只能使用 Glob、Grep、LS、View、Sourcegraph 等工具。
  • 无状态执行：每次调用都是独立会话，互不干扰。
  • 轻量高效：适合使用更快、更便宜的模型。
• 典型配置：

  agents:
    task:
      model: gpt-4-1-mini
      maxTokens: 5000

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

2.3 Title Agent：会话标题生成

顾名思义，它专门负责为对话生成简短、描述性的标题。

• 核心特性：
  • 无工具权限：纯文本生成，不需要任何工具。
  • 极限输出：maxTokens 通常设为 80 左右。
  • 输出控制：允许设置最大长度限制。
• 典型配置与设计考量：

  agents:
    title:
      model: claude-3-7-sonnet
      maxTokens: 80

  虽然输出很短，但标题质量直接影响用户体验和后续检索，因此通常建议使用与主代理相同或相近质量的模型。

2.4 Summarizer Agent：会话摘要

负责压缩冗长的对话历史，提炼关键信息，防止会话超出模型的上下文限制。

• 核心特性：
  • 无工具权限：纯文本处理。
  • 摘要压缩：将长对话浓缩为结构化关键点。
• 典型配置：

  agents:
    summarizer:
      model: claude-3-7-sonnet
      maxTokens: 5000

三、代理配置结构详解

所有代理的配置都位于统一的配置文件中。

3.1 配置位置

代理配置位于 opencode.json 或 opencode.yaml 的 agents 字段下：

{
  "providers": {...},
  "agents": {
    "coder": {...},
    "task": {...},
    "title": {...},
    "summarizer": {...}
  }
}

对应的 Go 语言结构体定义清晰地展示了配置的顶层结构：

type Config struct {
    ...
    Agents map[AgentName]Agent `json:"agents,omitempty"`
    ...
}

3.2 配置参数说明

每个代理支持三个核心参数：

参数	类型	说明	示例
model	string	使用的模型 ID	claude-4-sonnet
maxTokens	number	最大输出 token 数	5000
reasoningEffort	string	推理强度（低/中/高）	medium

其中 reasoningEffort 参数仅部分模型（如 Claude）支持：

• low：快速响应，适合简单任务。
• medium：平衡速度和质量。
• high：深度推理，适合复杂问题。

3.3 完整配置示例与策略

{
  "providers": {
    "anthropic": {
      "apiKey": "$ANTHROPIC_API_KEY"
    },
    "openai": {
      "apiKey": "$OPENAI_API_KEY"
    }
  },
  "agents": {
    "coder": {
      "model": "claude-4-sonnet",
      "maxTokens": 5000,
      "reasoningEffort": "high"
    },
    "task": {
      "model": "gpt-4-1-mini",
      "maxTokens": 5000
    },
    "title": {
      "model": "claude-3-7-sonnet",
      "maxTokens": 80
    },
    "summarizer": {
      "model": "claude-3-7-sonnet",
      "maxTokens": 5000
    }
  }
}

配置策略建议：

• Coder Agent：使用最强模型（如 Claude 4 Sonnet, GPT-4.1），并将 reasoningEffort 设为 high。
• Task Agent：选用轻量、快速的模型（如 GPT-4.1-mini, Gemini Flash）。
• Title Agent：maxTokens 保持在 80 左右即可。
• Summarizer Agent：为保证摘要质量，建议使用与 Coder Agent 相同或相近的模型。

四、Agent Tool：元工具机制

这是 OpenCode 代理系统中最精妙的设计之一——一个“能生成代理的工具”。

4.1 什么是 Agent Tool

当 Coder Agent 在执行任务过程中，发现需要执行一个只读的子任务（例如搜索代码）时，它并不会自己去做，而是通过调用 Agent Tool，动态生成一个临时的 Task Agent（子代理）来专门处理这个任务。这是一种层次化、轻量化的任务执行模式。

Coder Agent（主代理）
 |
 | 发现需要搜索代码
 |
 | 调用 Agent Tool
 |
 | 生成 Task Agent（子代理）
 |
 | 执行搜索，返回结果
 |
基于结果继续工作

4.2 工作原理

从源码可以直观看到 Agent Tool 的定义和能力边界：

// internal/llm/agent-agent-tool.go
func (b *agentTool) Info() tools.ToolInfo {
    return tools.ToolInfo{
        Name: "agent",
        Description: "Launch a new agent that has access to: GlobTool, GrepTool, LS, View, Sourcegraph...",
        Parameters: map[string]any{
            "prompt": map[string]any{
                "type":        "string",
                "description": "The task for the agent to perform",
            },
        },
    }
}

关键特点：

1. 单参数：只接收一个 prompt 参数，用于描述子任务。
2. 固定工具集：生成的子代理只能使用 Glob、Grep、LS、View、Sourcegraph 等只读工具。
3. 无状态执行：子代理完成任务后立即销毁，不保留任何上下文。
4. 并发支持：可以在单条消息中并发调用多个 Agent Tool，并行处理任务。

4.3 触发场景与并发执行

Agent Tool 通常会在以下场景被 Coder Agent 自动触发：

• 搜索关键词在代码库中的位置。
• 查找符合特定模式的文件。
• 探索项目结构或依赖关系。
• 分析代码调用链。

并发执行示例：
当用户要求“帮我找到所有使用 useState 和 useEffect 的组件”时，Coder Agent 可以这样做：

1. 调用 Agent Tool #1：生成子代理搜索 “useState”。
2. 调用 Agent Tool #2：生成另一个子代理搜索 “useEffect”。
   两个子代理并发执行搜索，最后将结果汇总返回。这种模式极大提升了搜索和探索任务的效率。

五、工具权限层级

OpenCode 严格遵循“最小权限原则”，为不同代理设计了差异化的工具集合，这是系统安全与稳定的基石。

5.1 权限层级图

Coder Agent（完整权限）
 ├─ 文件操作：Edit, Write, Patch, View
 ├─ 搜索工具：Glob, Grep, LS, Sourcegraph
 ├─ 命令执行：Bash
 ├─ 网络分析：Fetch
 ├─ 代码分析：Diagnostics (LSP)
 ├─ 子代理生成：Agent Tool
 └─ MCP 工具：通过配置扩展

Task Agent（只读权限）
 ├─ 搜索工具：Glob, Grep, LS, Sourcegraph
 └─ 文件查看：View

Title / Summarizer Agent（无工具）
 └─ 仅文本生成

5.2 权限隔离的意义

• 安全角度：Task Agent 被设计为无法修改文件或执行命令。即使受到恶意提示词诱导，其破坏力也仅限于只读操作，从根本上杜绝了误删改代码的风险。
• 成本角度：只读任务无需携带 Edit、Bash 等复杂工具的上下文描述，显著减少了每次请求的 Token 消耗。
• 稳定性角度：工具越少，代理行为的可预测性越高，出错的概率也越低。

5.3 工具集组装逻辑

从代码层面看，不同代理的工具集是明确组装的：

// Coder Agent 工具集（完整）
func CoderAgentTools(...) []tools.BaseTool {
    return append(
        []tools.BaseTool{
            tools.NewBashTool(permissions),
            tools.NewEditTool(...),
            tools.NewGrepTool(),
            tools.NewSourcegraphTool(),
            NewAgentTool(...), // 元工具
            // 更多工具...
        },
        GetMcpTools(cts, permissions)... // MCP 扩展
    )
}

// Task Agent 工具集（只读）
func TaskAgentTools(lspClients map[string]lsp.Client) []tools.BaseTool {
    return []tools.BaseTool{
        tools.NewGlobTool(),
        tools.NewGrepTool(),
        tools.NewLSTool(),
        tools.NewSourcegraphTool(),
        tools.NewViewTool(lspClients),
    }
}

六、代理与命令的区别

OpenCode 同时提供了“自定义代理”和“自定义命令”两种扩展机制，理解它们的区别很重要。

6.1 核心对比

性质	自定义代理	自定义命令
定义位置	配置文件 agents/ 字段	.cloude/commands/ 目录下的 .md 文件
配置核心	model, maxTokens, reasoningEffort	纯文本提示词 + $ARGUMENTS 变量
工具权限	继承其代理类型的预设工具集	使用触发它的 Coder Agent 的完整工具集
触发方式	自动（系统根据任务类型分配）	手动（通过 Ctrl+K 或 /命令名 调用）
适用场景	为特定任务配置不同的AI模型和权限	封装可重复的工作流或团队标准流程

6.2 选择指南与组合使用

• 何时用自定义代理：当你需要为代码搜索和代码编写等不同性质的任务，分配不同模型、调整推理强度或限制工具权限时。
• 何时用自定义命令：当你需要将一套固定的操作流程（例如标准的 Git 提交、代码审查模板）封装成一键执行的快捷方式时。

两者可以强强联合。例如，你可以创建一个名为 /review 的自定义命令，该命令的内部逻辑会触发 Task Agent 对指定目录进行只读的代码审查分析，并生成报告。

6.3 最佳实践与场景匹配

模型选择策略：

• Coder Agent: Claude 4 Sonnet / GPT-4.1（需要深度推理）。
• Task Agent: GPT-4.1-mini / Gemini Flash（速度优先）。
• Title/Summarizer Agent: 建议与 Coder 使用相同模型（保证输出质量）。

使用场景匹配：

• 代码编写/重构：直接使用 Coder Agent。
• Bug 调试：Coder Agent 主导，辅以 Task Agent（通过 Agent Tool）搜索和定位。
• 纯代码审查：使用 Task Agent 或触发它的自定义命令即可。

七、关键注意事项

1. 权限牢记：Task Agent 无法修改文件，任何需要写入的操作都必须由 Coder Agent 执行。
2. 状态无关：Agent Tool 生成的子代理是无状态的，每次调用都是全新会话，不保留历史。
3. 善用并发：多个独立的搜索任务，可以通过并发调用多个 Agent Tool 来显著提升效率。
4. MCP 继承：所有配置的 MCP 工具会自动添加到 Coder Agent 的工具集中，无需额外配置。

小结

OpenCode 的多代理架构通过精细化分工，解决了单一AI模型在编程辅助中的效率与成本瓶颈。掌握 Coder、Task、Title、Summarizer 这四种内置代理的定位与配置，理解 Agent Tool 这一元工具的并发工作逻辑，并遵循 最小权限原则 进行工具隔离，你就能构建出一个高效、安全且经济的智能编程助手体系。无论是个人开发者还是团队，都可以在云栈社区交流更多关于LLM应用架构的实践，让AI真正成为提升生产力的利器。