权限

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

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 — 启动子智能体 (subagents)（匹配子智能体类型）
skill — 加载技能 (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 提示审批时，UI 提供三种结果：

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
---

仅分析代码并建议更改。