📖 1.1 什么是 Agents？
Agents（代理）是 OpenCode 的核心概念之一。Agent 是一个专门化的 AI 助手， 可以被配置用于执行特定的任务和工作流。OpenCode 采用双层代理架构： Primary Agent（主代理）和 Subagent（子代理）。
🤖 Primary Agent
主代理，你直接交互的 AI 助手。可通过 Tab 键切换不同主代理。
🔧 Subagent
子代理，主代理可以为特定任务调用的专业助手。
📋 1.2 内置代理类型
Primary Agents（主代理）
🔨 Build
默认代理，所有工具启用。适合日常开发任务。
📋 Plan
受限代理，默认禁用 write/edit/bash。适合规划和分析。
Subagents（子代理）
🔍 Explore
快速代理，专长于探索代码库，查找文件和代码模式。
💡 General
通用代理，用于研究复杂问题和执行多步骤任务。
⚙️ 1.3 配置 Agents
你可以通过 opencode.json 配置文件自定义 Agent：
// opencode.json 配置示例
"agent": {
"build": {
"mode": "primary",
"description": "Default agent with all tools enabled",
"model": "anthropic/claude-sonnet-4-20250514",
"temperature": 0.7,
"maxSteps": 100,
"tools": {
"write": true,
"edit": true,
"bash": true
}
},
"plan": {
"mode": "primary",
"description": "Restricted agent for planning",
"model": "anthropic/claude-haiku-4-20250514",
"tools": {
"write": false,
"edit": false,
"bash": false
}
},
"code-reviewer": {
"mode": "subagent",
"description": "Reviews code for quality",
"hidden": false,
"permission": {
"task": ["build", "plan"]
}
}
}
💡 提示：
也可以使用 Markdown 文件配置代理，在 ~/.config/opencode/agent/ 或 .opencode/agent/ 目录下创建 YAML 文件。
🔄 1.4 切换代理
在 OpenCode 对话中，你可以使用 Tab 键切换不同的 Primary Agent：
// 在对话中输入 @ 符号呼出代理选择菜单
// 或使用 Tab 键在不同代理间切换
// 示例：调用子代理
@code-reviewer 请帮我审查 src/index.js 的代码质量
@explore 查找所有使用 OpenCode SDK 的文件
🛠️ 1.5 创建自定义代理
使用命令行创建新的 Agent：
// 创建新代理
$ opencode agent create
// 交互式引导创建代理
? Enter agent name: my-custom-agent
? Enter agent description: A custom agent for data analysis
? Select mode (primary/subagent/all): subagent
? Enter model (default: anthropic/claude-sonnet-4-20250514):
? Enable tools:
✓ write
✓ edit
✗ bash
? Save to: ~/.config/opencode/agent/my-custom-agent.yaml
或直接创建 YAML 配置文件：
// ~/.config/opencode/agent/data-analyst.yaml
---
description: Specialized agent for data analysis and visualization
mode: subagent
model: anthropic/claude-sonnet-4-20250514
tools:
write: true
edit: true
bash: false
---
You are a data analysis expert.
Your job is to help users analyze data, create visualizations, and generate reports.
Always use clear explanations and provide actionable insights.
📊 1.6 实际案例
以下案例来自你的 codebase：
🔍 探索代码库
使用 @explore 代理快速扫描项目结构，查找特定文件。
📝 代码审查
创建 code-reviewer 子代理，自动审查代码质量。
🎯 规划任务
使用 @plan 代理进行项目规划和任务分解。
✅ 本章小结
- 理解 Primary Agent 和 Subagent 的区别
- 掌握内置代理（Build、Plan、Explore、General）的用途
- 学会配置和自定义 Agent
- 了解如何切换和调用不同代理