首页 > 专题 > AI编程 > 文章详情
返回 AI编程

3、OpenCode Agents 简明实战手册：15分钟上手多Agent协作

2026年02月08日 20 阅读 AI编程

快速开始（5分钟）

1. 什么是 Agents？

Agents 是 OpenCode 中的AI 专家角色，每个 Agent 可以：

  • 使用不同的 AI 模型（Claude、GPT、Gemini 等）
  • 拥有特定的系统提示词（Prompt）
  • 拥有不同的工具权限（读文件、写代码、执行命令）
  • 主 Agent：直接交互（Build、Plan）
  • 子 Agent：通过 @agent名 调用（Reviewer、Researcher 等）

2. 为什么需要多 Agents？

单一模型的问题：

  • Claude 擅长编码但无法获取实时信息
  • Perplexity 能搜索但不该碰你的代码
  • GPT 调试强但不如 Claude 懂代码风格

多 Agents 优势：

  • ✅ 专业化：每个 Agent 做最擅长的事
  • ✅ 并行化：多个 Agent 同时工作
  • ✅ 安全性：限制敏感操作权限
  • ✅ 灵活调用：按需使用不同专家

免费模型：MiniMax2.1 和 kimi2.5 写代码基本够用

3. 三步配置你的第一个 Agent

Step 1：创建配置文件

# 全局配置
mkdir -p ~/.config/opencode/agents
touch ~/.config/opencode/opencode.json

Step 2：写入基础配置

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "coder": {
      "description": "主开发 Agent",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4",
      "temperature": 0.2,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    }
  }
}

Step 3：启动使用

opencode
# 按 Tab 切换 Agents
# 输入 @coder 直接调用

核心配置详解

配置方式对比

