叶云梦天

OpenCode Agent 配置完全指南：打造专属的 AI 编程助手团队

OpenCode 内置了一个强大的 Agent（智能体）系统，允许你将 AI 编程助手拆分为多个"角色"，每个角色专注于特定的任务领域。你可以理解它为一种"AI 编程团队"的配置方式：有负责写代码的、有负责审查的、有负责搜索文档的，各司其职。这篇指南将从零开始，带你掌握 OpenCode Agent 系统的全部细节。

Agent 是什么

在 OpenCode 中，Agent 就是一个带有特定系统提示词、权限和模型配置的 AI 会话实例。每个 Agent 可以有自己的"人设"：代码审查员只看不写，文档写手专门生成文档，安全审计员专注于漏洞检查。通过将不同性质的任务分配给不同的 Agent，你可以避免单一 Agent 上下文过载、提升输出的专业度，并控制不同任务的安全边界。

OpenCode 的 Agent 分为两种类型：主 Agent（Primary Agent） 和 子 Agent（Subagent）。

主 Agent

主 Agent 是你在终端中直接交互的对象。按 Tab 键（或配置的 switch_agent 快捷键）可以在不同主 Agent 之间切换。OpenCode 内置了两个主 Agent：

Build：默认的主 Agent，拥有所有工具的完全访问权限。适合日常编码开发。
Plan：受限的分析型 Agent。默认所有文件编辑和 bash 命令都被设置为"询问模式"（ask），意味着它在修改代码前必须经过你同意。适合代码分析和方案规划。

你可以让 Plan Agent 先分析问题、制定方案，再切回 Build Agent 执行。这个流程就是 Plan 模式与 Build 模式的协作方式。

子 Agent

子 Agent 不能直接作为终端对话对象。它们由主 Agent 通过 Task 工具自动调用，或者你可以通过 @ 提及来手动触发。OpenCode 内置了三个子 Agent：

General：通用型 Agent，具备完整工具访问权限，能修改文件。适合执行多步骤的复杂任务。
Explore：快速探索型 Agent，只读权限，不能修改文件。适合快速搜索代码库、查找文件模式。
Scout：外部参考型 Agent，只读权限，用于克隆依赖仓库到 OpenCode 管理的缓存中、检查库源码、交叉引用本地代码与上游实现。

此外还有三个隐藏的系统 Agent（Compaction、Title、Summary），它们不显示在 UI 中，在需要时自动运行，负责上下文压缩、会话标题生成和摘要创建。

创建你的第一个自定义 Agent

我们从一个实际场景入手：假设你需要一个代码审查员，它只读代码、输出建议，不修改任何文件。用 Markdown 文件方式创建是最快的途径。

在项目根目录下创建 .opencode/agents/code-reviewer.md：

---
description: 审查代码质量与最佳实践
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

你是一名资深代码审查员。审查代码时请关注：

- 代码质量与最佳实践
- 潜在的 bug 和边界情况
- 性能影响
- 安全风险

请仅提供改进建议，不要直接修改代码。每条建议要附带具体行号和修改方案。

文件名 code-reviewer 就是 Agent 的名称。现在在 TUI 中输入 @code-reviewer 审查 src/utils/parser.ts 就能调用它。

除了 Markdown 方式，你也可以在 opencode.json 中用 JSON 配置：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码质量与最佳实践",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      },
      "prompt": "你是一名资深代码审查员。审查代码时请关注代码质量、潜在 bug、性能和安全风险。仅提供建议，不要修改代码。"
    }
  }
}

两种方式效果一致，选择你习惯的即可。Markdown 方式的好处是 prompt 可以写得更长、排版更好；JSON 方式则适合集中管理。

配置选项详解

description（必填）

描述 Agent 的用途和适用场景。主 Agent 根据这个描述决定何时自动调用子 Agent。

{
  "agent": {
    "security-scanner": {
      "description": "扫描代码中的安全漏洞和敏感信息泄露"
    }
  }
}

mode

决定 Agent 的使用方式，可选值为 primary、subagent、all，默认为 all。

primary：可作为主 Agent 切换使用
subagent：只能作为子 Agent 被调用
all：两种方式均可

