跳至主要內容

OpenCode 权限配置教程

2026/6/11大约 12 分钟

OpenCode 权限配置教程

OpenCode 内置完善的权限管控系统，是保障项目代码、文件与系统安全的核心能力。该系统可对文件读写、终端命令、网络请求、子代理调用等所有工具操作进行精细化管控，支持直接放行、人工审批、彻底禁止三种权限策略。从 v1.1.1 版本开始，OpenCode 将旧版独立的 tools 布尔配置全面合并至 permission 权限体系中，旧版 tools 配置仍保留向后兼容性，建议用户统一使用全新权限语法进行配置。

本文将从权限基础规则、配置语法、全量权限项、特殊场景配置、代理独立权限、审批交互、实战案例等维度，全方位讲解 OpenCode 权限系统的使用方法，帮助开发者根据本地开发、团队协作、生产环境等不同场景，搭建兼顾效率与安全的权限策略。

一、权限核心基础规则

在开始配置前，首先掌握权限动作、匹配规则、通配符与路径展开等基础规则，这是正确编写权限配置的前提。

1.1 三大权限动作

OpenCode 所有权限规则最终都会解析为以下三种动作，管控工具的执行方式：

  1. allow：直接放行，工具无需人工审批，自动执行，适用于安全的常规操作。

  2. ask：审批模式，触发操作后弹出审批弹窗，需人工确认后方可执行，是高危操作的推荐配置。

  3. deny：彻底禁止，拦截对应操作，工具无法执行，适用于隐私文件、高危命令等场景。

1.2 规则匹配优先级

权限采用自上而下解析、最后匹配优先的规则：

  • 编写规则时，建议将通用通配规则（如 *）放置在配置靠前位置，具体细分规则放在后方；

  • 当一条操作同时匹配多条规则时，以最后命中的规则作为最终执行依据。

1.3 通配符语法

权限模式支持两类基础通配符，用于模糊匹配文件路径、终端命令、URL 等内容：

  1. *：匹配零个或多个任意字符，使用频率最高；

  2. ?：精确匹配单个字符。

1.4 主目录路径展开

