Agents 代理系统

OpenCode 的代理系统由**主代理（Primary Agents）和子代理（Subagents）**组成。主代理是你直接交互的助手，子代理是专门处理特定任务的辅助助手。

内置代理

主代理

代理	说明
Build	默认代理，启用所有工具，可直接执行代码修改
Plan	受限代理，用于分析和规划；文件编辑和 bash 命令默认需要确认

切换方式：按 Tab 键在 Build 和 Plan 模式间切换。

子代理

代理	说明
General	通用子代理，处理多步骤任务研究和代码搜索
Explore	快速代码库探索和模式匹配

调用方式：使用 @mention 语法，例如 @general 搜索认证相关代码。

配置方式

OpenCode 支持两种代理配置方式：JSON 配置和 Markdown 配置。

JSON 配置

在 opencode.json 中定义代理：

{
  "agent": {
    "review": {
      "mode": "subagent",
      "description": "专注于代码审查和质量改进",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false
      }
    },
    "doc-writer": {
      "mode": "subagent",
      "description": "技术文档编写专家",
      "model": "anthropic/claude-sonnet-4-5",
      "maxSteps": 10
    }
  }
}

Markdown 配置

在 ~/.config/opencode/agent/ 或项目 .opencode/agent/ 目录下创建 .md 文件：

---
description: 专注于代码审查和质量改进
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
  write: false
  edit: false
---

你是一个代码审查专家。请专注于以下方面：

1. 代码质量和可维护性
2. 潜在的 bug 和边界情况
3. 安全漏洞
4. 性能问题

审查时请提供具体的改进建议和代码示例。

配置选项详解

选项	类型	说明
description	string	代理功能描述（必需）
mode	string	primary（主代理）、subagent（子代理）或 all（两者）
model	string	覆盖默认模型，格式：provider/model-name
temperature	number	响应随机性控制（0.0-1.0）
maxSteps	number	限制代理迭代步数
tools	object	启用/禁用特定工具
permission	string	权限模式：ask、allow、deny
prompt	string	自定义系统提示词文件路径

实用代理示例

代码审查代理

{
  "agent": {
    "review": {
      "mode": "subagent",
      "description": "代码审查与质量分析",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

文档编写代理

{
  "agent": {
    "docs": {
      "mode": "subagent",
      "description": "技术文档编写与维护",
      "model": "anthropic/claude-sonnet-4-5",
      "maxSteps": 15,
      "tools": {
        "bash": false
      }
    }
  }
}

架构设计代理

{
  "agent": {
    "architect": {
      "mode": "subagent",
      "description": "系统架构设计与技术选型",
      "model": "anthropic/claude-opus-4-5",
      "temperature": 0.3,
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

测试专家代理

{
  "agent": {
    "tester": {
      "mode": "subagent",
      "description": "编写和优化测试用例",
      "model": "anthropic/claude-sonnet-4-5",
      "maxSteps": 20
    }
  }
}

使用代理

切换主代理

# 按 Tab 键切换 Build/Plan 模式
# 或使用配置的 switch_agent 快捷键

调用子代理

在对话中使用 @ 语法调用子代理：

@review 请审查这段代码的安全性
@docs 为这个函数编写文档
@architect 设计这个微服务的架构
@general 搜索项目中所有的 API 端点

会话导航

• <Leader>+Right：进入子代理会话
• <Leader>+Left：返回父会话

工具权限配置

可以为代理配置特定工具的权限：

{
  "agent": {
    "safe-agent": {
      "mode": "subagent",
      "description": "只读分析代理",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "notebook_edit": false
      },
      "permission": "ask"
    }
  }
}

可配置的工具

工具	说明
read	读取文件
write	创建新文件
edit	编辑现有文件
bash	执行 shell 命令
glob	文件模式匹配
grep	内容搜索
fetch	网络请求
notebook_edit	编辑 Jupyter Notebook

设置默认代理

{
  "default_agent": "build"
}

可选值："build" 或 "plan"

最佳实践

1. 明确的描述

为每个代理提供清晰、具体的描述，帮助 OpenCode 正确选择代理：

{
  "description": "专注于 React 组件开发和性能优化"
}

2. 合理的工具限制

根据代理用途限制工具访问：

• 审查代理：禁用写入和编辑
• 文档代理：禁用 bash
• 分析代理：只保留读取权限

3. 适当的温度设置

• 代码生成/审查：0.0-0.3（更确定性）
• 创意任务：0.5-0.7（更多变化）
• 文档编写：0.3-0.5（平衡）

4. 控制迭代步数

为复杂任务设置足够的 maxSteps，简单任务可以降低以节省资源：

{
  "maxSteps": 10  // 简单任务
  "maxSteps": 30  // 复杂任务
}

下一步

• 配置详解 - 了解完整配置结构
• Provider 配置 - 为不同代理配置不同模型