model

为 Agent 指定独立的模型。未指定时，主 Agent 使用全局配置的模型，子 Agent 则继承调用它的主 Agent 的模型。

{
  "agent": {
    "fast-scout": {
      "mode": "subagent",
      "model": "anthropic/claude-haiku-4-20250514",
      "description": "快速搜索代码库，不含推理"
    }
  }
}

使用场景很明确：Plan Agent 用轻量的 Haiku 快速分析，Build Agent 用 Sonnet 编写代码，复杂重构任务用 Opus。

temperature

控制模型输出的随机性，范围 0.0 到 1.0：

0.0 – 0.2：高度聚焦和确定性，适合代码分析、测试生成
0.3 – 0.5：平衡输出，适合通用开发任务
0.6 – 1.0：创造性输出，适合头脑风暴和方案探索

{
  "agent": {
    "brainstorm": {
      "description": "头脑风暴和方案探索",
      "temperature": 0.8,
      "permission": { "edit": "deny" }
    }
  }
}

steps

限制 Agent 的最多迭代步数。达到上限后，Agent 会收到系统指令停止行动并输出当前工作总结。适合控制 API 调用成本。

{
  "agent": {
    "quick-thinker": {
      "description": "快速推理，限制步骤数",
      "steps": 5,
      "mode": "subagent"
    }
  }
}

hidden

隐藏子 Agent，使其不出现在 @ 自动补全菜单中。适用于只应由其他 Agent 通过 Task 工具程序化调用的内部 Agent。

{
  "agent": {
    "internal-indexer": {
      "mode": "subagent",
      "hidden": true,
      "description": "内部项目索引器"
    }
  }
}

color

在 UI 中为 Agent 设置颜色，支持 hex 色值或主题色名称：primary、secondary、accent、success、warning、error、info。

{
  "agent": {
    "code-reviewer": { "color": "warning" },
    "security-scanner": { "color": "error" }
  }
}

prompt

为 Agent 指定自定义系统提示词文件。路径相对于配置文件所在目录。

{
  "agent": {
    "docs-writer": {
      "description": "撰写和维护项目文档",
      "mode": "subagent",
      "prompt": "{file:./prompts/docs-writer.txt}"
    }
  }
}

disable

设为 true 禁用该 Agent。

top_p 与额外参数

top_p 是 temperature 的替代方案，控制输出多样性。此外，任何未列出的配置项都会作为模型参数透传给提供商：

