配置 Agents

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

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

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

先记住这个判断：

OpenCode 的 Agent 分工模型

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

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 在主代理之间切换。子代理更像临时请来的专项助手，可以由主代理自动调用，也可以用 @ 指定。

@explore find where authentication is handled

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

什么时候创建自定义 Agent

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

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

用 Markdown 定义一个只读审查 Agent

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

---
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. 只是意图说明，不应该承担安全边界。

配置字段怎么判断

先记住这些字段就够了：

权限比提示词可靠

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

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 解决的，不必先造一个新名字。

接下来去哪

官方资料

• OpenCode agents
• OpenCode configuration