权限与安全

权限（Permission）与策略（Policy）的区分

Permission：控制 session 内工具能做什么（本页第一部分）
Policy：控制 OpenCode 是否可以使用某个已配置资源（目前仅 provider.use，本页第二部分）

两者是不同层面的门控，不要混用。

Permission 三态

allow（放行）/ ask（需批准）/ deny（禁用）。v1.1.1 起原来的 tools 布尔配置已废弃合并入 permission（仍向后兼容）。

Auto 模式

opencode --auto 或 opencode run --auto "..."：自动批准所有未被显式 deny 的权限请求；显式 deny 规则仍然生效。TUI 内可用命令面板切换 “Enable/Disable auto-approve permissions”，开启时提示符旁显示 auto 标记。

配置语法

{
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

也可整体设为字符串："permission": "allow"。

细粒度对象语法（Granular Rules）

{
  "permission": {
    "bash": {"*": "ask", "git *": "allow", "rm *": "deny"},
    "edit": {"*": "deny", "packages/web/src/content/docs/*.mdx": "allow"}
  }
}

匹配规则：按模式匹配，最后一条匹配规则生效，因此惯例是把 * 通配放最前，具体规则放后面覆盖。

通配符：* 匹配任意长度字符，? 匹配单字符。

~/$HOME 可用于路径开头展开为用户目录
external_directory 权限键专门控制”触达工作区外路径”的行为（适用于 read/edit/glob/grep 及很多 bash 命令），home 展开本身不代表纳入工作区,仍需显式 external_directory 规则放行外部路径

可用权限键完整列表

read、edit（覆盖 edit/write/apply_patch）、glob、grep、bash、task（子 Agent 调用）、skill、lsp（当前非细粒度）、question、webfetch、websearch、external_directory、doom_loop（同一工具调用连续 3 次完全相同输入时触发）。

默认值

大多数权限默认 allow
doom_loop、external_directory 默认 ask
read 默认 allow，但 .env / .env.* 默认 deny（.env.example 例外 allow）——这是 OpenCode 内置的一条安全默认规则

”Ask” 时的三个可选结果

once（仅本次）/ always（本 session 内后续匹配请求自动批准）/ reject（拒绝）。

Agent 级覆盖

Agent 的 permission 与全局配置合并，Agent 规则优先。也可在 Markdown Agent 文件的 frontmatter 中定义（详见 Agent系统）。

Policy（资源策略，实验特性）

配置在 experimental.policies 数组，每条含 effect(allow/deny)、action、resource。目前仅支持一种 action：provider.use（控制能否使用某 LLM Provider）。

{
  "experimental": {
    "policies": [
      {"effect": "deny", "action": "provider.use", "resource": "openai"}
    ]
  }
}

resource 支持通配符（company-*）
最后匹配规则生效，惯用先写宽泛 deny 再写具体 allow 做白名单
未匹配任何规则时默认允许
全局配置的 policy 优先于项目配置（防止仓库越权重新启用被组织禁用的 Provider）——这是与 permission 不同的优先级方向（permission 是就近覆盖，policy 是全局压制项目）
官方建议用 Policy 取代旧的 disabled_providers/enabled_providers 配置项

网络与证书（企业网络环境）

支持标准代理环境变量 HTTPS_PROXY/HTTP_PROXY；必须用 NO_PROXY=localhost,127.0.0.1 放行本地 TUI↔本地 HTTP server 通信，否则会形成路由环
代理认证：URL 内嵌 user:pass（不建议硬编码密码，用环境变量）；NTLM/Kerberos 等高级认证建议改用支持该认证方式的 LLM Gateway 中转
自定义 CA 证书：NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Enterprise（企业部署）

核心承诺：OpenCode 不存储代码或上下文数据，处理均在本地或直连你配置的 AI Provider 完成
唯一例外是 /share 功能（若启用，对话数据会发送到 opencode.ai 托管的分享页 CDN），企业试用建议 "share": "disabled"
代码归属：用户拥有 OpenCode 产出的全部代码，无许可限制
定价：按座位收费；若已有自建 LLM Gateway，不额外收 token 费用
部署能力：集中式配置（Central Config）+ SSO 集成 + 内部 AI Gateway 强制路由（可禁用其他 Provider）；分享页自托管在路线图中
私有 npm registry 支持：基于 Bun 原生 .npmrc 支持（如 JFrog Artifactory/Nexus），需提前 npm login --registry=... 完成认证

关联

索引 — 返回总索引
Agent系统 — Permission 作为 Agent 的工具门控机制
模型与订阅 — Policy 常用于限制 Provider 访问范围
对比Claude-Code — 权限模型（allow/ask/deny + 细粒度 glob）与 Claude Code 的权限模式高度相似

来源

https://opencode.ai/docs/{permissions,policies,network,enterprise}.mdx（dev 分支）。整理：赵卫国 2026-07-07。

Wiki AI

目录

OpenCode 权限与安全