OpenCode 使用 permission config 来决定某个 action（操作）是否可以自动执行、是否需要提示你确认，或者是否应被阻止。

从 v1.1.1 开始，旧版的 tools boolean config 已被弃用（deprecated），并已合并进 permission。 为了向后兼容（backwards compatibility），旧的 tools config 仍然被支持。

Actions（动作类型）

每一条 permission rule（权限规则）最终会解析为以下三种之一：

  • "allow" — 无需审批，直接执行
  • "ask" — 需要提示你确认
  • "deny" — 阻止该操作

Configuration（配置）

你可以通过 * 设置全局权限，并对特定 tool 进行覆盖。

  1. {
  2.   "$schema": "https://opencode.ai/config.json",
  3.   "permission": {
  4.     "*": "ask",
  5.     "bash": "allow",
  6.     "edit": "deny"
  7.   }
  8. }

你也可以一次性设置所有权限：

  1. {
  2.   "$schema": "https://opencode.ai/config.json",
  3.   "permission": "allow"
  4. }

Granular Rules（细粒度规则，Object 语法）

对于大多数 permissions，你可以使用 object，根据 tool input（工具输入）来应用不同的 action。

  1. {
  2.   "$schema": "https://opencode.ai/config.json",
  3.   "permission": {
  4.     "bash": {
  5.       "*": "ask",
  6.       "git *": "allow",
  7.       "npm *": "allow",
  8.       "rm *": "deny"
  9.     },
  10.     "edit": {
  11.       "*": "deny",
  12.       "packages/web/src/content/docs/*.mdx": "allow"
  13.     }
  14.   }
  15. }

规则是通过 pattern match（模式匹配）进行评估的，并且遵循 最后一个匹配规则生效（last matching rule wins） 的原则。 常见写法是：先写兜底规则 "*"，再写更具体的规则。

Wildcards（通配符）

permission pattern 使用简单的通配符匹配规则：

  • * 匹配零个或多个任意字符
  • ? 精确匹配一个字符
  • 其他字符按字面量匹配

Available Permissions（可用权限）

OpenCode 的 permissions 以 tool name（工具名）作为 key，并包含一些安全防护项（safety guards）：

  • read — 读取文件（匹配 file path）
  • edit — 所有文件修改操作（覆盖 edit、write、patch、multiedit）
  • glob — 文件 glob 匹配（匹配 glob pattern）
  • grep — 内容搜索（匹配 regex pattern）
  • list — 列出目录文件（匹配 directory path）
  • bash — 执行 shell commands（匹配解析后的命令，例如 git status --porcelain）
  • task — 启动 subagents（匹配 subagent 类型）
  • skill — 加载 skill（匹配 skill 名称）
  • lsp — 执行 LSP 查询（当前不支持细粒度控制）
  • todoread、todowrite — 读取 / 更新 todo list
  • webfetch — 请求 URL（匹配 URL）
  • websearch、codesearch — Web / Code 搜索（匹配 query）
  • external_directory — 当 tool 访问项目工作目录之外的路径时触发
  • doom_loop — 当相同的 tool call 连续 3 次以相同 input 重复时触发

Defaults（默认行为）

如果你没有做任何配置，OpenCode 会使用较为宽松（permissive）的默认策略：

  • 大多数 permissions 默认是 "allow"。
  • doom_loop 和 external_directory 默认是 "ask"。
  • read 默认是 "allow"，但 .env 文件默认被拒绝（deny）：
  1. {
  2.   "permission": {
  3.     "read": {
  4.       "*": "allow",
  5.       "*.env": "deny",
  6.       "*.env.*": "deny",
  7.       "*.env.example": "allow"
  8.     }
  9.   }
  10. }

What “Ask” Does（“Ask” 的行为）

当 OpenCode 请求你进行确认时，UI 会提供三种选择结果：

  • once — 仅批准本次请求
  • always — 批准未来所有匹配建议 pattern 的请求（仅在当前 OpenCode session 内生效）
  • reject — 拒绝该请求

always 将批准的 pattern 集合由 tool 提供。 例如，bash 的审批通常会自动加入安全的命令前缀白名单（如 git status*）。

Agents（代理权限）

你可以为每个 agent 覆盖 permissions。 agent 的 permissions 会与全局配置合并，并且 agent 规则优先生效。 更多信息请参考 Learn more。

  1. {
  2.   "$schema": "https://opencode.ai/config.json",
  3.   "permission": {
  4.     "bash": {
  5.       "*": "ask",
  6.       "git status": "allow"
  7.     }
  8.   },
  9.   "agent": {
  10.     "build": {
  11.       "permission": {
  12.         "bash": {
  13.           "*": "ask",
  14.           "git status": "allow",
  15.           "git push": "allow"
  16.         }
  17.       }
  18.     }
  19.   }
  20. }

你也可以使用 Markdown 来配置 agent permissions：

  1. description: Code review without edits
  2. mode: subagent
  3. permission:
  4.   edit: deny
  5.   bash: ask
  6.   webfetch: deny
  8. Only analyze code and suggest changes.