OpenCode 2 的权限规则为什么没生效?
按配置来源、规则顺序、子代理和 policies 四步排查。给出可校验的 V2 示例,也讲清外部目录默认行为和插件不受进程沙箱保护的边界。
核查日:2026-11-18(北京时间)。依据当天 V2 官方文档和公开 JSON Schema;做了离线结构检查,没有启动 OpenCode、调用模型或实测拦截效果。
你在项目里写了「推送前询问」,它却没问;主代理不许改文件,子代理却仍能改。先别加十条重复规则。先确定读了哪些配置、最后匹配的是哪条、实际动作由哪个代理执行。
这篇是权限排查指南,不是系统沙箱教程。工具本身的模型和订阅信息见 OpenCode 工具页。
先分清三套规则
Config、Permissions 和 Policies 不能合并成一句「项目配置优先」。
| 要查什么 | 官方规则 | 常见误判 |
|---|---|---|
| 普通配置值 | 用户全局与项目文件合并,系统配置更高,macOS 受管配置最高 | 以为改最近的项目文件一定能覆盖系统值 |
permissions | 有序匹配,最后匹配生效;共享规则后再追加代理自己的规则 | 以为更具体的模式自动赢,或子代理继承主代理的禁令 |
policies | 同文件最后匹配;跨来源按管理权限排序,较广的来源反而更强 | 以为仓库里的 allow 能解开全局或组织的限制 |
1. 找齐来源,不只看当前目录
对普通配置,OpenCode 从当前目录往文件系统根目录找:先把直接的 opencode.json(c) 按由远到近合并,再把 .opencode/opencode.json(c) 按由远到近合并。因此,找到的 .opencode 文件会覆盖直接文件里的普通同名设置,不只是「离我最近的那个文件赢」。用户全局文件是 ~/.config/opencode/opencode.json(c);Linux 系统目录是 /etc/opencode。
这不等于项目能覆盖系统或受管设置,也不要把这张普通配置加载图直接套到策略上。
policies 的来源优先级从高到低是:macOS MDM → 系统 → 已连接的 Console 工作区 → 用户全局 → 直接项目配置 → .opencode 配置。后两类各自又是外层目录高于内层。Console 策略变更约在下一次抓取时生效,通常约一分钟;断开连接会清掉该连接的策略,暂时不可达则保留上次策略。
排查时列出实际启动目录、系统 / 全局 / 祖先目录配置、当前 Console 工作区。不要公开带有密钥的整份配置。
2. 看最后匹配,不看「谁更具体」
原生 V2 的字段是 permissions,动作名是 shell、subagent。V1 的 permission、bash、task 不要和 V2 示例随意混拼。迁移指南说支持的 V1 配置仍会规范化加载,不是所有旧字段都要立刻删除;原生 V2 值和旧形式设同一值时,有效的原生值优先。
一条权限规则需要三个字符串:action、resource、effect。effect 可取 allow、deny、ask。
- 同时匹配两条,最后一条赢。把宽泛规则放前面,例外放后面;没有「具体程度」加权。
- 通配符
*可以匹配斜杠,?匹配一个字符,不要当成 Git 的路径通配语义。 - shell 模式末尾的
*也匹配不带参数的命令。例如git push *也匹配git push。 - 一次操作检查多个资源时:有一个
deny就拒绝;否则有一个ask就询问;全部允许才放行。 - 「没有规则匹配时询问」不等于「默认全部询问」。每个代理的基础规则先允许
*;.env、.env.*读取再设为询问,.env.example允许。
一份可逐条解释的起点,不是完整安全策略
放进项目的 opencode.json,或合并到已有 opencode.jsonc;先备份,不要直接覆盖其他配置:
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status --short", "effect": "allow" },
{ "action": "shell", "resource": "git --no-pager diff --no-ext-diff --no-textconv", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" },
{ "action": "external_directory", "resource": "*", "effect": "ask" }
],
"agents": {
"reviewer": {
"description": "Review without edit or shell tools",
"mode": "subagent",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "deny" },
{ "action": "shell", "resource": "*", "effect": "deny" }
]
}
}
}
这份配置想表达的是:shell 通常先问;两个固定的 Git 检查命令不问;匹配到的 git push 拒绝;项目外路径先问;reviewer 子代理追加拒绝 edit 和 shell。
这里刻意没有用 git diff * 自动放行任意参数。Git 的 --output 能写文件,外部 diff / textconv 也可能运行程序;固定命令使用 --no-ext-diff --no-textconv,缩小放行范围,仍不保证宿主 Git 配置或整个进程只读。在没有其他覆盖规则或匹配的既有保存批准时,其他参数版本会落回询问;不要为了省事全部点「总是允许」。Git 参数的依据见 git diff 文档。
这也不是「从此无法推送」:绝对路径调用 Git、包装脚本、其他工具或网络通路不一定匹配 git push *。它们可能落回询问;不要批准不理解的命令。需要强制断网或文件隔离时,要另做操作系统 / 容器层面的限制。
3. 外部目录和子代理,单独查
官方把 active Location 与其非根项目 worktree 之外的路径先交给 external_directory,再查 read / edit。外部目录默认允许,不是默认弹窗;上面的 ask 是显式补上的。
read、edit、external_directory 的 ~ 和 $HOME 前缀会展开;shell 的资源是原始命令文本,不会这样展开。shell 只会尽力推断命令涉及的目录,不是文件系统边界。
代理自己的规则追加在共享规则后。自定义子代理使用它自己的权限,不是主代理权限的子集。因此:
- 主代理拒绝编辑,不代表
reviewer自动继承这一条。 - 例子给
reviewer单独加了edit与shell拒绝,避免只改了主代理。 - 这仍不是「所有方式都不能写文件」的证明。MCP 工具、插件及其他动作也要单独审查,不能靠一条
edit规则代表全部副作用。
真要强制限制,用 policies;但不要写 ask
下面是另一份配置片段。需要组织约束时,把相应策略部署在合适的高权限来源,而不是指望仓库文件能约束所有人:
{
"$schema": "https://opencode.ai/config.json",
"policies": [
{ "action": "tool.use", "resource": "shell:git push *", "effect": "deny" }
]
}
它匹配的是 tool.use 的 动作:资源,在普通权限与已保存批准之后再检查。匹配到拒绝时,不弹询问,而是类似 Blocked by configuration policy 的错误;Console 策略会标出工作区名称。
policies 的 effect 只有 allow / deny,没有 ask。只有当 allow 是按来源优先级与语句顺序评估后的最后匹配语句时,它才覆盖此前匹配的策略 deny;不按模式的具体程度排名。之后仍要回到代理权限判断,不会直接授权。没有匹配的策略默认允许继续走原有检查。
已保存的「Allow always」是项目级持久允许规则,不会覆盖已配置的 deny。如果似乎绕过禁令,先查是否根本没匹配到、禁令被后续规则覆盖,或当前执行的是另一个代理 / 动作。
4. JSON 能解析,不代表策略真的加载了
Policies 文档明确写:校验失败的语句会被丢弃,服务端日志会警告,其余列表继续生效。 所以改完拒绝规则要看日志,不能只检查括号配平。
核查当天,Permissions 页 Scanner 小节还出现了 policies 内嵌 permissions 的示例;它与公开 schema 及 Policies 页的三字段语句结构不一致。本文不采用那个嵌套形状,也没有验证运行时是否有兼容处理。遇到类似冲突,先对照所用版本、公开 schema和日志,别把网页示例当成执行结果。
升级前还要查版本:
- 早于 2.2.3 的客户端会忽略
integration.connect、新语义的integration.use、mcp.use、skill.use、plugin.use。 - 早于 2.2.6 的客户端会忽略
websearch.use。 - 旧的
integration.use加mcp:/skill:/plugin:前缀会转换到对应新动作;现在裸integration.use: *限制的是集成来源,不能当成「禁用全部 MCP、技能、插件」。
如果目的是禁用这三类,当前文档的原生形状是:
{
"policies": [
{ "action": "mcp.use", "resource": "*", "effect": "deny" },
{ "action": "skill.use", "resource": "*", "effect": "deny" },
{ "action": "plugin.use", "resource": "*", "effect": "deny" }
]
}
这是独立的严格示例,会禁用所有对应能力,不建议无差别加进每个项目。先确认自己确实不需要它们。
最后一道边界:这些配置不隔离插件进程
官方明确说,policies 不对插件代码做沙箱隔离。例如禁用某 provider,是在正常 provider / model 路径上阻止使用,不是让插件从此没有联网能力。shell 也仍以宿主用户的文件、进程、网络权限运行。
只加载信任的插件与 MCP 服务;陌生仓库先看配置和启动命令,不要靠一段 JSON 接受运行不信任代码。本文没有验证某个插件或 MCP 服务的行为。
无需真实推送的验收清单
先在隔离目录里准备假仓库和假文件;不要拿真实 .env、SSH 文件或生产目录试拦截。
| 检查项 | 按文档应检查的结果,不是本文实测 |
|---|---|
| 主代理两个固定 Git 命令 | 应匹配精确允许;加新参数不一定匹配 |
规范形式 git push、git push origin main | 应匹配示例拒绝;不要为验收实际发起推送 |
| 外部假目录 | 应先走 external_directory;还要看后续规则是否覆盖 |
reviewer 的 edit / shell 动作 | 应匹配它自己的拒绝,不只看主代理 |
| 保存过批准后再加 deny | 配置拒绝不应被旧批准解开 |
非法策略字段或 ask | 检查 schema 报错和服务端警告,别以为已执行 |
本文只做了公开 schema 校验、JSON 示例一致性检查,以及隔离假仓库中的 Git 参数检查。没有启动 OpenCode,也没有测试真实权限执行、扫描器解析、Console 同步或插件隔离。运行时验收若需要模型、付费请求或真实账号,先取得相应授权,不能把离线检查写成「实测安全」。
官方依据(均于 2026-11-18,北京时间核对)
- Config:配置位置、普通值的合并顺序、系统与受管配置。
- Permissions:匹配、默认值、目录、子代理、保存批准与宿主权限。
- Policies:管理来源顺序、非法语句警告、版本门槛与插件边界。
- 公开 JSON Schema:本文示例字段和结构的离线校验依据,不证明运行时效果。
- Migrate from V1:旧配置兼容和原生 V2 值优先。
- git diff:
--output、--no-ext-diff、--no-textconv的含义。
📚 继续阅读
📚 相关指南
AI 编程 Agent 安全指南 2026:仓库权限、Shell 执行与提示注入怎么防
AI 编程 Agent 越来越能干,但权限越大风险越大。本文从仓库权限、Shell 执行、提示注入、凭证泄露四个维度,结合 Claude Code、Codex、Copilot、Gemini CLI、Cursor 的安全机制,给开发者和团队一份可落地的安全实践清单。
AI 编程 Agent 2026 趋势路线图:从补全、IDE 到云端同事
截至 2026 年 6 月,AI 编程工具正在从代码补全进入 Agent 工程化阶段。本文结合 Codex、Claude Code、GitHub Copilot、Gemini CLI、MCP 与安全实践,给开发者和团队一份选型路线图。
火山方舟 Agent Plan 全解读:业界首个 Agent 套餐包
2026-05-11 火山方舟发布 Agent Plan,被官方定义为业界首个 Agent 套餐包。本文详解四档订阅价格、AFP 积分制、多模态模型与 Harness 工具、与 Coding Plan 的差异,以及如何选择。
📖 相关对比文章
2026 最佳 AI 编程工具推荐:主流工具横评与选型指南
2026 年 AI 编程工具横评,覆盖 Cursor、Claude Code、Copilot、Windsurf 等主流工具,从编码能力、价格、国内可用性多维度评分,帮你找到最适合的方案。
OpenCode vs Cursor 2026:免费开源 TUI 对决付费 AI IDE
OpenCode vs Cursor 深度对比:免费终端 TUI Agent 与顶级 AI IDE,从价格、编程能力、国内可用性到工作流全面对比,帮你做出最适合的选择。
终端 AI 编程三杰:Claude Code vs OpenCode vs Aider
三款主流终端 CLI AI 编程工具全面对比:Claude Code、OpenCode、Aider 的功能、定价、模型支持和使用场景详解。
🔧 文中提到的工具
💰 相关省钱方案
基于本文涉及的工具与 API,这些组合能帮你以更低成本上手。
OpenCode + 方舟 Agent Plan
开源 Agent 终端套件开源 CLI 客户端 OpenCode 接入方舟 Agent Plan:在终端里同时拿到 Doubao 编程主力、Seedance 视频、Seedream 图像、Embedding 向量与 Harness 工具链。AFP 积分制按 5h 与日额度滚动消耗,Medium 及以上送 7×24 智能伙伴;适合想要 Claude Code 体验但要国产模型 + Agent 工具的终端党。
适合:想在终端里玩 Agent + 多模态的国内开发者 · OpenCode / 开源客户端粉丝
OpenCode + 方舟 Coding Plan
终端党之选终端党的国产平替方案。开源 CLI 客户端,支持 75+ 模型提供商、多会话管理,接方舟 API 国内直连。方舟提供 Lite / Pro 双层级套餐;新用户订阅入口自 2026-03-13 起改为每日 10:30 限量开放。
适合:终端重度用户 · 预算有限的国内开发者
🎁 领取优惠 & 免费试用
汇总各工具与 Coding Plan 的免费额度、首月折扣与注册入口,随时更新。
查看优惠福利 →