权限

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

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",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

规则通过模式匹配進行評估，最后匹配的规则獲勝。常見的模式是将包羅万象的 "*" 规则放在前面，然後再放置更具體的规则。

通配符

权限模式使用簡單的通配符匹配：

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

主目录扩展

您可以在模式目录中使用 ~ 或 $HOME 来引用您的主目录。这对于 external_directory 规则特别有用。

~/projects/* -> /Users/username/projects/*
$HOME/projects/* -> /Users/username/projects/*
~ -> /Users/username

外部目录

使用 external_directory 允许工具调用启动 opencode 的工作目录之外的路径。这适用于任何采用路径作为输入的工具（例如 read、edit、list、glob、grep 和许多Zbash 命令）。

主扩展（如~/...）仅影响模式的编写方式。它不会使外部路径成为当前工作空间的一部分，因此仍然必须通过 external_directory 允许工作目录之外的路径。

例如，这允许访问~/projects/personal/下的所有内容：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

这里允许的任何目录都会继承与当前工作空间默认相同的值。自read默认为allow起，也允许读取external_directory下面的边界，除非被覆盖。当工具应在这些路径中时添加显式规则，例如在保留读取的同时阻止编辑：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

将列表重点放在受信任的路径上，并根据其他工具的需要分层额外的允许或拒绝规则（例如bash）。

可用权限

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

“問”的作用是什麼

当 opencode 提示批准时，UI 会提供清晰的结果：

once — 仅批准此请求
always — 批准与建议模式匹配的未来请求（对于当前 opencode 会话的其余部分）
reject — 拒绝请求

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

代理商

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

{
  "$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 中配置代理权限：

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

Only analyze code and suggest changes.