---
title: "配置 Agents"
description: "理解 OpenCode 里的 Build、Plan、Explore、General，以及什么时候创建自己的 Agent。"
verifiedAt: "2026-05-09"
---

Agent 不是“给模型换几个角色名”。它真正解决的是边界：什么时候可以改文件，什么时候只能分析，什么时候可以把一个独立问题丢给子任务。

> [!NOTE]
> **这一篇用 8 分钟换什么**：看完以后，你应该能判断该用 `Build`、`Plan`、`Explore` 还是 `General`，并能写出一个不会乱改文件的自定义 Agent。

## 先给结论：先用内置 Agent，再自定义

新手最常见的错误，是还没用熟 OpenCode 自带的 Agent，就先创建一堆“架构师”“审查员”“文档专家”。这通常不会让工作更清楚，反而会把边界搞乱。

先记住这个判断：

| 场景 | 优先用谁 | 原因 |
| --- | --- | --- |
| 实现功能、修 bug、改文件 | `Build` | 默认动手型主代理 |
| 先看代码、评估方案、做 review | `Plan` | 更适合规划和分析 |
| 查某段逻辑在哪里 | `Explore` | 只读探索，适合隔离上下文 |
| 独立研究、多步骤旁路任务 | `General` | 通用子代理，不干扰主线 |

> [!IMPORTANT]
> Agent 的质量不看名字多专业，而看职责、权限和输出是否稳定。一个只读审查 Agent 默认能改文件，就是边界失败。

## OpenCode 的 Agent 分工模型

OpenCode 里同时有主代理和子代理。主代理是你正在直接对话的工作模式；子代理是为某个专项任务临时启动的隔离上下文。

```mermaid
flowchart LR
  User[你的任务] --> Need{这一步要什么}
  Need -->|要改代码| Build[Build 主代理]
  Need -->|要先想清楚| Plan[Plan 主代理]
  Need -->|只读找线索| Explore[Explore 子代理]
  Need -->|独立旁路任务| General[General 子代理]
  Plan --> Build
  Explore --> Build
  General --> Build
```

一个稳妥流程是：先用 `Plan` 理清方案，再切到 `Build` 执行；代码库很大时，用 `Explore` 查结构，把结果带回主线。

## 主代理和子代理怎么选

主代理适合承接当前会话的长期工作。OpenCode 里可以通过 **Tab** 在主代理之间切换。子代理更像临时请来的专项助手，可以由主代理自动调用，也可以用 `@` 指定。

```txt
@explore find where authentication is handled
```

| 类型 | 适合做 | 不适合做 |
| --- | --- | --- |
| 主代理 | 持续规划、执行、改文件、承接上下文 | 同时塞进多个互不相关的调查任务 |
| 子代理 | 只读搜索、专项 review、独立研究 | 替代主会话长期推进复杂改动 |

不要把子代理当成“更强模型”。它的价值是隔离任务：让探索、审查、资料查找不污染主会话。

## 什么时候创建自定义 Agent

只有当某类任务反复出现，并且需要稳定边界时，才值得创建自定义 Agent。

| 适合创建 | 暂时别创建 |
| --- | --- |
| 只读代码审查 | 一次性问题 |
| 安全检查 | 只是想换一个角色名 |
| 文档维护 | 输出标准还没想清楚 |
| 数据库迁移规划 | 每次都要临场补很多要求 |
| 固定发布前检查 | 和现有内置 Agent 重叠太多 |

如果你每次都要补充“不要改文件”“只看安全风险”“先列计划”，这些规则就应该进入 Agent 定义。

## 用 Markdown 定义一个只读审查 Agent

新手优先用 Markdown 文件定义 Agent，比把大段 JSON 塞进 `opencode.json` 更清楚。文件名就是 Agent 名，`.opencode/agents/review.md` 对应 `@review`。

```md
---
description: Review code without editing files
mode: subagent
permission:
  edit: deny
  bash: ask
---

Review the current change.
Focus on bugs, security, regressions, and missing tests.
Do not edit files.
```

这个例子里，真正起边界作用的是 `permission.edit: deny`。最后一行 `Do not edit files.` 只是意图说明，不应该承担安全边界。

## 配置字段怎么判断

先记住这些字段就够了：

| 字段 | 作用 | 新手判断 |
| --- | --- | --- |
| `description` | 让模型判断什么时候调用它 | 写具体场景，不写空泛人格 |
| `mode` | 决定是主代理还是子代理 | 长期工作用 `primary`，专项隔离用 `subagent` |
| `permission` | 限制文件、命令、网络等能力 | 涉及安全边界时必须写 |
| `model` | 指定模型 | 只有任务确实需要不同模型时再指定 |
| `temperature` | 控制随机性 | 审查、迁移、排障偏低；脑暴可以稍高 |
| `steps` | 限制最多迭代步数 | 用来控制成本和跑偏 |
| `disable` | 禁用某个 Agent | 临时停用比删除更稳 |
| `prompt` | 指向外部提示词文件 | 长提示词复用时再用 |

> [!WARNING]
> 旧资料里可能出现 `maxSteps`。现在优先用 `steps` 表达最大迭代步数，避免新旧字段混用。

## 权限比提示词可靠

不要只在提示词里写“不要改文件”。如果你真的不希望它改文件，就用权限限制：

```yaml
permission:
  edit: deny
  bash: ask
```

提示词是意图，权限是边界。尤其是代码审查、安全检查、发布前检查这类任务，权限要和职责一致。

## 怎么判断 Agent 写对了

一个好 Agent 应该有稳定行为：

- 看到 `description` 就知道什么时候该用。
- 任务范围窄，不是什么都想做。
- 权限和职责一致：审查 Agent 不应默认能改文件。
- 输出结构稳定，例如总是先列风险，再列建议测试。
- 不需要你每次额外解释一大段背景。

把它跑 2-3 次，如果每次都要临场补同一句限制，就把限制写回 Agent。Agent 不是一次性 prompt，而是可复用的工作边界。

## 新手常见坑

- 创建太多 Agent。数量多不等于效率高，先把常用的 3-5 个打磨稳定。
- `description` 写得太抽象。模型会根据它判断是否调用，不能只写 “helpful assistant”。
- 把主代理和子代理混用。长期对话用主代理，专项隔离用子代理。
- 只写提示词，不配权限。涉及文件修改、命令执行时，权限才是底线。
- 自定义 Agent 和内置 Agent 重叠。能用 `Plan`、`Build`、`Explore` 解决的，不必先造一个新名字。

## 接下来去哪

<Cards>
  <Card title="配置 Skills" href="/docs/opencode/official/02-agents-skills/skills">
    学会把可复用能力沉淀成 Skill，而不是每次靠临时提示词。
  </Card>
  <Card title="配置 Plugins" href="/docs/opencode/official/02-agents-skills/plugins">
    理解什么时候需要插件，什么时候内置 Agent 和 Skill 已经够用。
  </Card>
  <Card title="配置 Rules" href="/docs/opencode/official/02-agents-skills/rules">
    把项目约束写成长期规则，让 Agent 默认按同一套边界工作。
  </Card>
  <Card title="Agents、Skills、Plugins 怎么分" href="/docs/opencode/understanding/05-agents-skills-plugins">
    用更完整的视角理解三者分工，避免把所有问题都塞进 Agent。
  </Card>
</Cards>

## 官方资料

- [OpenCode agents](https://opencode.ai/docs/agents/)
- [OpenCode configuration](https://opencode.ai/docs/config/)
