LowHow 文档

中文

English

中文

English

深色模式

OpenCode AI代理实战教程：创建你的专属编码助手 ​

📚 分类: AI 开发工具 / 工作流优化 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并配置好 OpenCode（当前最新稳定版） 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 中 Primary Agent (主代理) 和 Subagent (子代理) 的区别与用途
  • [ ] 熟练使用内置的 Build 和 Plan 代理来规划与执行开发任务
  • [ ] 通过 @ 提及或自动调用，让 Scout、Explore 等子代理为你工作
  • [ ] 掌握在 opencode.json 中配置和自定义一个专属 AI 代理的方法

最终效果 ​

你将能够根据不同的开发阶段（如规划、编码、审查），在 OpenCode 中灵活切换并使用不同的 AI 代理，并最终创建一个属于自己的、拥有特定权限和提示词的代码审查代理。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode当前最新稳定版opencode --version

1. 确认 OpenCode 已安装 ​

bash
$ opencode --version    // 验证 OpenCode 是否安装成功

✅ 验证：如果终端输出版本号（例如 v1.x.x），说明安装成功。

第 1 步：认识 OpenCode 的两种代理类型 ​

🎯 目标：理解 Primary Agent 和 Subagent 的核心概念，为后续操作打下基础。

在 OpenCode 中，代理分为两种：

  • Primary Agent (主代理)：你与之直接对话的主要助手。你可以通过 Tab 键在主代理之间快速切换。它们拥有不同的工具权限，例如 Build 代理可以修改文件，而 Plan 代理只能读取。
  • Subagent (子代理)：由主代理或你（通过 @ 提及）调用的专业化助手，用于执行特定任务。

🤔 为什么要这样设计？ 这种设计让你可以根据工作阶段，将任务（如“分析代码”和“修改代码”）分配给最合适的 AI 模型和工具集，从而提高效率和安全性。

✅ 验证：理解上述概念即可，无需操作。

第 2 步：使用内置的 Primary Agent ​

🎯 目标：体验 Build 和 Plan 这两个内置主代理的工作模式。

OpenCode 内置了两个关键的 Primary Agent：

1. 使用 Build 代理 ​

📝 操作： 在 OpenCode 中开始一个新会话，默认的代理就是 Build。

  • 特点：拥有所有工具的完全访问权限（文件读写、执行命令等）。
  • 用途：执行实际的开发工作，如编写代码、创建文件。

✅ 验证： 你可以直接向它提问：“帮我创建一个名为 hello.js 的文件，内容为 console.log("Hello, Agent!")”。Build 代理会直接执行操作。

2. 使用 Plan 代理 ​

📝 操作： 在对话中按下 Tab 键，切换到 Plan 代理。

  • 特点：权限受限，默认情况下，所有文件编辑和执行命令都需要你的批准。
  • 用途：用于代码分析、架构规划、生成改进建议，而不会意外修改你的代码。

✅ 验证： 现在，试一下同样的请求：“帮我创建一个名为 hello.js 的文件”。Plan 代理会询问你的许可，而不是直接执行。

💡 提示：在开始编码前，先用 Plan 代理规划，再用 Build 代理实施，是一个高效的工作流。

第 3 步：调用内置的 Subagent ​

🎯 目标：学会如何手动和自动调用 Scout、Explore 等子代理。

OpenCode 内置了三个重要的 Subagent：

1. 手动调用 (@ 提及) ​

📝 操作：在主代理的对话中，输入 @ 符号，然后选择你想调用的子代理。

  • @Explore：快速搜索和浏览你的代码库。例如：@Explore 帮我找到项目中所有使用 fetch 的位置。
  • @Scout：用于研究外部依赖库。例如：@Scout 帮我查看 lodash 库的 cloneDeep 函数的实现。
  • @General：一个全能型子代理，可以执行多步骤的复杂任务。

✅ 验证： 尝试输入 @Explore 帮我看看当前目录的结构。你应该会看到 Explore 子代理执行此任务并返回结果。

2. 自动调用 ​

主代理会根据任务描述自动决定是否需要调用子代理。例如，当主代理需要研究一个外部库时，它会自动使用 Scout。

💡 提示：当子代理创建了子会话时，你可以使用特定的快捷键在会话间导航（如 <Leader>+Down 进入子会话，Up 返回父会话）。具体快捷键请查阅 OpenCode 的 Keybinds 配置。

第 4 步：配置你的第一个自定义代理 ​

🎯 目标：在 opencode.json 文件中创建一个名为 code-reviewer 的只读代码审查代理。

上一步我们学习了如何使用内置代理，现在我们来创建一个属于自己的。

📝 操作：

  1. 打开你的 OpenCode 配置文件 opencode.json（通常位于项目根目录或 ~/.config/opencode/）。

  2. 在 agent 字段下，添加以下配置：

json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    // ... 其他配置
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues", // 代理的描述
      "mode": "subagent", // 设置为子代理
      "model": "anthropic/claude-sonnet-4-20250514", // 指定模型（可选）
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", // 自定义系统提示词
      "permission": {
        "edit": "deny", // 禁止修改文件
        "bash": "deny"  // 禁止执行命令
      }
    }
  }
}

🤔 为什么要这样配置？

  • mode: "subagent" 表示这是一个可以被其他代理调用的专业化工具。
  • permission 字段至关重要，它定义了代理的权限范围。将 edit 和 bash 都设为 deny，确保了审查代理是“只读”的，不会对你的代码造成任何意外更改。

✅ 验证： 保存配置文件后，在 OpenCode 会话中，输入 @，你应该能在列表中找到并选择你新创建的 code-reviewer 代理。

进阶技巧（可选） ​

掌握基础后，你可以尝试更精细的控制：

  1. 精细的 Bash 权限控制：你可以控制代理对特定命令的权限。例如，只允许 git 命令，而其他命令需要询问：
json
// opencode.json 片段
"agent": {
  "build": {
    "permission": {
      "bash": {
        "*": "ask",         // 所有 bash 命令默认需要询问
        "git status *": "allow",  // git status 命令允许执行
        "git push": "ask"         // git push 命令需要询问
      }
    }
  }
}
  1. 使用 Markdown 文件配置代理：除了 JSON，你也可以在 ~/.config/opencode/agents/ 目录下创建 .md 文件来定义代理。文件名即代理名。
markdown
// ~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
Provide constructive feedback without making direct changes.

常见问题 (FAQ) ​

Q1: 为什么我的 @code-reviewer 代理没有出现在列表中？A: 检查你的 opencode.json 文件格式是否正确，特别是 JSON 的逗号和花括号。然后重启 OpenCode 会话。

Q2: 代理的 permission 和全局的 permission 有什么区别？A: 代理级别的 permission 会覆盖全局设置。例如，全局禁止了 edit，但你可以为 Build 代理单独设置 edit: "ask"，这样 Build 代理在编辑文件时就会询问你。

Q3: 如何控制代理的“思考”深度？A: 可以通过 temperature 和 top_p 参数。temperature 值越低（如0.1），回答越确定和专注；值越高（如0.8），回答越有创造性和多样性。top_p 是另一种控制随机性的方式。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 代理类型：理解了 Primary Agent（主代理）和 Subagent（子代理）的核心区别和用途。
  2. 内置代理：掌握了 Build、Plan、Explore、Scout 等内置代理的切换和使用方法。
  3. 配置与自定义：学会了通过 opencode.json 文件创建一个拥有特定提示词和权限的自定义代理。
  4. 权限控制：理解了 permission 字段中 allow、ask、deny 三种模式及其在精细化管理中的应用。

© 2026 LowHow