第23章 OpenCode 权限控制指南:配置资源访问规则
PermissionsPermissions 权限控制智能体(agent)是否可以对资源执行操作。
一种常见的配置方式是:在执行 shell 命令前询问,允许常规的 Git 检查,并始终阻止推送。将这些有序规则添加到 opencode.jsonc 中: JSONC{ "$schema": "https://opencode.ai/config.json", "permissions": [ { "action": "shell", "resource": "*", "effect": "ask" }, { "action": "shell", "resource": "git status *", "effect": "allow" }, { "action": "shell", "resource": "git diff *", "effect": "allow" }, { "action": "shell", "resource": "git push *", "effect": "deny" }, ], } 最后匹配的规则优先,因此特定例外会跟随广义规则之后生效。
每条规则需要三个字符串字段: FieldMeaningaction工具权限动作resource被使用的值,如路径、命令、URL、查询、技能 ID 或 agent IDeffectallow、deny 或 ask JSONC{ "permissions": [ { "action": "read", "resource": "*", "effect": "allow" }, { "action": "read", "resource": "*.env", "effect": "deny" }, ], } EffectResultallow继续执行,无需提示deny阻止操作ask等待客户端做出决定 如果没有规则匹配,OpenCode 会使用 ask。
Action 和 resource 使用简单的整值通配符: PatternMatch*零个或多个字符,包括 /?恰好一个字符Other字面字符 JSONC{ "permissions": [ { "action": "edit", "resource": "packages/docs/*.mdx", "effect": "allow" }, ], } 此模式匹配整个规范化路径。反斜杠会被规范化为正斜杠,且在 Windows 上匹配是大小写不敏感的。 以 * 结尾的 shell 模式也会匹配不带参数的命令: JSONC{ "action": "shell", "resource": "git status *", "effect": "allow" } 这同时匹配 git status 和 git status --short。 OpenCode 按顺序组合规则并使用最后一个匹配项。低优先级的配置先加载,全局规则随后追加,agent 规则最后追加。 JSONC{ "permissions": [ { "action": "read", "resource": "*", "effect": "allow" }, { "action": "read", "resource": "secrets/*", "effect": "deny" }, ], } 操作可能检查多个资源,例如触及多个文件的补丁。任何 deny 都会拒绝该操作;否则,任何 ask 都会询问;否则,该操作被允许。
V2 的 action 名称是字符串,因此插件可以定义更多 action。内置工具目前使用以下 action 和 resource:
ActionResourceread相对于 Location 的内部路径或规范化的绝对外部路径editedit、write 和 patch 的目标路径glob请求的 glob 模式grep请求的正则表达式,而非搜索路径shell由扫描器生成的命令字符串;复合命令可能生成多个subagent目标 agent IDskill技能 IDquestion*webfetch请求的 URLwebsearch搜索查询experimental_image_generate选定的图像模型,格式为 providerID/modelID,若设置了变体则加上 #variantexternal_directory规范的外部目录边界,通常以 / 结尾;MCP 工具格式为
位于活动 Location 及其非根项目工作树之外的路径,会在检查其 read 或 edit 规则之前先对照 external_directory 进行检查。默认策略允许 external_directory,因此除非你添加规则,否则外部路径不会触发提示。若要在访问项目外部之前被询问: JSONC{ "$schema": "https://opencode.ai/config.json", "permissions": [ { "action": "external_directory", "resource": "*", "effect": "ask" }, ], } 其后更窄的规则可以允许或拒绝特定目录: JSONC{ "$schema": "https://opencode.ai/config.json", "permissions": [ { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" }, { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" }, { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }, ], } 这适用于 read、edit、write 和 patch 使用的外部路径。 Shell 在检查 shell 资源之前,会检查其外部工作目录以及其扫描器推断的目录。 对于 external_directory、read 和 edit,前导的 ~、~/、$HOME 或 $HOME/ 会在配置加载时展开: JSONC{ "action": "read", "resource": "$HOME/reference/*", "effect": "allow" } Shell 资源保留原始命令文本,不会进行主目录展开。
相对变异路径可能离开活动 Location,但仍留在其项目工作树内部。显式的外部路径在匹配前会进行规范化,因此仅授权受信任的目录边界。
Shell 权限检查使用 OpenCode 的内置 shell 扫描器,涵盖 Bash、Zsh、POSIX sh 和 PowerShell。包含语法错误或有扫描器无法安全分析的动态评估的命令会返回扫描器错误,而不是执行未经验证的子命令。 JSONC{ "$schema": "https://opencode.ai/config.json", "policies": [ { "permissions": [ { "action": "shell", "resource": "git status *", "effect": "allow" }, { "action": "shell", "resource": "rm *", "effect": "deny" }, ], }, ], } 权限规则、保存的批准模式和最佳努力的目录推断应用于每个提取的子命令和 cd 目标。没有针对未知目录的额外批准模式或全面限制。
每个 agent,包括自定义 agent,都从以下有序基础策略开始: JSONC[ { "action": "*", "resource": "*", "effect": "allow" }, { "action": "read", "resource": "*.env", "effect": "ask" }, { "action": "read", "resource": "*.env.*", "effect": "ask" }, { "action": "read", "resource": "*.env.example", "effect": "allow" }, ] 随附的 agent 追加以下策略: AgentAdditional policybuild允许问题plan允许问题;除了 ~/.opencode/plans 下的文件外,拒绝编辑general拒绝问题和启动 subagentsexplore除了 shell、read、glob、grep、web 抓取、web 搜索和外部目录外,拒绝所有操作;询问 .env 读取title拒绝所有 actionssummary拒绝所有 actionscompaction保持基础策略 由于没有默认规则询问 external_directory,位于 Location 和工作树之外的读取和编辑会在无提示的情况下进行。添加 external_directory 的 ask 或 deny 规则,如目录部分所示,可恢复提示或阻止外部访问。 后续的全局和 agent 规则会覆盖这些默认值。
将共享规则放在顶级,更窄的规则放在 agents.
当规则解析为 ask 时,客户端可以回复: ChoiceReplyResultAllow onceonce仅批准当前待处理请求Allow alwaysalways批准并保存工具建议的模式供项目使用Rejectreject拒绝并拒绝该会话中其他所有待处理的权限请求 例如,选择允许始终允许 git status --short 可能会保存一个 shell 前缀,覆盖后续的 git status 命令: shell: git status * → allow 保存的批准是持久的、项目范围的 allow 规则。它们永远不会覆盖配置的 deny。工具选择建议的保存模式:有些建议 *,shell 建议命令前缀,技能和 subagents 建议它们的 ID。 审查广泛的批准并移除不再需要的。 客户端在拒绝时可能附带反馈。非交互式客户端必须决定如何处理批准请求;配置的 deny 规则始终强制执行。
策略可以在这些规则和保存的批准运行后硬拒绝权限检查。它将 allow 或 ask 变为 deny,从不授予访问。 JSONC{ "policies": [{ "action": "tool.use", "resource": "shell:sudo *", "effect": "deny" }], } 全局和 Console 管理策略覆盖项目配置,这就是组织如何阻止仓库允许的某条命令。