OpenCodePermissionsAgentNbility

OpenCode 权限规则怎么写,才不会越改越宽

OpenCode V2 权限使用按顺序匹配的 permissions 规则,最后匹配项生效;区分 Agent 权限、长期批准和真实系统隔离,并用公开文件验证。

查看接入文档
OpenCode 权限规则怎么写,才不会越改越宽

OpenCode V2 的权限规则按顺序匹配,最后匹配的条目决定动作是允许、拒绝还是询问。写在前面的 deny 可能被后面的 allow 覆盖;主 Agent 的限制也不会自动成为子 Agent 权限的上限。想减少意外执行,必须同时核对规则顺序、实际 Agent 和客户端的审批行为。

本文于 2026 年 11 月 21 日阅读官方权限文档、Agent 文档及其 v2.3.2 标签版本。配置是 V2 的 permissions / shell / subagent,不要原样塞进 V1 的 permission / bash / task。本文未运行真实客户端权限验收,下面给出可用公开数据完成的检查方法。

默认会询问每个动作吗

不会。官方列出的基础策略先允许全部动作,再对 .env 和 .env.* 读取设为询问,对 .env.example 放行。虽然“没有任何规则匹配”时会询问,基础策略已经让许多动作匹配到了允许。

Build 默认可用工具并访问工作区外位置。Plan 会限制普通文件编辑,但 Shell 仍按自身规则检查;不能只凭名字把它当成操作系统级只读环境。

从规则文件与 Skills移来的一句“不要修改”,也不能替代执行层的拒绝。规则文件负责说明任务,权限决定工具是否能做。

如何写一个有明确例外的规则表

先在公开演示项目的 opencode.json 写下常规询问,再逐条留出允许和拒绝的例外:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

这是解释规则组合的例子,不是完整安全配置。git diff * 放行的是一个命令族,实际 Git 配置和参数也会影响行为;只应对你信任的演示仓库使用。准备更严格的执行环境时,应进一步缩小允许的命令和系统权限。

宽规则在前,具体例外在后,分别得到允许、询问和拒绝

V2 的 * 可匹配包括 / 在内的多个字符,? 匹配一个字符;不是完整正则表达式。以空格加 * 结尾的 Shell 规则也匹配无参数命令,所以 git status * 能覆盖 git status。

一个操作可能检查多个资源,例如补丁涉及多个文件:任一资源被拒绝,整个操作拒绝;否则有询问项就询问。不要只检查其中一个“安全文件”后认定整次修改通过。

子 Agent 会继承主 Agent 的全部限制吗

不会以“父权限子集”的方式继承。全局规则先应用,Agent 自己的规则追加在后;子 Agent 使用自己的配置。因此,限制主 Agent 的 agents.build.permissions,不能证明 general 或自建 reviewer 也同样受限。

如果你只想允许主任务调用一个特定 reviewer,可以控制 subagent 的目标 ID:

{
  "agents": {
    "build": {
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "reviewer", "effect": "allow" }
      ]
    },
    "reviewer": {
      "description": "Review code without changing files or running shell commands",
      "mode": "subagent",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" },
        { "action": "shell", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "*", "effect": "deny" }
      ]
    }
  }
}

这个 reviewer 禁止了文件修改、Shell 与继续派生,未限制的其他动作仍受其余生效规则控制;若还连着会写入的 MCP 工具,须继续按 Agent 限制 MCP。不要把提示里的“只读审查”当成所有工具都已只读。

Always allow 会留下什么

它会保存项目范围的持久批准规则。一次命令可能提出覆盖整个命令前缀的模式;以后相似动作可能不再询问。先看拟保存的模式,再决定是仅本次允许,还是长期允许。

保存的批准不能覆盖配置中的 deny,但其他更晚匹配的配置规则仍可能改变结果。组织需要强制拒绝时,可以另查官方 Policies;不要靠一个可被项目后续配置放宽的条目建立组织边界。

规则计算、已保存批准和客户端处理共同影响可见审批,系统权限另行限制

external_directory 用于项目范围外的路径检查,Shell 则还要依靠命令分析。官方明确:Shell 具有运行用户的文件、进程与网络权限,目录推断尽力而为。允许一个通用解释器命令后,不要再把路径提示当成完整沙箱。

写了 ask 却不弹窗,能直接改成 allow 吗

先查实际执行环境。近期 #65248 报告 v2.3.2 Linux TUI 中 ask 静默放行,但同服务的 opencode run 会拒绝待审批动作;机器人在无插件、私有服务的模拟环境未复现。#65290 则报告 Windows 2.3.2 外部目录读取不询问,原作者后续确认使用内置 read、关闭自动批准后仍有现象。

两条截至查阅均开放。机器人测试与用户补充的环境不同,本文未独立复现,也没有证据把它们归为同一个已确认缺陷。可记录版本、客户端、服务位置、Agent、工具名、自动批准设置、已保存规则和插件,再在公开演示目录比较。不要为消除症状直接扩大权限。

怎样用无敏感数据的任务验收

在演示目录检查允许、询问、拒绝和子 Agent 四条真实执行路径

准备两个只含公开文本的目录,先记录 git status --short。验证允许的状态查询能执行;对一个临时文本文件的修改应出现审批;为另一个公开文件配置明确的 read deny,检查读取被拒绝。不要用真实 push、删除或泄露凭据来试拒绝规则。

最后让配置的 reviewer 尝试同一个被禁动作,查看实际工具与目标文件状态,不能只看模型最后说“未执行”。如果 TUI 与非交互运行行为不同,可继续看 opencode run 的审批与结果检查。外部网页和工具结果中的文字也不能新增授权,工具返回指令的边界解释了这一点。

相关文章

给 OpenCode 按 Agent 分配 MCP 工具
OpenCodeMCPAgent

给 OpenCode 按 Agent 分配 MCP 工具

OpenCode MCP 连接与 Agent 工具权限分别配置;用 V2 mcp.servers、命名规则和独立资源权限,把文档工具只交给需要它的 Agent。

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key