配置路径类规则时，可使用 ~ 或 $HOME 代表系统当前用户主目录，系统会自动完成路径解析，简化跨设备配置：

  • ~/projects/*：匹配用户主目录下 projects 文件夹内所有内容；

  • ~：直接匹配当前用户主目录根路径。

示例：在 Windows、macOS、Linux 系统中，~/docs 都会自动转换为对应系统的用户文档目录。

二、权限基础配置语法

OpenCode 权限统一在 opencode.json 配置文件的 permission 节点中编写，分为极简全局配置、基础键值配置、细粒度对象配置三种语法，适配不同复杂度的管控需求。

2.1 极简全局配置

当需要对所有操作统一设置权限时，可直接将 permission 赋值为单一权限动作，语法最简。

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

示例说明：全局放行所有工具操作，适合个人本地开发环境。

2.2 基础键值配置

按工具维度单独设置权限，每个工具对应一条规则，适合简单的权限管控场景。

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

示例说明：默认所有操作需要审批；终端命令直接放行；文件修改操作彻底禁止。

2.3 细粒度对象配置

针对单一工具，再根据命令内容、文件路径、URL等细分规则管控，是生产环境、复杂项目的主流配置方式。该语法支持对同一个工具区分不同执行内容，设置差异化权限。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    // 细分终端命令权限
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny",
      "npm *": "allow"
    },
    // 细分文件编辑权限
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

示例说明：终端命令默认需审批，放行 Git、Npm 相关命令，禁止删除命令；文件修改默认禁止，仅允许编辑指定目录下的 mdx 文档。

三、全量可用权限项详解

OpenCode 提供十余类权限项，覆盖文件操作、命令执行、网络访问、代理调用、目录访问等全场景。下文逐个说明权限项的管控范围、默认规则与适用场景。

权限项管控范围默认规则补充说明
read读取文件内容、文件路径匹配allow特殊默认：自动拒绝 .env、.env.* 隐私配置文件，仅放行 .env.example
edit所有文件修改操作allow统一管控 edit/write/patch/multiedit 四类文件编辑工具
glob基于通配符查找文件allow匹配文件通配模式，常用于批量文件检索
grep正则检索文件内容allow匹配检索关键词与文件范围
bash执行 Shell 终端命令allow匹配解析后的完整命令（含参数）
task主代理调用子代理allow匹配目标子代理名称，管控代理之间的调用权限
skill加载项目技能文件（[SKILL.md](SKILL.md)）allow匹配技能文件名称
lsp调用 LSP 代码智能服务allow暂不支持细粒度规则，仅支持全局开关
webfetch拉取远程网页内容allow匹配目标 URL 地址
websearch/codesearch全网 / 代码库搜索allow匹配搜索关键词
external_directory访问项目工作目录外的路径ask安全防护项，默认访问外部目录需审批
doom_loop同一工具重复 3 次相同调用ask防死循环机制，触发后默认需审批

四、特殊权限场景配置

针对跨目录访问、循环调用防护两类特殊安全场景，OpenCode 提供专属权限配置，下文结合示例讲解用法。

4.1 外部目录访问（external_directory）

默认情况下，OpenCode 仅允许访问当前项目工作目录，如需读取、编辑其他目录的文件，必须通过 external_directory 授权。该权限常配合主目录展开语法使用。

4.1.1 基础授权（允许访问外部目录）

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

示例说明：授权访问用户主目录下 projects/personal 目录下所有文件，继承全局默认权限。

4.1.2 叠加细分规则（允许读、禁止改）

授权外部目录后，可单独叠加 edit、bash 等规则，限制外部目录的高危操作：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    // 禁止编辑该外部目录下的所有文件
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

4.2 循环调用防护（doom_loop）

当同一个工具以完全相同的输入连续调用 3 次时，会触发 doom_loop 权限，用于拦截代码死循环、异常批量调用。默认规则为 ask，可手动修改：

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

示例说明：直接禁止重复调用，彻底拦截死循环场景。

五、Ask 模式审批交互逻辑

当权限规则设置为 ask 时，操作触发后会在界面弹出审批窗口，提供三种操作选项，按需选择即可：

  1. once：仅批准本次操作，下次相同调用仍需重新审批；

  2. always：本次会话内永久放行该类操作，系统会自动将匹配规则加入临时白名单，会话结束后失效；

  3. reject：拒绝本次操作，拦截当前调用。

补充：always 选项会根据工具类型自动生成临时白名单，例如放行 git status 后，同前缀的 Git 查询命令会一并临时授权。

六、代理独立权限配置

OpenCode 支持为单个代理单独配置权限，代理权限优先级高于全局权限，会与全局规则合并生效。支持 opencode.json（全局配置）和 Markdown 代理文件（独立代理配置）两种写法。

6.1 JSON 文件配置（全局 + 代理覆写）

在全局权限基础上，针对指定代理修改规则，适合批量管理多个代理：

{
  "$schema": "https://opencode.ai/config.json",
  // 全局权限
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git push *": "deny"
    }
  },
  // 单独覆写 build 代理的权限
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny"
        }
      }
    }
  }
}

6.2 Markdown 代理文件配置

在代理的 .md 配置文件中直接编写 permission 节点，仅对当前代理生效，适合独立代理精细化管控。
文件路径参考：全局代理 ~/.config/opencode/agents/、项目代理 .opencode/agents/

---
description: 代码审查只读代理
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
仅分析代码，不执行文件修改与网络请求。

补充：命令匹配细节

使用细粒度规则时，带参数的命令必须添加通配符 *****：

  • 正确写法："git status *"（匹配带参数的 git status 命令）；

  • 错误写法："git status"（仅匹配无参数指令，无法拦截带参数调用）。

七、OpenCode 默认权限规则

若未编写任何 permission 配置，OpenCode 会启用内置默认规则，以下是官方默认配置完整版，可作为配置参考：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    // 常规工具默认放行
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "edit": "allow",
    "bash": "allow",
    "glob": "allow",
    "grep": "allow",
    // 安全防护类默认需审批
    "external_directory": "ask",
    "doom_loop": "ask",
    // 其他工具默认放行
    "task": "allow",
    "skill": "allow",
    "webfetch": "allow",
    "websearch": "allow"
  }
}

核心默认特性：默认保护 .env 隐私文件，访问外部目录、触发循环调用默认需要审批。

八、实战配置案例

结合本地开发、团队生产、代码审计、隐私防护等常见场景，提供可直接复用的完整配置案例。

案例 1：个人本地开发配置（宽松模式）

本地信任环境，全局放行，仅禁止删除高危命令与读取隐私文件：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "allow",
    "bash": {
      "rm *": "deny"
    },
    "read": {
      "*.env": "deny",
      "*.env.*": "deny"
    }
  }
}

案例 2：生产项目安全配置（严格模式）

所有操作默认审批，放行常用查询命令，禁止文件修改、推送、删除等高风险操作：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "edit": "deny",
    "bash": {
      "git status *": "allow",
      "grep *": "allow",
      "ls *": "allow",
      "rm *": "deny",
      "git push *": "deny"
    }
  }
}

案例 3：授权访问外部共享目录

允许读取公共代码目录，但禁止修改其中任何文件：

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

案例 4：只读审计代理配置

创建纯审计代理，禁止所有文件修改、终端命令与网络请求：

---
description: 项目安全审计代理（只读）
mode: subagent
permission:
  edit: deny
  write: deny
  bash: deny
  webfetch: deny
  websearch: deny
---
仅对代码进行安全审计、漏洞分析，不执行任何修改与外部请求。

九、重要使用注意事项

  1. 规则排序必须规范：通用通配规则（如 *）务必放在细分规则前方，否则会导致细分规则失效，遵循「先通用、后具体」原则。

  2. 命令与路径匹配需完整：匹配带参数的终端命令、带后缀的文件路径时，必须搭配 * 通配符，仅写基础指令无法生效。

  3. 外部目录严控权限：external_directory 仅在必要时授权，不要全局放行所有外部路径；对外部分配建议遵循「最小权限原则」，仅开放必要目录。

  4. 主目录展开仅限路径：~ 和 $HOME 仅用于文件 / 目录路径匹配，不可用于终端命令、URL 等非路径规则。

  5. 旧版配置兼容说明：v1.1.1 之前的 tools 布尔配置仍可使用，但官方不再维护，新项目建议统一迁移至 permission 语法。

  6. 强化隐私文件防护：除默认拦截的 .env 文件外，可手动补充 *.pem、*.key、password.txt 等密钥、密码文件的禁止读取规则。

  7. 代理权限优先级牢记：代理独立权限会覆盖全局同名规则，调试权限问题时，优先检查当前代理的专属配置。

  8. LSP 工具限制：lsp 权限仅支持全局 allow/ask/deny 开关，不支持基于文件、指令的细粒度匹配。

十、权限配置最佳实践

10.1 个人本地开发场景

本地环境信任度高，以效率为主：

  • 全局设置 permission: allow，放行常规操作；

  • 仅针对性禁止 rm、git push 等高危命令与隐私文件读取；

  • 无需严格限制 external_directory，方便跨目录查阅文件。

10.2 团队 / 生产项目场景

以安全为核心，兼顾协作效率：

  • 全局默认设置为 ask，所有操作人工把关；

  • 放行 git status、grep、ls 等安全查询命令；

  • 彻底禁止 rm、格式化、代码提交 / 推送等高危操作；

  • 严格管控 external_directory，仅授权项目必需的外部目录。

10.3 代码审计 / 文档查看场景

纯只读场景，彻底禁用修改能力：

  • 将 edit、write、patch 全部设置为 deny；

  • 终端命令设置为 ask，仅临时允许查询类指令；

  • 按需禁用 webfetch/websearch 网络能力，防止外网请求泄露信息。

10.4 多代理协作场景

区分代理职能，差异化配置权限：

  • Build（开发代理）：适度放行文件编辑、构建命令，高危命令设为 ask；

  • Plan/Explore（分析 / 检索代理）：禁用文件修改，仅放行读取、检索工具；

  • 子代理：根据职能最小化授权，无关工具全部禁止。

总结

OpenCode 的 permission 权限系统是分层、精细化的安全管控体系，从全局规则、工具规则、代理规则形成三级防护，同时支持通配符、路径展开、外部目录授权等拓展能力。

在实际使用中，需根据运行环境平衡安全与效率：个人本地可放宽权限提升开发速度，团队与生产环境必须收紧高危操作、强化隐私文件防护；多代理场景下利用代理独立权限实现职能隔离。同时严格遵循规则排序、通配符使用等规范，避免因配置错误导致权限失效。

熟练掌握权限配置，既能充分发挥 OpenCode 的自动化能力，又能有效规避文件篡改、命令误执行、信息泄露等安全风险，是企业与团队规范化使用 OpenCode 的必备技能。