权限

控制哪些操作需要你的批准。

OpenCode 通过 permission 配置来决定某个操作是自动执行、向你确认，还是直接被阻止。

从 v1.1.1 起，旧的布尔型 tools 配置已废弃，并合并进 permission 中。为了兼容旧版本，tools 仍然可以使用，但不再推荐。

动作类型

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

"allow" —— 直接执行，不需要确认
"ask" —— 执行前弹出提示，询问是否允许
"deny" —— 直接禁止执行

配置方式

你可以通过通配符（如 *）设定全局默认，再为具体工具单独覆盖：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

也可以直接把所有权限一次性设为同一个值：

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

细粒度规则（对象语法）

对于大部分权限，你都可以使用对象语法，按输入内容做更细的区分：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

规则按模式匹配，最后匹配到的规则优先。常见写法是先写一个总的 "*" 规则，再写更具体的规则覆盖它。

通配符

权限模式使用简单的通配匹配：

* 匹配任意长度的任意字符（包括空字符串）
? 匹配单个任意字符
其他字符按字面含义匹配

可配置的权限项

OpenCode 中的权限键主要以工具名为主，外加若干安全保护项：

read —— 读文件（按文件路径匹配）
edit —— 修改文件（涵盖 edit、write、patch、multiedit）
glob —— 文件匹配（按 glob 模式匹配）
grep —— 内容搜索（按正则模式匹配）
list —— 列出目录内容（按目录路径匹配）
bash —— 运行 shell 命令（按解析后的命令，如 git status --porcelain 匹配）
task —— 启动子 Agent（按子 Agent 类型匹配）
skill —— 加载 skill（按 skill 名称匹配）
lsp —— LSP 查询（当前不分子项）
todoread、todowrite —— 读取/更新待办列表
webfetch —— 抓取 URL（按 URL 匹配）
websearch、codesearch —— Web / 代码搜索（按查询语句匹配）
external_directory —— 当工具访问到项目工作目录之外的路径时触发
doom_loop —— 当同一个工具以相同输入连续调用 3 次时触发

默认行为

如果你完全不配置 permission，OpenCode 会采用相对宽松的默认值：

大多数权限默认是 "allow"
doom_loop 和 external_directory 默认是 "ask"
read 默认是 "allow"，但 .env 文件默认被禁止读取：

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

“ask” 时发生了什么

当某个操作需要确认时，OpenCode 的 UI 会给出三种选择：

once —— 仅允许本次请求
always —— 在当前 OpenCode 会话内，自动允许之后所有匹配同一模式的请求
reject —— 拒绝该请求

always 会放宽的“匹配模式”由各工具提供（例如，bash 通常会建议以 git status* 这种前缀形式进行白名单）。

Agent 级别的权限

你可以在 Agent 级别覆盖全局权限。Agent 的权限会与全局配置合并，且 Agent 配置的优先级更高。详见 Agent 权限。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status": "allow",
          "git push": "allow"
        }
      }
    }
  }
}

你也可以在 Markdown 中为 Agent 配置权限：

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.