OpenCode 权限设置指南：如何安全使用 allow、ask 和 deny

OpenCode 权限会决定一个匹配的动作是直接运行、等待你批准，还是被阻止。在当前 stable 配置中，三种结果分别是：

• allow：不再询问，直接运行匹配动作；
• ask：暂停并请求人类决定；
• deny：阻止匹配动作。

一套保守的起点，是在写文件和运行 Shell 命令前询问，只精确放行你理解的只读操作，并拒绝工作流中明确不该发生的删除或发布动作。随后在一次性项目或已经进入版本控制的项目中测试，再决定是否减少提示。

这种方法能降低误操作风险，却不能创造绝对 Sandbox。权限规则不会证明一条已允许命令是正确的，不理解业务意图，也不能替代 Code Review 或恢复丢失的数据。它只是整个执行环境中的一层控制。

如果还没有连接目标运行路径，可以先在受控项目中安装 stable OpenCode，并确认 OpenCode 使用的 Provider 与模型。

allow、ask 和 deny 到底做什么？

官方权限文档会把动作应用到文件读取、编辑、Shell 命令、Subagent Task、Web 访问，以及项目之外的路径等工具。

这里的关键词是“匹配”。一条规则可以覆盖整个工具，也可以只覆盖更具体的路径、命令模式、URL 或 Subagent。最终权限取决于规则结构和顺序。

批准也不等于质量保证。允许 git status，不会让所有 Git 命令都变得无害；允许某个目录下的编辑，也不能证明 Patch 符合需求。授权与验证应分开处理。

不要在没读过的情况下依赖默认权限

本文在 2026 年 8 月 27 日核验时，stable OpenCode 的默认权限相对宽松：

• 大多数权限默认是 allow；
• external_directory 和防止重复 Tool Call 的 doom_loop 默认是 ask；
• 文件读取默认 allow，但常见 .env 文件默认拒绝读取。

这些默认值优先保证工具能够工作，不代表符合每个团队的风险要求，而且未来可能变化。显式写出的项目策略，比对安装版本默认行为的猜测更容易 Review。

不要因为某个任务说自己需要凭证，就直接削弱 .env 保护。更安全的问题是：Provider 或命令能否通过获批的凭证存储或环境获取 secret，而不把它暴露给模型或写入输出。

一套保守的 stable OpenCode 权限起点

下面的示例使用 2026 年 8 月 27 日 stable 文档记录的 permission Schema：

{  "$schema": "https://opencode.ai/config.json",  "permission": {    "*": "ask",    "read": {      "*": "allow",      "*.env": "deny",      "*.env.*": "deny",      "*.env.example": "allow"    },    "edit": "ask",    "bash": {      "*": "ask",      "git status *": "allow",      "git diff *": "allow",      "git push *": "deny",      "rm *": "deny"    },    "external_directory": "ask"  }}

这是一套教学起点，不是适用于所有项目的标准答案。它明确表达了这些意图：

• 未知动作先询问；
• 普通读取可执行，但类似 secret 的环境文件被拒绝；
• 编辑需要批准；
• 两类只读 Git 检查模式可执行；
• Push 和 rm 模式被拒绝；
• 项目之外的路径需要批准。

你的项目可能需要更严格的读取规则、不同命令名，或者受组织管理且优先级更高的策略。复制任何示例前，都要确认安装版本的 Schema。

规则顺序很重要：最后匹配的规则生效

Stable OpenCode 会按顺序评估细粒度权限模式，最后一个匹配规则生效。宽泛的 Catch-all 应放在前面，再在后面写更具体的例外。

例如：

{  "permission": {    "bash": {      "*": "ask",      "git *": "allow",      "git commit *": "ask",      "git push *": "deny"    }  }}

匹配 git push * 的命令也会匹配 git *，但更靠后的具体 deny 会成为最终结果。如果顺序反过来，宽泛规则可能意外覆盖原本的限制。

这种模式很有用，但仍然需要谨慎：

• Pattern 只匹配文字，不理解命令意图；
• Shell Alias、Wrapper、Script 和复合命令可能改变真正执行的内容；
• 一个看起来很窄的命令，在错误目录或账号中仍可能产生很大影响；
• 复制的示例可能不符合当前 Parser 或 Tool 名称。

应该测试工作流真正会用的准确命令，不要为了减少提示就批准一个很宽的前缀。

分开管理读取、编辑、Shell 与外部目录

“访问代码库”不是单一权限。OpenCode 拆分了多种能力，让任务可以检查项目，而不自动获得所有执行权限。

Read 权限

读取可能暴露源码、配置、日志、凭证或个人数据。只放行任务需要的目录，保留 secret 文件的 deny，并避免从包含无关项目的上级目录启动 OpenCode。

Edit 权限

编辑覆盖文件修改，包括 Write 和 Patch。要求编辑前 ask 可以形成有效检查点，但最终仍要检查 Diff。对于只负责 Review 的 Agent，应直接把编辑设为 deny，而不是只靠 Prompt 写“不要改文件”。

Shell 权限

Shell 可以运行测试和检查状态，也可以发布、删除、安装软件、修改基础设施或传输数据。先用 ask，只放行已经理解的检查与验证命令；除非单独工作流明确需要，否则破坏性或外部变更动作继续 deny。

External directory 权限

工具触碰项目工作目录之外的路径时，会触发 external_directory。允许一个外部路径只代表它可达，普通的 Read、Edit 与命令规则仍然有效。

