OpenCode 代理系统完全指南：Build / Plan 双模式与自定义 Agent 实战

OpenCode 代理系统完全指南：Build / Plan 双模式与自定义 Agent 实战

引言

使用 OpenCode 进行 AI 辅助编程时，你有没有想过这样一个问题：为什么有时候 AI 直接上手修改代码，有时候却只是给出建议？答案就在 OpenCode 的代理系统（Agent System）中。与许多 AI 编程助手不同，OpenCode 将交互模式抽象为「代理」的概念，通过不同的代理来实现开发、规划、探索等多种工作流。

本文将从 OpenCode 的代理架构出发，深入讲解 Build 和 Plan 两大内置模式的使用方法，以及如何创建自定义代理来满足特定需求。掌握了代理系统，你将能够更精准地控制 AI 的行为，让它在合适的场景充当合适的角色。

什么是代理系统？

在 OpenCode 中，代理是一个拥有独立系统提示、模型配置、工具权限和温度参数的 AI 角色。每个代理都是一份「角色说明书」，告诉 AI 它应该怎么工作、能做什么、不能做什么。

代理分为两类：

• 主代理（Primary Agent）：直接与你对话的代理，负责处理你的主要需求。你可以通过 Tab 键在主代理之间快速切换。
• 子代理（Subagent）：由主代理或你通过 @ 提及调用的专用代理，擅长执行特定子任务，如搜索代码、调研文档等。

OpenCode 内置了两个主代理——Build 和 Plan，以及三个子代理——General、Explore 和 Scout。

Build 模式：默认开发模式

Build 是 OpenCode 的默认主代理，也是使用频率最高的模式。它的特点是拥有完整的工具权限，包括文件读写、编辑、Bash 命令执行、网络请求等所有内置工具。

当你运行 opencode 进入 TUI 时，默认就处于 Build 模式。右下角会显示当前代理名称。在这个模式下，你可以：

• 要求 AI 直接修改代码、创建文件
• 执行 Shell 命令来运行测试、构建项目
• 安装依赖、调试程序
• 进行大规模的代码重构

Build 模式的工具配置也可以自定义。例如，如果你希望在 Build 模式下某些操作需要确认：

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "git push": "ask",
          "*": "allow"
        }
      }
    }
  }
}

这样配置后，编辑文件时会弹出确认提示，而 git push 这类危险操作也需要你手动批准。

Plan 模式：先规划，再动手

如果说 Build 是执行者，那么 Plan 就是规划师。Plan 模式是一个受限代理，默认对所有编辑操作和 Bash 命令设置为 ask（需要确认），这意味着 AI 会先给出方案和建议，再等你批准后才能执行。

这是 Plan 模式的核心用途：

分析代码：让 AI 阅读代码并给出理解，而不触碰任何文件

生成计划：在动手之前，让 AI 制定详细的实施步骤

代码审查：检查代码质量、安全性和性能问题

分支探索：在不确定最佳方案时，让 AI 提供多个选项

在 TUI 中按 Tab 键即可在 Build 和 Plan 之间切换。切换后，右下角的代理名称会随之变化，提示你当前处于哪个模式。

你也可以在配置中调整 Plan 的行为：

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

将 Plan 模式的编辑和 Bash 设置为 deny，它就无法执行任何修改操作，成为纯粹的只读视角。或者设置为 ask，让 AI 可以先提出方案，经你确认后再执行。

代理切换与使用技巧

在 TUI 中使用代理有几种方式：

Tab 键循环切换：按 Tab 键在主代理列表中循环。如果只有 Build 和 Plan 两个主代理，每次 Tab 就在两者之间切换。反向切换使用 Shift + Tab。

默认代理：你可以通过 default_agent 配置设置启动时默认使用的代理：

{
  "default_agent": "plan"
}

设置后，启动 OpenCode 时默认进入 Plan 模式。这在审阅代码或制定方案时特别有用。

@ 提及子代理：在消息中使用 @ 可以调用子代理。例如：

@explore 帮我找到所有与认证相关的路由定义

这会启动 Explore 子代理来搜索代码，然后将结果返回给当前会话。

会话导航：当子代理创建了子会话时，使用 <Leader>+Down 进入子会话，用左右键在子会话间切换，用上键返回父会话。

模型变体切换：按 Ctrl + T 可以循环切换模型的推理变体（如高/中/低推理力度），这在处理不同复杂度的任务时很实用。

