OpenCode permissions 决定一个匹配的工具动作是直接执行、等待批准，还是被阻止。在 OpenCode V2 中，stable 配置使用有顺序的 permissions 数组。每条规则都包含 action、resource 和 effect：
allow：执行匹配动作；ask：暂停并等待真人决定；deny：阻止匹配动作。
如果复制的是使用 permission、bash 或 task 的旧示例，不要把它混进 V2 配置。当前 V2 对应使用 permissions、shell 和 subagent。
最后核验：2026 年 9 月 16 日。 OpenCode 配置会随版本变化。本文示例依据当前 OpenCode V2 permissions 官方说明。实际使用时仍需核对安装版本的 Schema 与文档。
安全边界： Permission 规则只决定 OpenCode 能否尝试一个动作。它不能证明已放行的命令一定正确，不能自动隔离操作系统或权限过大的云账号，也不能代替 Review 和备份。
从一套精简的 V2 基线开始
下面的示例会在执行任意 Shell 命令前询问，放行两种常见的只读 Git 检查，并拒绝 Push：
这是一套教学起点，不是所有项目都应该照抄的标准策略。命令格式、仓库流程、操作系统和组织控制不同，适合的 Resource 也会不同。
关键是策略必须能被解释。Review 的人应该能说清楚每条规则允许什么，以及这项工作为什么需要它。
规则顺序很重要：最后一个匹配项生效
OpenCode V2 会按照顺序评估规则，并使用最后一个匹配项。先放宽泛基线，再放更窄的例外：
git commit ... 和 git push ... 也会匹配 git *，但后面的规则更具体。顺序写反后，宽泛规则可能覆盖原本想保留的限制。
Pattern 匹配不会理解命令意图。Wrapper Script、Alias、错误工作目录或意料之外的参数，都可能改变真实效果。应该测试工作流真正会执行的输入。
分开决定文件、Shell 与外部目录权限
“访问仓库”不是一种权限，应该分别检查不同能力。
文件读取
读取可能暴露源码、日志、配置、个人数据和 Secret。只允许任务需要的 Resource。类似 .env 的敏感文件继续 deny；只有工作流确实需要时，才允许 .env.example 这类无密钥模板。
不要为了读取一个文件，就从包含许多无关项目的上层目录启动 OpenCode。边界越窄，越容易判断实际可达范围。
文件编辑
只负责 Review 的 Agent 应拒绝编辑。负责构建的 Agent 可以用 ask 在修改前保留检查点。即使真人批准，Patch 仍然可能写错，所以必须检查 Diff 并运行仓库真实检查。
Shell 命令
Shell 可以检查状态和运行测试，也可以删除数据、安装依赖、发布代码或修改基础设施。先使用 ask，只放行已经理解的精确低风险 Pattern，并明确 deny 这项工作不应该执行的破坏性或外部变更动作。
外部目录
外部目录权限会扩大文件系统边界。只开放完成任务需要的最小路径，并继续收紧其中的读取、编辑和 Shell 规则。能到达一个目录，不等于可以在里面做所有操作。
只有工作职责不同，才添加 Agent 专属规则
V2 支持在某个 Agent 下增加规则。OpenCode 会把 Agent 规则追加到全局列表后面，因此匹配的 Agent 规则可以覆盖全局基线。
只有角色真的承担不同职责时才这样做，例如 Reviewer 拒绝编辑，Builder 在编辑前询问。不要建立大量几乎相同的 Agent 和例外列表；一套简短的全局基线，加少量清楚 Override，更容易审计。
自定义 Subagent 使用它自己的 Permissions，不能假设它一定继承 Parent Agent 更窄的有效权限。
安全测试最终生效的策略
使用不包含真实 Secret、可以丢弃或已经进入版本控制的小项目：
- 加载配置，确认 OpenCode 没有报告 Schema Error。
- 读取普通源码，确认结果符合预期。
- 使用虚构
.env文件确认目标 deny 行为。 - 提出一次无害编辑，确认它会 ask 还是 deny。
- 执行已经放行的精确只读 Shell Pattern。
- 在非生产测试仓库中尝试虚构的 Push，确认被拒绝。
- 引用项目外的无害文件，确认外部目录行为。
- 对每个 Agent 专属 Override 重复检查。
记录 OpenCode 版本和测试日期。重大升级或配置发生实质变化后，再完整跑一遍。
Permissions 只是其中一层，不是完整 Sandbox
还应同时具备：
- 版本控制和明确的回退路径；
- 独立开发凭证和最小权限 Cloud Role；
- 不把 Key 暴露在 Prompt 或日志中的 Secret 管理；
- 仓库检查与真人 Review；
- 处理不可信代码或数据时的隔离运行环境。
如果正在选择本地执行还是托管环境，可以比较 OpenCode 本地与云端工作流。Cloud Workspace 会改变 Runtime 边界，但不会消除显式工具权限。
安装和模型选择可以参考 OpenCode 安装指南与 Provider / 模型指南。如果持久托管 Workspace 更适合项目，可以查看 OpenCode Agent 页面和 Agent.Space 当前套餐。Agent.Space 与 OpenCode 相互独立，不会替代 OpenCode 权限配置。
FAQ
OpenCode V2 Permissions 改了什么？
V2 官方说明使用包含 action、resource、effect 的有序 permissions 数组，并使用 shell、subagent 等 Action 名称，而不是旧示例中的 bash、task。不要在同一份文件中混合 V1 和 V2 Schema。
为什么具体规则没有覆盖 *？
同时检查实际匹配输入和规则顺序。V2 由最后一个匹配规则生效，因此宽泛规则通常应该放在前面，具体例外放在后面。
ask 是最安全又实用的默认值吗？
它是一种保守检查点，不是安全保证。工作流永远不应执行的动作使用 deny，需要结合上下文判断的动作使用 ask，只有经过 Review 和测试的窄 Pattern 才使用 allow。
Reviewer 和 Builder 可以使用不同权限吗？
可以。把共享规则放在顶层，把更窄的 Override 放在 agents.<id>.permissions 下。应该验证最终行为，而不是只依赖 Agent 名称。