例如，工作流可以允许读取共享参考目录，但继续拒绝在其中编辑。不要只因为需要一个外部文件，就放行整个 Home 目录。应该选择能完成任务的最小可信路径。

为不同工作使用 per-agent override

OpenCode Agents 文档允许 Agent 专属权限。Agent 规则会与全局配置合并，并在匹配时优先。

这样可以建立与角色对应的边界：

• Planning 或 Review Agent 可以读取和搜索，但拒绝编辑；
• Build Agent 可以在编辑与测试命令前询问；
• Documentation Agent 只编辑一个内容目录，其他写入继续拒绝。

价值来自缩小每个工作的范围，而不是制造大量几乎相同的配置。清楚的全局基线，加少数具体 Override，会比复杂例外网络更容易审计。

OpenCode 当前包含 Plan 与 Build 等 Primary Agent，但不要只根据名称推断准确权限。应检查当前配置与官方文档，因为自定义 Override 会改变行为。

理解批准提示的范围

Stable OpenCode 权限解析为 ask 时，当前 UI 可以提供类似结果：

• 只批准这一次；
• 在当前 Session 中批准以后匹配建议 Pattern 的请求；
• 拒绝请求。

“Always”不代表系统永久宣布这项操作安全。它只在 Session 中批准建议的匹配模式。接受前要阅读 Pattern：一个前缀可能覆盖比当前可见动作更多的命令或路径。

动作是否可执行依赖当前上下文时，使用单次批准；只有理解生成 Pattern，而且确实还会重复同一个有边界操作时，才使用 Session 级重复批准。当目标、副作用、账号或回退路径不清楚时，应拒绝。

OpenCode 权限不能替代什么？

权限规则应与其他保护手段一起使用。

版本控制与回退

写入任务应在版本控制项目或一次性项目中运行。检查 Diff、保持改动小，并知道如何恢复涉及的准确文件。一个已获允许的破坏性动作删除未跟踪数据后，权限提示无法帮你重建内容。

环境隔离

使用独立开发凭证、最小权限 Cloud Role、测试数据库和隔离 Workspace。一个 deny Pattern 无法补偿操作系统或云账号本身权限过大。

Secret 管理

不要把 API Key 或凭证放进 Prompt、已提交文件、截图、日志与共享 Transcript。权限规则可以减少部分读取，却不是完整的 Data Loss Prevention 系统。

人工 Review 与验证

一个被允许的 Patch 仍然可能写错。根据改动风险运行仓库测试、Type Check、Lint、安全检查和需要的人类决策点。

Provider 与模型审查

Provider 决定模型请求在哪里处理，以及适用哪些账号条款。权限控制 Harness 中的工具动作，不会重新定义 Provider 数据处理方式。

如何测试一套权限策略？

使用不包含敏感数据的小型测试仓库。

1. 保存目标 stable 配置，确认 OpenCode 加载时没有 Schema 错误。
2. 让 Agent 读取普通源码，确认预期 allow 行为。
3. 让它读取虚构的 .env 文件，不使用真实凭证，确认 deny 行为。
4. 让它提出编辑，确认编辑会等待批准。
5. 测试你放行的准确只读 Shell Pattern，以及一个虚构的拒绝模式。
6. 引用 Workspace 外的无害文件，确认 external_directory 会询问。
7. 对 Agent 专属 Override 重复同样检查。
8. 扩大任何 allow 规则前，先检查 Diff 和命令输出。

记录 OpenCode 版本与测试日期。OpenCode 升级或配置发生实质变化后，再运行一遍检查。

适合真实工作的权限策略

目标不是把提示数量降到零，而是把人类注意力放在一旦出错就会产生明显后果的地方。

• 放行范围窄、可重复、已经检查过的读取与验证。
• 写入、新命令类别、外部路径、安装或账号敏感动作先询问。
• 对工作流永远不应该执行的操作保持 deny，尤其是破坏性与发布动作。
• 只有角色确实不同，才增加 per-agent override。
• 操作系统、仓库、云账号与 Provider 权限仍分别限制。

如果正在决定使用本地进程还是托管环境，可以另外比较本地与云端 OpenCode 环境。云端 Workspace 会改变 Runtime 边界，却不会消除显式工具权限的必要性。

OpenCode 权限在规则简短、具体、经过测试并且具备回退路径时最有用。先从保守设置开始，观察真实提示，再扩展那些你能够解释的规则。

FAQ

最安全的 OpenCode 权限设置是什么？

没有一套既适用于所有工作流、又保持可用性的通用最安全设置。deny 对匹配动作限制最严格，ask 保留人类检查点，allow 减少摩擦。应从完成明确任务所需的最小访问开始，并在隔离项目测试。

ask 会阻止 OpenCode 修改文件吗？

它会在匹配动作执行前要求人类批准。一旦批准，动作仍然可以改文件，所以要检查目标与最终 Diff。

为什么具体规则没有覆盖 *？

检查规则顺序和实际匹配输入。Stable OpenCode 的细粒度规则由最后一个匹配项生效，应把宽泛规则放在前面，具体例外放在后面。

.env 文件一定受到保护吗？

2026 年 8 月 27 日核验的 stable 默认设置会拒绝常见 .env 读取，同时允许 .env.example。显式配置或未来版本可以改变行为，不能把默认值当作唯一 Secret 保护。

Plan 和 Build 可以使用不同权限吗？

可以。Agent 专属规则可以覆盖全局基线。应该核对最终生效配置，而不是只依赖 Agent 名称。