opencode 权限:allow、ask、deny

opencode 的每个动作——读文件、改代码、跑 shell 命令——都会落到三种结果之一:直接执行、先问你、直接拦下。permission 配置决定走哪条。自 v1.1.1 起,旧的布尔型 tools 配置已废弃并入 permission(仍然兼容)。

三种动作

每条规则解析为 "allow"(不询问直接执行)、"ask"(在 TUI 里弹审批)或 "deny"(直接拦下)。

配置方式

用 "*" 设全局默认,再按工具覆盖:

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

一刀切写法:"permission": "allow"。

细粒度规则

多数权限接受一个对象,把输入模式映射到动作。最后命中的规则生效——兜底的 "*" 放前面,更具体的模式放后面:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "shell": {
      "*": "ask",
      "git *": "allow",
      "git push *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    },
    "webfetch": {
      "*": "ask",
      "https://en.wikipedia.org/*": "allow"
    }
  }
}

通配符很简单:* 匹配任意多个字符,? 匹配恰好一个字符,其余按字面匹配。模式开头的 ~ 或 $HOME 展开为家目录。模式匹配的是工具输入——read/edit 匹配文件路径,glob 匹配 glob 表达式,grep 匹配正则,webfetch 匹配 URL,shell 匹配解析后的命令。要匹配完整命令而不只是命令名:"grep *" 放行 grep pattern file.txt,光写 "grep" 会在带参数时被拦下。

权限键一览

键	匹配对象
`read`	文件路径
`edit`	文件路径——涵盖 `edit`、`write`、`patch`
`glob`	glob 表达式
`grep`	正则表达式
`list`	目录路径——`ls` 工具
`shell`	解析后的命令(如 `git status --porcelain`)
`task`	子 agent 类型
`skill`	skill 名称
`lsp`	LSP 查询(不支持细粒度)
`question`	执行中向你提问
`webfetch`	URL
`websearch`	网络搜索
`external_directory`	触及工作目录外路径的工具调用
`doom_loop`	相同输入的工具调用重复 3 次

默认偏宽松:多数键是 allow,两个安全兜底 external_directory 和 doom_loop 默认 ask。read 放行一切,唯独 .env 文件(*.env 与 *.env.* deny,*.env.example allow)。

external_directory 管的是触及启动目录之外路径的工具调用。显式放行信任的目录:

{
  "permission": {
    "external_directory": { "~/projects/personal/**": "allow" },
    "edit": { "~/projects/personal/**": "deny" }
  }
}

放行的目录继承工作区默认——read 默认 allow 所以直接可读,需要限制的地方(比如 edit)再叠 deny 规则。

ask 时会发生什么

审批弹窗给三个选项:

once——只批准这一次
always——批准本次会话内匹配工具建议模式的后续请求(shell 审批一般建议安全前缀,如 git status*)
reject——拒绝

Auto 模式自动批准一切未被显式 deny 的请求:用 opencode --auto 或 opencode run --auto "…" 启动,或在命令面板里开关(Enable auto-approve permissions)。deny 规则照常生效。开启后 agent 名旁会显示灰色的 auto 标记。

按 agent 覆盖

agent 有自己的 permission 块,与全局配置合并且 agent 规则优先:

{
  "agent": {
    "plan": {
      "permission": {
        "edit": { "*": "deny", "~/.opencode/plan/*": "allow" },
        "shell": "ask"
      }
    }
  }
}

内置 plan agent 默认就禁止 ~/.opencode/plan/ 之外的编辑(直接拒绝不提示),并放行 question 工具——但 shell 命令跟随你的 permission 配置。注意顺序:plan 的默认值在顶层 permission 之前生效,所以全局 "edit": "allow" 会重新打开编辑权限——想保持 plan 只读,就显式钉住 agent.plan.permission。Markdown 定义的 agent(~/.config/opencode/agents/*.md)可在 frontmatter 里写同样的 permission: 块。

v2 差异

v2 把整块重做了:permissions(复数)是 { "action", "resource", "effect" } 有序规则数组——后者覆盖前者——取代 v1 的 permission 对象,配置文件为 opencode.jsonc。action 改名 bash→shell、task→subagent;doom_loop 和 lsp 不在 v2 action 之列。默认值也变了:v2 对 .env 读取是 ask 而非 deny。本篇对应 v1 的配置。