权限

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

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 目录展开

你可以在模式开头使用 ~ 或 $HOME 来引用你的 home 目录。这对 external_directory 规则尤其有用。

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

外部目录

使用 external_directory 来允许那些会触及 OpenCode 启动时所在工作目录之外路径的工具调用。这适用于任何以路径作为输入的工具（例如 read、edit、glob、grep 以及许多 bash 命令）。

Home 展开（如 ~/...）只影响模式的书写方式。它不会让一个外部路径成为当前工作区的一部分，因此工作目录之外的路径仍必须通过 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）
• glob — 文件 glob（匹配 glob 模式）
• grep — 内容搜索（匹配正则模式）
• bash — 运行 shell 命令（匹配解析后的命令，如 git status --porcelain）
• task — 启动子 agent（匹配子 agent 类型）
• skill — 加载技能（匹配技能名称）
• lsp — 运行 LSP 查询（目前不支持细粒度）
• question — 在执行期间向用户提问
• webfetch — 抓取 URL（匹配 URL）
• websearch — Web 搜索（匹配查询）
• 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*）。

Agent

你可以按 agent 覆盖权限。Agent 权限会与全局配置合并，且 agent 规则优先。了解更多 关于 agent 权限的内容。

注意： 更详细的模式匹配示例请参阅上方的“细粒度规则（对象语法）”一节。

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

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
 
Only analyze code and suggest changes.

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