Back to Blog

OpenCode Agent 系统：Build、Plan 到自定义 Agent

2026-04-27T10:00:00+08:00
OpenCode Agent AI 编程 自定义 Agent

OpenCode Agent 系统：Build、Plan 到自定义 Agent

最近几个月我一直在用 OpenCode 做项目，从最开始只会打字提问，到现在能自己定制 Agent 做代码审查、安全审计、文档生成——这个 Agent 系统真的是越用越顺手。

OpenCode 在 GitHub 上已经超过 140K Star，月活开发者 650 万，它不仅仅是一个 "AI 聊天工具"，而是一个有完整 Agent 架构的编程平台。内置的 Build、Plan、Explore 三个 Agent 各有分工，你还能用 Markdown 文件创建自己的专属 Agent，甚至让 AI 帮你自动生成 Agent 配置。

今天我们就来聊聊 OpenCode 的 Agent 系统，看看它是怎么把 AI 编程这件事做得既有条理又灵活的。

本文提纲

  1. Agent 的两种类型：Primary Agent 和 Subagent
  2. Build Agent——全能选手，拥有完全权限
  3. Plan Agent——只看不动的"军师"
  4. Explore Subagent——快速探索代码库的侦察兵
  5. Markdown 自定义 Agent：一个文件搞定专属助手
  6. opencode agent create：让 AI 帮你写 Agent
  7. Agent 切换与 @ 提及
  8. Permissions：精细化控制每个 Agent 能干什么
  9. 几个实用的自定义 Agent 示例

Agent 的两种类型：Primary Agent 和 Subagent

OpenCode 把 Agent 分成两类：Primary Agent（主 Agent）和 Subagent（子 Agent）。

Primary Agent 是你直接对话的对象。在 TUI 界面里，你用 Tab 键就能在不同 Primary Agent 之间切换，界面右下角会显示当前是哪个 Agent 在工作。

Subagent 不直接出现在主界面，而是被 Primary Agent 按需调用，或者你通过 @ 提及 手动唤醒。比如你在对话中输入 @general help me search for this function，就会唤醒 General Subagent 来帮你处理这个任务。

这种设计的好处很明显：Primary Agent 负责主干对话，Subagent 负责特定领域的辅助任务，分工清晰，不会互相干扰。

OpenCode 内置了两个 Primary Agent（Build 和 Plan）和两个 Subagent（General 和 Explore），另外还有三个隐藏的系统 Agent（Compaction、Title、Summary）在后台默默工作。

Build Agent——全能选手，拥有完全权限

Build 是 OpenCode 的默认 Agent，也是你打开 OpenCode 后第一个面对的"人"。

它拥有所有工具的完整权限：读写文件、执行 Bash 命令、搜索代码、操作 Git、调用 MCP Server……基本上你在终端里能干的事它都能干。不管是新建文件、重构代码、跑测试、还是部署，Build Agent 都是那个"啥都能做"的全能选手。

We need to add authentication to the /settings route. Take a look at how
this is handled in the /notes route in @packages/functions/src/notes.ts
and implement the same logic in @packages/functions/src/settings.ts

你给它一段指令，它就会自己去读相关代码、理解上下文、然后动手改文件。整个过程你只需要确认就行。

不过全能也意味着风险。如果你不放心让它随便改东西，可以通过 permission 配置把某些操作改成 ask 模式——每次执行前先问你一下。这个后面讲 Permissions 的时候会详细说。

默认情况下，Build Agent 的 edit 和 bash 权限都是 allow，也就是说它可以直接修改文件和执行命令，不需要你确认。对于大多数开发者来说，这个默认设置已经够用了——OpenCode 本身有 /undo 命令，改错了可以随时回退。

Plan Agent——只看不动的"军师"

Plan Agent 是另一个内置的 Primary Agent。它的设计哲学很明确：只分析，不动手。

默认情况下，Plan Agent 的 file edits 和 bash 权限都设成了 ask。也就是说，它想改文件或执行命令的时候，会先问你要不要允许。这个设计确保了 Plan Agent 只做分析和规划，不会悄悄改你的代码。

