配置 Agents

理解 OpenCode 里的 Build、Plan、Explore、General，以及什么时候创建自己的 Agent。

Agent 的核心不是“多几个角色名”，而是把不同工作模式分开：有的模式负责动手改代码，有的模式负责只读分析，有的模式负责并行探索。

官方教程给出了主代理、子代理、内置代理、配置字段和权限写法。这里按新手视角讲：日常应该怎么用，什么时候才需要自定义。

先理解它解决什么问题

新手刚开始用 AI 编程工具时，常见问题是把所有任务都交给同一个会话：

让模型一边理解代码，一边规划，一边改文件。
想让它只分析，但它开始动手改。
想并行查几个问题，但上下文混在一起。

Agent 就是为了解决这个边界问题。你可以让不同 Agent 承担不同职责，降低误改、跑偏和上下文污染。

先用内置 Agent

新手不需要一开始就创建一堆自定义 Agent。先把内置的四个用熟：

Build：默认动手型主代理。适合实现功能、修 bug、改文件、运行命令。
Plan：规划和分析型主代理。适合先看代码、评估方案、做 review，不希望它直接改文件。
Explore：只读探索型子代理。适合快速搜索代码、回答“这个逻辑在哪”。
General：通用子代理。适合相对独立的研究或多步骤任务。

实际工作里，一个稳妥流程是：先用 `Plan` 理清方案，再切到 `Build` 执行；遇到代码库很大时，用 `Explore` 查结构。

主代理和子代理

主代理是你正在直接对话的工作模式。OpenCode 里可以通过 Tab 在主代理之间切换。

子代理更像临时请来的专项助手。你可以让主代理自动调用，也可以在消息里用 @ 指定：

@explore find where authentication is handled

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

什么时候创建自定义 Agent

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

适合创建：

只读代码审查。
安全检查。
文档维护。
数据库迁移规划。
某个项目固定的发布前检查。

不适合创建：

一次性任务。
你还没想清楚输出标准的任务。
只是为了换一个角色名。

文件名就是 Agent 名。`review.md` 对应 `@review`。

配置字段怎么理解

新手先记住这几个字段就够了：

description：模型判断何时调用它的依据，必须写清楚场景。
mode：primary 表示可直接切换的主代理，subagent 表示专项子代理。
permission：限制它能不能改文件、跑命令、访问网页。
model：只有任务确实需要不同模型时再指定。
temperature：分析、审查、迁移这类任务用低温；头脑风暴可以稍高。
steps：限制最多迭代多少步，用来控制成本和跑偏。

官方旧文档里还会看到 `tools`，但现在更推荐用 `permission` 表达允许、询问或拒绝。

权限比提示词更可靠

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

permission:
  edit: deny
  bash: ask

提示词是意图，权限是边界。新手最容易忽略这点。

怎么判断 Agent 写对了

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

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

如果你发现每次调用都要补充“不要改文件”“只看安全问题”“先给计划”，说明这些规则应该写进 Agent。

新手常见坑

创建太多 Agent。数量多不等于效率高，常用的 3-5 个就够。
description 写得太抽象。模型会根据它判断是否调用，不能只写 “helpful assistant”。
把主代理和子代理混用。长期对话用主代理，专项隔离用子代理。
只写提示词，不配权限。涉及文件修改、命令执行时，权限才是底线。

最近更新： 2026年5月1日