{
  "agent": {
    "deep-thinker": {
      "description": "复杂问题深度推理",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

reasoningEffort 和 textVerbosity 会直接透传给 OpenAI 的 API，让你可以使用提供商特定的高级参数。

权限管理：精确控制 Agent 的能力边界

Agent 系统的核心价值之一就是精细化的权限控制。每个 Agent 可以拥有独立的权限配置。

可用的权限键及其管控范围：

| 权限键 | 管控工具 |
|--------|----------|
| read | 文件读取 |
| edit | 文件写入、编辑、补丁 |
| glob | 文件模式匹配 |
| grep | 代码内容搜索 |
| bash | 终端命令执行 |
| task | 调用子 Agent |
| webfetch | 网页抓取 |
| websearch | 网络搜索 |
| lsp | LSP 语言服务 |
| skill | 技能调用 |

每个键可设为 allow（允许）、ask（询问）、deny（拒绝）。bash、edit、task 等键还支持更细粒度的 glob 模式匹配：

{
  "agent": {
    "safe-build": {
      "mode": "primary",
      "permission": {
        "edit": "allow",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow",
          "npm run *": "allow"
        }
      }
    }
  }
}

上面的配置让 Agent 可以自由编辑文件，但对 bash 命令做了分类：git status、git diff、npm run 这类安全的命令直接放行，其他命令（如 rm -rf、git push）需要询问确认。规则按顺序匹配，最后匹配的规则生效，所以把 * 放前面、具体规则放后面是推荐的做法。

Task 权限：控制 Agent 可以调用哪些子 Agent

这是一个独特的权限维度：你可以限定某个 Agent 只能调用特定的子 Agent：

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

被 deny 的子 Agent 会从 Task 工具的描述中完全移除，模型不会尝试调用它。注意用户始终可以通过 @ 手动调用任何子 Agent，Task 权限只影响主 Agent 的自动调用行为。

使用 `opencode agent create` 快速创建

OpenCode 还提供了一个交互式命令行工具来创建 Agent：

opencode agent create

执行后会引导你完成以下步骤：

选择 Agent 的存储位置（全局或项目级）

输入 Agent 的描述

自动生成系统提示词和标识符

选择允许的权限（未选中的会被拒绝）

生成 Markdown 配置文件

这个命令适合那些不想手写配置的开发者，交互式引导能帮你快速上手。

实战案例

案例一：安全审计 Agent

---
description: 执行安全审计并识别漏洞
mode: subagent
temperature: 0.1
permission:
  edit: deny
  bash:
    "*": ask
    "grep *": allow
  webfetch: allow
  websearch: allow
---

你是一名安全专家。审查代码时请关注：

- 输入验证漏洞（SQL 注入、XSS、命令注入）
- 认证与授权缺陷
- 敏感数据泄露风险
- 依赖库已知漏洞（必要时搜索 CVE 数据库）
- 配置安全隐患

每条发现需包含：漏洞类型、风险等级（高/中/低）、具体文件位置、修复建议。

案例二：文档生成 Agent

---
description: 为项目生成高质量的 API 文档
mode: subagent
permission:
  edit: allow
  bash:
    "*": deny
---

你是一名技术文档撰写专家。根据代码生成文档时请注意：

- 清晰的 API 参数和返回值说明
- 包含可直接运行的使用示例
- 组织结构清晰，便于开发者快速查找
- 语言简洁、专业

案例三：主 Agent 层级定制

有时你想为项目定制默认的 Build Agent 行为，比如全局禁用某些危险命令：

{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": {
        "bash": {
          "*": "allow",
          "git push*": "ask",
          "rm -rf *": "ask",
          "npm publish*": "ask"
        }
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "temperature": 0.1
    }
  }
}

这样做的好处是：不改动全局配置，只在当前项目中施加约束，团队成员 checkout 后自动生效。

子 Agent 会话导航

当主 Agent 派生子 Agent 执行任务时，每个子 Agent 运行在自己的会话中。你可以通过以下快捷键在会话树中导航：

<Leader>+Down（默认 session_child_first）：进入第一个子会话
Right（默认 session_child_cycle）：切换到下一个子会话
Left（默认 session_child_cycle_reverse）：切换到上一个子会话
Up（默认 session_parent）：返回父会话

这套导航键让你可以在主对话和各类子 Agent 工作成果之间自由切换，非常直观。

总结

OpenCode 的 Agent 系统本质上是一个 AI 编程团队的管理框架。通过配置不同的 Agent，你可以：

专业化分工：让每个 Agent 专注一个领域，输出质量更高

安全隔离：通过权限系统精确控制每个 Agent 能做什么、不能做什么

成本优化：为不同任务选择不同级别的模型，在效果和成本之间取得平衡

团队协作：项目级配置可以随 Git 同步，整个团队共享同一套 Agent 定义

从简单的代码审查到复杂的安全审计流水线，Agent 系统提供了足够的灵活性和安全性来满足各种场景。配合 OpenCode 的其他系统（Skills、Commands、Hooks），你可以搭建出一个高度自动化的 AI 编程工作流。

OpenCode Agent 配置完全指南：打造专属的 AI 编程助手团队

OpenCode Agent 配置完全指南：打造专属的 AI 编程助手团队

Agent 是什么

主 Agent

子 Agent

创建你的第一个自定义 Agent

配置选项详解

description（必填）

mode

model

temperature

steps

hidden

color

prompt

disable

top_p 与额外参数

权限管理：精确控制 Agent 的能力边界

Task 权限：控制 Agent 可以调用哪些子 Agent

使用 opencode agent create 快速创建

实战案例

案例一：安全审计 Agent

案例二：文档生成 Agent

案例三：主 Agent 层级定制

子 Agent 会话导航

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客

使用 `opencode agent create` 快速创建