权限

控制哪些操作需要批准才能运行。

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 — 文件通配（匹配通配符模式）
grep — 内容搜索（匹配正则表达式模式）
list — 列出目录中的文件（匹配目录路径）
bash — 运行 shell 命令（匹配解析后的命令，如 git status --porcelain）
task — 启动子代理（匹配子代理类型）
skill — 加载技能（匹配技能名称）
lsp — 运行 LSP 查询（目前不支持细粒度控制）
todoread, todowrite — 读取/更新待办事项列表
webfetch — 获取 URL（匹配 URL）
websearch, codesearch — 网页/代码搜索（匹配查询）
external_directory — 当工具触及项目工作目录之外的路径时触发
doom_loop — 当相同的工具调用以相同的输入重复 3 次时触发

默认设置

如果您不指定任何内容，OpenCode 将从宽松的默认设置开始：

大多数权限默认为 "allow"。
doom_loop 和 external_directory 默认为 "ask"。
read 为 "allow"，但默认拒绝 .env 文件：

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

“Ask” 的作用

当 OpenCode 请求批准时，用户界面提供三种结果：

once — 仅批准此请求
always — 批准匹配建议模式的未来请求（在当前 OpenCode 会话的剩余时间内）
reject — 拒绝该请求

always 将批准的模式集由工具提供（例如，bash 批准通常会将安全的命令前缀如 git status* 加入白名单）。

代理

你可以为每个代理单独覆盖权限设置。代理权限会与全局配置合并，代理规则具有优先权。了解更多关于代理权限的信息。

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

你也可以在 Markdown 中配置代理权限：

---
description: 仅进行代码审查，不进行编辑
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

仅分析代码并提出修改建议。