使用场景很明确：

  • 你想让 AI 先帮你分析一下代码结构，再决定怎么改
  • 你想做一个新功能，但不确定最佳实现方案
  • 你在做 Code Review，只需要 AI 给建议，不需要它直接改

切换到 Plan Agent 的方法很简单：按 Tab 键。界面上会显示当前切换到了 Plan 模式。在 Plan 模式下描述你想要的功能，AI 会给出详细的实现方案和步骤。看完方案后觉得没问题，再按 Tab 切回 Build Agent，让它按方案执行。

When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.

Plan Agent 会分析你的代码库，理解现有的数据模型和路由结构，然后给出一个分步骤的实现计划。你可以反复跟它讨论细节，等方案成熟了再让 Build Agent 动手。

这种 "先 Plan 后 Build" 的工作流，比上来就让 AI 直接改代码要靠谱得多。特别是面对复杂功能的时候，先花几分钟规划一下，往往能省下后面几小时的调试时间。

Explore Subagent——快速探索代码库的侦察兵

Explore 是一个内置的 Subagent，特点是只读——它不能修改任何文件。

它的用途是在大型代码库中快速定位信息。比如你刚接手一个不熟悉的项目，想知道某个功能是在哪里实现的、数据库连接是怎么配置的、某个 API 的入口在哪——这些探索性的任务交给 Explore 就对了。

Explore 的速度很快，因为它不需要走修改文件的流程。它用的工具主要是 read、glob、grep、list 这些只读操作，专注于信息检索和代码理解。

你可以通过 @ 提及来手动调用它：

@explore find all files related to user authentication

不过更多时候，Primary Agent 会根据任务需要自动调用 Explore。当 Build Agent 需要查找某段代码但不想打断当前的工作流时，它会在后台派 Explore 去搜索，拿到结果后继续工作。

这种主从协作的模式，让 Agent 的分工更高效——Build 专注写代码，Explore 专注找代码，各司其职。

Markdown 自定义 Agent：一个文件搞定专属助手

OpenCode 最让我兴奋的功能之一，就是用 Markdown 文件创建自定义 Agent。

你只需要在 .opencode/agents/ 目录下放一个 .md 文件，文件名就是 Agent 的名字。文件开头用 YAML frontmatter 定义配置，后面写系统提示词，搞定。

举个例子，创建一个代码审查 Agent：

---
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.

把这个文件保存为 .opencode/agents/review.md，一个名叫 review 的 Subagent 就注册好了。

可配置的选项非常丰富：

  • description：描述 Agent 的用途，这是必填项
  • mode：primary、subagent 或 all
  • model：为这个 Agent 指定不同的 LLM 模型
  • temperature：控制回复的随机性和创造性
  • steps：最大迭代次数，控制成本
  • permission：精细化控制各种操作的权限
  • color：在 UI 中自定义 Agent 的显示颜色
  • hidden：隐藏 Subagent，不让它出现在 @ 自动补全菜单里

除了项目级的 .opencode/agents/ 目录，你还可以把 Agent 放在全局配置目录 ~/.config/opencode/agents/，这样所有项目都能用。

如果你更喜欢 JSON 配置，也可以在 opencode.json 里定义 Agent。不过我个人推荐 Markdown 方式——写提示词的时候更直观，而且可以用 {file:./prompts/build.txt} 引用外部文件，方便管理。

opencode agent create：让 AI 帮你写 Agent

如果你不想手动写 Agent 配置文件，OpenCode 提供了一个交互式命令：

opencode agent create

运行后会进入一个交互流程：

  1. 选择存放位置：全局（~/.config/opencode/agents/）还是项目级（.opencode/agents/）
  2. 描述 Agent 的用途：用自然语言告诉它这个 Agent 要做什么
  3. AI 生成配置：OpenCode 会根据你的描述自动生成系统提示词和 Agent 标识符
  4. 选择权限：让你勾选这个 Agent 应该拥有哪些权限，没勾选的都会被禁止
  5. 生成 Markdown 文件：最终创建一个配置好的 .md 文件