创建自定义代理

内置的 Build 和 Plan 满足大多数场景，但 OpenCode 更重要的是它允许你自定义代理。你可以创建自己的代理来应对特定场景。

通过 JSON 配置

在 opencode.json 中定义：

{
  "agent": {
    "code-reviewer": {
      "description": "审查代码质量和安全性",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "deny",
          "git diff*": "allow",
          "grep *": "allow"
        }
      },
      "prompt": "你是一名代码审查专家。重点关注安全漏洞、性能问题和代码可维护性。只给出建议，不修改代码。"
    }
  }
}

关键配置项说明：

• description：代理的描述（必填），决定了 AI 何时会自动调用该子代理
• mode：primary、subagent 或 all（不指定时默认为 all，即既可作为主代理也可被子代理调用）
• model：指定使用的模型，不指定则沿用主代理模型
• temperature：控制随机性，代码审查等精确任务建议用 0.1
• permission：精细控制工具权限
• prompt：自定义系统提示词

通过 Markdown 文件配置

代理也可以使用 Markdown 文件定义。将文件放在以下目录：

• 全局：~/.config/opencode/agents/
• 项目级：.opencode/agents/

文件名就是代理名。例如 .opencode/agents/security.md：

---
description: 安全审计专用代理
mode: subagent
model: anthropic/claude-haiku-4-5
permission:
  edit: deny
  bash: deny
---

你是一名安全审计专家，专注于发现代码中的安全隐患：

- SQL 注入和命令注入
- XSS 和 CSRF
- 认证与会话管理缺陷
- 敏感信息泄露
- 依赖安全问题

提供具体的修复建议和代码示例。

使用 CLI 创建

OpenCode 还提供了 opencode agent create 命令，可以交互式地创建代理：

opencode agent create

按照提示选择保存位置、填写描述、选择权限即可快速生成。

代理实战场景

场景一：编码前的规划

在开始实现复杂功能前，切换到 Plan 模式制定方案——让 AI 分析现有代码结构，梳理实现路径，评估可能的风险。满意后再切换到 Build 模式开始编码。这能有效减少返工。

场景二：并行代码调研

在 Build 会话中，通过 @explore 并发搜索多个代码位置，而不中断主会话。Explore 子代理创建的子会话在后台运行，完成结果后自动汇入主会话。

场景三：自动化代码审查

配置一个 code-reviewer 子代理，在完成代码修改后通过 @code-reviewer 审查我刚做的更改 来触发审查。由于设置了 edit: deny，它只会给出建议而不会改代码。

场景四：专用于特定框架的代理

为 Laravel 项目创建一个专属代理，内置框架最佳实践提示：

{
  "agent": {
    "laravel-dev": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一名 Laravel 开发专家。遵循 Laravel 最佳实践：使用 Eloquent ORM 而非查询构建器、使用 Form Request 做验证、使用 Repository 模式隔离数据层、编写 Feature Test。",
      "permission": {
        "edit": "allow",
        "bash": {
          "artisan *": "allow",
          "composer *": "allow",
          "*": "ask"
        }
      }
    }
  }
}

代理配置最佳实践

description 一定要写：它是 AI 判断何时调用子代理的依据，描述越准确，自动调用的时机越精准。

按风险等级配置权限：只读代理设置 edit: deny, bash: deny；开发代理可以开放权限；需要监督的操作设为 ask。

合理设置温度：代码分析和审查用低温（0.1~0.2），创意性任务（如写文档、生成测试数据）可以调高至 0.5~0.7。

为不同任务选择不同模型：规划和分析可以用小模型（如 Haiku）来节省成本，代码生成和重构用大模型（如 Sonnet）以保证质量。

避免权限过于宽松：即使对于 Build 模式，也建议对 git push、rm -rf 等危险命令设置 ask 权限。

总结

OpenCode 的代理系统是其区别于其他 AI 编程助手的核心特性之一。通过 Build 和 Plan 双模式的灵活切换，你可以在「执行」和「规划」两种角色之间自由切换；通过自定义代理，你可以为每一个特定任务创建最合适的 AI 角色。

掌握代理系统的精髓在于：让 AI 在合适的场景以合适的身份做合适的事。从今往后，不要再让 AI 一股脑地改代码了——先切换到 Plan 模式，让它制定一个清晰的方案，再用 Build 模式稳步推进。这套工作流程能显著提升你的开发效率和代码质量。