| 方式 | 文件位置 | 适用场景 |
|------|----------|----------|
| JSON 配置 | ~/.config/opencode/opencode.json | 复杂配置、多 Agents |
| Markdown 配置 | ~/.config/opencode/agents/*.md | 简单 Agent、快速创建 |

关键配置项速查表

| 配置项 | 说明 | 推荐值 |
|--------|------|--------|
| mode | Agent 类型 | primary(主) / subagent(子) |
| model | 使用模型 | anthropic/claude-sonnet-4 |
| temperature | 创造性 | 0.2(代码) / 0.8(研究) |
| tools | 工具权限 | write/edit/bash |
| description | 功能描述 | 必填，说明 Agent 用途 |

Temperature（温度）设置指南

{
  "agent": {
    "coder": { "temperature": 0.2 },      // 代码生成：稳定、可预测
    "debugger": { "temperature": 0.3 },   // 调试：逻辑性强
    "researcher": { "temperature": 0.8 }  // 研究：创造性探索
  }
}

参考值：

  • 0.0-0.2：代码编写、重构、分析
  • 0.3-0.5：调试、一般开发任务
  • 0.6-0.8：研究、探索、头脑风暴
  • 0.9-1.0：创意生成

工具权限配置

{
  "agent": {
    "full-access": {
      "tools": {
        "write": true,   // 创建文件
        "edit": true,    // 修改文件
        "bash": true     // 执行命令
      }
    },
    "read-only": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

实战：三 Agent 黄金组合

推荐架构

基于社区最佳实践，推荐配置 Coder + Researcher + Debugger：

| Agent | 职责 | 推荐模型 | 温度 | 工具权限 |
|-------|------|----------|------|----------|
| Coder | 代码编写 | Claude Sonnet 4 | 0.2 | 全部 |
| Researcher | 技术调研 | Perplexity Sonar | 0.8 | 只读+网络 |
| Debugger | 调试测试 | GPT-4 | 0.3 | 全部 |

完整配置示例

文件：~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4",
  "agent": {
    "coder": {
      "description": "主开发 Agent，编写高质量代码",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4",
      "temperature": 0.2,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "researcher": {
      "description": "技术调研 Agent，搜索最新文档",
      "mode": "subagent",
      "model": "perplexity/sonar",
      "temperature": 0.8,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "webfetch": true
      }
    },
    "debugger": {
      "description": "调试 Agent，定位和修复 Bug",
      "mode": "subagent",
      "model": "openai/gpt-4",
      "temperature": 0.3,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    }
  }
}

协作工作流示例

场景 1：开发新功能

用户：实现用户登录功能

Coder → 编写登录代码
  ↓ 遇到不确定的 JWT 最佳实践
  ↓ 自动调用 @researcher
  
Researcher → 搜索 2025 JWT 最佳实践
  ↓ 返回最新方案
  
Coder → 基于研究实现代码
  ↓ 编写完成后
  ↓ 自动调用 @debugger
  
Debugger → 运行测试，发现边界问题
  ↓ 修复 Token 过期处理
  ↓ 所有测试通过
  
返回给用户：完成功能，已验证

场景 2：手动调用 Agents

# 直接询问研究者
@researcher 2025 年 React 最佳实践是什么？

# 直接调用调试器
@debugger 修复这个 TypeScript 错误

# 切换主 Agent
[按 Tab 键] 在 Coder 和 Plan 之间切换

Markdown 方式快速创建 Agents

创建代码审查 Agent

文件：~/.config/opencode/agents/reviewer.md

---
description: 代码审查专家，发现潜在问题
mode: subagent
model: anthropic/claude-sonnet-4
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

你是代码审查专家。关注：
1. 代码质量和最佳实践
2. 潜在 Bug 和边界情况
3. 性能和安全问题

只提供建议，不直接修改代码。

使用：

@reviewer 审查 src/auth.js

创建文档编写 Agent

文件：~/.config/opencode/agents/writer.md

---
description: 技术文档撰写专家
mode: subagent
tools:
  bash: false
---

你是技术文档专家。编写清晰、结构化的文档：
- API 文档
- 使用说明
- 代码注释

权限控制（安全必备）

精细权限配置

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",           // 编辑前询问
        "bash": {
          "*": "ask",            // 默认询问
          "git status*": "allow", // git status 直接允许
          "npm test": "allow"     // 测试命令直接允许
        }
      }
    }
  }
}

权限级别

  • "ask"：执行前询问确认
  • "allow"：直接允许
  • "deny"：禁止执行

常用命令速查

# 启动 OpenCode
opencode

# 列出所有 Agents
opencode agent list

# 交互式创建 Agent
opencode agent create

# 查看当前配置
opencode models
opencode agents

TUI 快捷键

| 快捷键 | 功能 |
|--------|------|
| Tab | 切换主 Agent |
| Ctrl+K | 命令面板 |
| Ctrl+O | 切换模型 |
| @ + 名称 | 调用子 Agent |
| Ctrl+S | 发送消息 |

故障排查 FAQ

Q1: Agent 未识别

问题：@researcher 显示未找到

解决：

  1. 检查配置文件位置：~/.config/opencode/opencode.json
  2. 验证 JSON 格式（可用在线 JSON 校验工具）
  3. 重启 OpenCode

Q2: 调用了错误的模型

问题：Agent 使用了不期望的模型

解决：检查 model 字段格式：

"model": "anthropic/claude-sonnet-4"  // 正确
"model": "claude"                      // 错误

Q3: Agent 无法修改文件

问题：提示 "I don't have file access"

解决：检查 tools 配置：

"tools": {
  "write": true,  // 必须 true
  "edit": true    // 必须 true
}

Q4: 如何禁用某个 Agent？

{
  "agent": {
    "old-agent": {
      "disable": true
    }
  }
}

进阶技巧

1. 项目专属 Agents

在项目目录创建 .opencode/agents/：

my-project/
├── .opencode/
│   ├── agents/
│   │   ├── django-expert.md
│   │   └── api-tester.md
│   └── opencode.json
└── src/

2. 从文件加载复杂 Prompt

{
  "agent": {
    "coder": {
      "prompt": "{file:./prompts/build.txt}"
    }
  }
}

3. 限制最大迭代次数

{
  "agent": {
    "quick-task": {
      "steps": 5  // 最多 5 轮迭代
    }
  }
}

4. 隐藏内部 Agent

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true  // 不在 @ 补全中显示
    }
  }
}

最佳实践总结

✅ 要做的

  1. 专业化分工：不同 Agent 处理不同任务
  2. 合理温度：代码 0.2、调试 0.3、研究 0.8
  3. 最小权限：只给必要的工具权限
  4. 清晰描述：让 Agent 知道何时被调用
  5. 测试协作：手动测试 Agent 间的配合

❌ 不要做

  1. 一个 Agent 做所有事：失去了多 Agent 的意义
  2. 温度设置不当：代码生成用 0.8 会导致不稳定
  3. 权限过大：网络搜索 Agent 给写权限很危险
  4. 描述模糊：Agent 不知道该何时介入

成本优化配置

预算友好方案

{
  "agent": {
    "coder": {
      "model": "anthropic/claude-haiku-4"  // 便宜但够用
    },
    "researcher": {
      "model": "perplexity/sonar"           // 基础版
    }
  }
}

下一步

  1. 安装 OpenCode：curl -fsSL https://opencode.ai/install | bash
  2. 复制上面的三 Agent 配置
  3. 启动并测试：opencode
  4. 尝试调用：@researcher 搜索最新技术
  5. 探索更多：查看官方文档 https://opencode.ai/docs/agents/

核心公式：

最佳效果 = 专业 Agent + 合适模型 + 正确温度 + 最小权限
OpenCode