整个过程大概两分钟就能搞定。你只需要告诉它"我要一个做安全审计的 Agent"，它就能帮你生成一个配置完善的 security-auditor.md。

这个功能对新手特别友好——不用去记各种配置选项的语法，用自然语言描述需求就行。而且 AI 生成的提示词通常比你自己写的更全面、更结构化。

Agent 切换与 @ 提及

OpenCode 提供了多种方式在不同 Agent 之间切换：

Tab 键切换 Primary Agent：在 TUI 界面中，按 Tab 键可以在 Build 和 Plan 之间切换。如果你创建了自定义 Primary Agent，它们也会出现在切换循环中。右下角会显示当前活跃的 Agent 名称。

@ 提及调用 Subagent：在消息中用 @agent-name 的格式可以手动调用任何 Subagent。比如 @general help me research this API 或 @explore find the database schema。输入 @ 后会出现自动补全菜单，列出所有可用的 Subagent。

自动调用：Primary Agent 会根据任务的需要自动决定是否调用 Subagent。比如 Build Agent 需要搜索大量代码时，可能会在后台调用 Explore 来并行处理。

当你想查看 Subagent 的工作成果时，可以用快捷键导航：

  • <Leader>+Down 进入第一个子 Session
  • Right 切换到下一个子 Session
  • Left 切换到上一个子 Session
  • Up 返回父 Session

这样你就能在主对话和各个 Subagent 的子任务之间自由跳转，查看每个 Agent 的详细工作过程。

Permissions：精细化控制每个 Agent 能干什么

Permissions 是 OpenCode Agent 系统的安全基石。每个权限项都可以设成三种状态：

  • allow：允许，不需要确认
  • ask：每次执行前先问用户
  • deny：直接禁止

可控制的权限项覆盖了所有操作类型：

权限 Key 控制的工具
read 文件读取
edit write、edit、apply_patch
bash Bash 命令执行
glob 文件搜索
grep 内容搜索
task 调用 Subagent
webfetch 网页抓取
skill 加载 Agent Skill
lsp LSP 语言服务

bash 权限还支持按命令粒度控制。你可以精确到某条命令允许、某条命令禁止：

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

支持 glob 模式匹配，git * 会匹配所有以 git 开头的命令。规则按顺序匹配，最后匹配到的规则生效。

还有一个很实用的 task 权限，可以控制某个 Agent 能调用哪些 Subagent：

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

这样你就能设计出有层级关系的 Agent 架构——Orchestrator 只能调用特定前缀的 Subagent，调用 code-reviewer 时还需要用户确认。

几个实用的自定义 Agent 示例

最后分享几个我日常在用的自定义 Agent 配置，给大家一些灵感。

Security Auditor

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "grep *": allow
  webfetch: deny
---

You are a security expert. Focus on identifying potential security issues.
Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

项目上线前跑一遍 Security Auditor，能发现不少你平时没注意到的安全隐患。

Documentation Writer

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.
Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

这个 Agent 只能读写文件，不能执行任何 Bash 命令。让它去写文档的时候不用担心它误操作。

Quick Thinker

---
description: Fast reasoning with limited iterations for quick answers
mode: subagent
steps: 5
temperature: 0.1
prompt: "You are a quick thinker. Solve problems with minimal steps. Be concise."

设置了 steps: 5 的迭代上限，5 步之内必须给出答案。适合需要快速反馈的简单问题，还能控制 Token 消耗。

OpenCode 的 Agent 系统把 AI 编程从"一个人干所有事"变成了"一个团队协作"。Build 负责写代码，Plan 负责规划，Explore 负责搜索，你还可以根据需要添加 Security Auditor、Documentation Writer 等专家角色。加上精细化的 Permissions 控制和 Markdown 配置方式，整个系统既灵活又安全。

如果你还没试过自定义 Agent，建议从 opencode agent create 开始，让 AI 帮你生成第一个专属 Agent，体验一下就懂了。

作者: itech001 来源: 公众号：AI人工智能时代 主页: https://www.theaiera.cn（每日分享最前沿的AI新闻和技术）

关注公众号，获取更多 AI 技术干货！

Enjoyed this article? Share it with others!