进阶 opencode.ai 2026-11-11 16:13:22 · 16 阅读

第7章 OpenCode Agents 配置指南

创建 Markdown 文件来添加可复用的 Agent。下面的示例添加了一个只读的 reviewer(审查者),主 Agent 可以启动它进行代码审查: .opencode/agents/reviewer.md --- description: 审查变更的正确性和回归问题 mode: subagent model: anthropic/claude-sonnet-5-5#high permissions: - action: edit resource: "*" effect: deny - action: shell resource: "*" effect: deny ---

审查当前变更。按严重程度列出发现,并附上文件和行号引用。 让主 Agent 使用它: Use the reviewer subagent to review my current changes.

一个 Agent 将系统提示词、模型偏好、权限和显示细节整合为一个命名的助手配置。

在全局或项目范围内保存 Markdown Agent: ~/.config/opencode/agents/.md .opencode/agents/.md OpenCode 从当前目录向上遍历直到项目根目录来发现 .opencode 目录。嵌套路径会成为 Agent ID 的一部分: .opencode/agents/team/reviewer.md → team/reviewer

Frontmatter 接受与 Agent 配置条目相同的字段。Markdown 正文作为 Agent 的系统提示词: .opencode/agents/explainer.md --- description: 解释代码但不修改它 mode: subagent ---

用简短的例子解释相关代码。不要编辑文件。 V1 frontmatter 字段已弃用。参考 Agent 文件了解仍使用这些字段的文件是如何被读取的。

在任何 OpenCode 配置文件的 agents 部分下定义 Agent: opencode.jsonc { "$schema": "https://opencode.ai/config.json", "agents": { "reviewer": { "description": "审查当前变更", "mode": "subagent", "system": "按严重程度报告发现。", "permissions": [ { "action": "edit", "resource": "*", "effect": "deny" }, ], }, }, }

设置会话未选择 Agent 时使用的默认主 Agent: opencode.jsonc { "$schema": "https://opencode.ai/config.json", "default_agent": "writer", "agents": { "writer": { "mode": "primary" }, }, } 所选的默认值必须存在、可见且支持 primary 用途。否则,OpenCode 会使用 build,然后是第一个可见且支持 primary 的 Agent。更改此设置不会替换现有会话中存储的 Agent。

根据 Agent 应运行在哪里设置 mode: JSONC { "agents": { "reviewer": { "mode": "subagent" }, }, } Mode | 行为 primary | 作为会话的主 Agent 运行。这是新自定义 Agent 的默认值。 subagent | 仅通过 subagent 工具在子会话中运行。 all | 既可以作为主 Agent 运行,也可以作为子 Agent 运行。

子 Agent 在前景或背景的子会话中以全新上下文运行。父 Agent 的 subagent 权限控制它可以启动哪些 Agent;子 Agent 使用其自身配置的权限。 JSONC { "agents": { "orchestrator": { "permissions": [ { "action": "subagent", "resource": "*", "effect": "deny" }, { "action": "subagent", "resource": "reviewer", "effect": "allow" }, ], }, }, }

OpenCode 包含以下可见的 Agent: Agent | Mode | 用途 Build (build) | primary | 默认的编码 Agent。默认允许工作区外的工具和访问权限;敏感的环境文件读取需要批准。 Plan (plan) | primary | 探索和规划而不编辑常规项目文件。在被要求时可以写入 OpenCode 计划文件,shell 命令仍受权限控制。 General (general) | subagent | 处理具有广泛工具访问权限的研究和多步骤工作,但不能启动更多的子 Agent。 Explore (explore) | subagent | 搜索和读取代码或网络来源而不编辑文件。

使用相同的 ID 来覆盖内置 Agent: JSONC { "agents": { "build": { "permissions": [ { "action": "shell", "resource": "git push *", "effect": "ask" }, ], }, }, } 隐藏的 compaction、title 和 summary Agent 执行维护任务,无法直接选择。V2 没有内置的 scout Agent。

Agent 定义按配置顺序合并。后来的标量值替换早前的值,请求映射按键合并,权限规则追加: JSONC { "permissions": [ { "action": "shell", "resource": "*", "effect": "ask" }, ], "agents": { "build": { "permissions": [ { "action": "shell", "resource": "git status", "effect": "allow" }, ], }, }, } 全局权限在 Agent 特定规则之前应用,因此后续的 Agent 规则可以对其进行细化。

description 解释 Agent 的用途。将其添加到子 Agent,因为 OpenCode 会将其展示给选择要启动哪个 Agent 的模型: YAML description: 审查数据库迁移的安全性

mode 接受 primary、subagent 或 all。对于新的自定义 Agent,如果省略则默认为 primary: YAML mode: all

model 使用 provider/model,可选地带有 #variant: YAML model: anthropic/claude-sonnet-5-5#high JSON 配置也接受扩展形式: JSONC { "agents": { "reviewer": { "model": { "providerID": "anthropic", "model": "claude-sonnet-5-5", "variant": "high", }, }, }, }

子 Agent 使用其配置的模型,或者在未配置时继承父会话的模型。 会话单独存储其选定的模型。按 ID 选择主 Agent 不会更改该模型。

system 设置 Agent 的系统提示词。非空值将替换该 Agent 提供者的基础提示词: JSONC { "agents": { "reviewer": { "system": "仅审查。不要修改文件。" }, }, } 项目说明、技能、引用和其他说明源仍会被添加。在 Markdown Agent 中,将此文本放在文档正文中,而不是 system frontmatter 字段中。

permissions 是匹配规则有序列表: JSONC { "agents": { "reviewer": { "permissions": [ { "action": "*", "resource": "*", "effect": "deny" }, { "action": "read", "resource": "src/", "effect": "allow" }, ], }, }, } 字段 | 含义 action | 工具或权限操作。支持通配符。 resource | 路径、命令、Agent ID 或由 action 匹配的其他值。支持通配符。 effect | allow、ask 或 deny。 最后一个匹配的规则获胜,因此将广泛规则放在例外之前。常见的操作包括: Action | 涵盖范围 shell | Shell 命令 edit | Edit、write 和 patch 工具 subagent | 子 Agent read, glob, grep | 本地发现工具 webfetch, websearch | 网络工具 skill | 技能加载 对于 read、edit 和 external_directory 资源,OpenCode 会展开 ~ 和 $HOME: JSONC { "action": "read", "resource": "~/notes/", "effect": "allow" } Shell 资源保持为原始命令文本,不会展开这些值。

steps 设置模型步骤的正数最大值: YAML steps: 8 在最后一步时,OpenCode 移除工具并要求模型以文本形式总结。新的用户输入会重置配额。

hidden 将 Agent 从正常列表、交互式发现和子 Agent 目录中移除: YAML hidden: true 这控制可见性,而不是安全性。使用 permissions 来限制行为。

color 使用六位十六进制值设置 Agent 的 UI 颜色: YAML color: "#ff6b6b"

disabled 在配置加载的该点移除内置或自定义 Agent: JSONC { "agents": { "plan": { "disabled": true }, }, }

request 接受每个 Agent 的 header 和 JSON body 覆盖: JSONC { "agents": { "reviewer": { "request": { "headers": { "x-agent": "reviewer" }, "body": { "temperature": 0.1 }, }, }, }, }

不要在新的 V2 Agent 配置中使用诸如 temperature、top_p、prompt、permission、tools、disable 或 maxSteps 这样的旧顶层字段。

评论 (0)