跳转到内容
展示 生态 源码解读 文档

权限

权限

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、glob、grep 和许多 bash 命令）。

主目录扩展（如 ~/...）仅影响模式的编写方式。它不会使外部路径成为当前工作区的一部分，因此工作目录外的路径仍必须通过 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"
    }
  }
}

保持列表专注于受信任的路径，并根据需要添加额外的 allow 或 deny 规则（例如 bash）。

可用权限

OpenCode 权限按工具名称键入，加上一些安全保护：

  • read — 读取文件（匹配文件路径）
  • edit — 所有文件修改（涵盖 edit、write、patch）
  • glob — 文件 glob（匹配 glob 模式）
  • grep — 内容搜索（匹配正则表达式模式）
  • bash — 运行 shell 命令（匹配解析的命令如 git status --porcelain）
  • task — 启动子智能体（匹配子智能体类型）
  • skill — 加载技能（匹配技能名称）
  • lsp — 运行 LSP 查询（当前非细粒度）
  • question — 在执行期间向用户提问
  • webfetch — 获取 URL（匹配 URL）
  • websearch — 网络搜索（匹配查询）
  • 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 *": "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.