Permissions - OpenCode Docs | OpenCode Tutorial

OpenCode 使用 permission 配置来决定是否自动运行、提示您或阻止给定的操作。

从 v1.1.1 开始，旧的 tools 布尔配置已被弃用，并已合并到 permission 中。旧的 tools 配置仍然支持向后兼容。

##操作 (Actions)

每个权限规则解析为以下之一：

"allow" — 无需批准即可运行
"ask" — 提示批准
"deny" — 阻止操作

##配置 (Configuration)

您可以全局设置权限（使用 *），并覆盖特定工具。

bash

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

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

bash

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

##细粒度规则（对象语法）

对于大多数权限，您可以使用对象来根据工具输入应用不同的操作。

bash

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

规则通过模式匹配进行评估，最后匹配的规则获胜。一种常见的模式是首先放置捕获所有 "*" 规则，然后在之后放置更具体的规则。

###通配符 (Wildcards)

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

* 匹配零个或多个任意字符
? 匹配恰好一个字符
所有其他字符按字面匹配

##可用权限 (Available Permissions)

OpenCode 权限由工具名称以及一些安全保护措施进行键控：

read — 读取文件（匹配文件路径）
edit — 所有文件修改（涵盖 edit、write、patch、multiedit）
glob — 文件 globbing（匹配 glob 模式）
grep — 内容搜索（匹配正则表达式模式）
list — 列出目录中的文件（匹配目录路径）
bash — 运行 shell 命令（匹配已解析的命令，如 git status --porcelain）
task — 启动子代理（匹配子代理类型）
skill — 加载技能（匹配技能名称）
lsp — 运行 LSP 查询（目前非粒度）
todoread、todowrite — 读取/更新待办事项列表
webfetch — 获取 URL（匹配 URL）
websearch、codesearch — 网络/代码搜索（匹配查询）
external_directory — 当工具接触项目工作目录之外的路径时触发
doom_loop — 当相同的工具调用使用相同的输入重复 3 次时触发

##默认值 (Defaults)

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

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

bash

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

##“询问 (Ask)” 的作用

当 OpenCode 提示批准时，UI 提供三个结果：

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

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

##代理 (Agents)

您可以覆盖每个代理的权限。代理权限与全局配置合并，并且代理规则优先。有关代理权限的更多信息，请了解更多。

Note

📝 注意

有关更详细的模式匹配示例，请参阅上面的细粒度规则（对象语法）部分。

bash

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

您还可以在 Markdown 中配置代理权限：

bash

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

Only analyze code and suggest changes.

Note

💡 提示

对带有参数的命令使用模式匹配。 "grep *" 允许 grep pattern file.txt，而单独的 "grep" 会阻止它。像 git status 这样的命令适用于默认行为，但在传递参数时需要显式权限（如 "git status *"）。