执行审批

执行审批

执行审批是配套应用 / 节点主机的护栏,用于让沙箱化的智能体在真实主机(gateway 或 node)上运行命令。只有当策略 + 允许列表 +(可选的)用户审批全部同意时,命令才会运行。执行审批叠加在工具策略与提权门控之上。Gateway 完整权限会话与符合条件的 elevated-full 路径可以跳过主机审批评估,参见官方文档中 strict inline-eval 例外一节。

关于 deny、allowlist、ask、auto、full 各模式的总览,见权限模式(官方)。

注意:除下述完整权限 Gateway 会话例外之外,生效策略取 tools.exec.* 与审批默认值中更严格的一方:审批只能收紧由配置推导的 security/ask,绝不会放宽。省略某个审批字段时使用 tools.exec 的值。主机执行还使用该机器上的本地审批状态——执行主机审批文档里的 ask: "always" 会持续提示,即使会话或配置默认值请求的是 ask: "on-miss"。未配置的 node 使用与 Gateway 相同的 full/off 基线。node 执行在派发前仍会检查目标策略:调用方 allowlist/off 会拒绝未匹配的命令,目标 ask: "always" 在调用方请求 full/off 时仍要求审批。

适用范围

执行审批在执行主机上本地强制执行:

  • Gateway 主机 → gateway 机器上的 openclaw 进程。
  • Node 主机 → 节点运行器(macOS 配套应用或无头节点主机)。

claude-cli 后端在 ask: "on-miss" 时也会按智能体的 exec 允许列表检查原生 Bash 命令。这在 Claude Code 负责执行期间为命令参数授权,不提供 OpenClaw 沙箱。匹配、提示与绑定限制见官方文档 Native Bash and the exec allowlist 一节。

信任模型

  • 经 Gateway 认证的调用者是该 Gateway 的受信操作员。
  • 配对的 node 把这份受信操作员能力扩展到 node 主机上。
  • 审批降低误执行风险,但不是按用户的认证边界或文件系统只读策略。
  • 命令获批后可以按所选主机或沙箱文件系统权限改写文件。
  • 获批的 node 主机运行绑定精确执行上下文:cwd、精确 argv、存在时的 env 绑定,以及适用时的可执行文件固定路径。
  • Gateway 审批背书的命令在审查前绑定每个已解析命令段的可执行文件,并在启动前复查。Node 主机在本地策略评估时捕获这些身份并在派发前复查。这不覆盖远端人工审批等待期间的内层 shell 可执行文件。受保护可执行文件仅使用解析后的真实路径身份;可写可执行文件还加内容哈希。绑定窗口内解析结果发生变化(包括 PATH 上出现新的可执行文件)会拒绝运行。仅身份绑定保留原本符合条件的 allow-always 决定。
  • 对 shell 脚本与直接以解释器/运行时调用文件的形式,OpenClaw 还会尝试绑定一个具体的本地文件操作数。若该文件在获批后、执行前发生变化,运行被拒绝而不是执行已漂移的内容。
  • 文件绑定是尽力而为,并非对每种解释器/运行时加载路径的完整建模。当无法唯一确定一个具体本地文件时,OpenClaw 拒绝为这次运行创建审批背书,而不是假装覆盖完整。

macOS 分工

OpenClaw 让原生 macOS 人工审批面板避开 Peekaboo 屏幕截图,并在审批待定(含菜单栏队列)期间拒绝原生电脑输入;人工审批控件保持可用。这些原生防护不覆盖浏览器自动化、独立的 CUA 驱动或同机第三方自动化。不要对你不信任的模型把 ask 模式 exec 与无限制电脑控制组合使用。这是加固,不是隔离边界。

  • node 主机服务通过本地 IPC 把 system.run 转发给 macOS 应用。
  • macOS 应用执行审批并在 UI 上下文中执行命令。

检查生效策略

命令显示内容
openclaw approvals get / --gateway / --node <id|name|ip>请求的策略、主机策略来源与生效结果。
openclaw exec-policy show终端工具策略与本地命令审批;加 --session <key> 预览会话工具。
openclaw exec-policy set / preset一步把本地请求策略与本地主机审批文档同步。

按会话的 /exec 覆盖不包含在内。在相应会话中运行 /exec 查看其当前默认值(见官方 Exec 文档的 session overrides 一节)。

工具可用性与命令审批是分离的:messaging 工具 profile 可以在审批允许命令的同时排除 exec 与 process。exec-policy show 离线解释本地排除项并标识策略来源;--session <key> 从已保存的会话设置预览工具。包含不保证可执行,缺失也不证明工具被禁用;在运行中验证执行,命令审批仍然适用。用 --agent <id> 选择智能体,--verbose 查看全部审批作用域。

完整 CLI 参考(标志、JSON 输出、允许列表增删)见 Approvals CLI。

当本地作用域请求 host=node 时,exec-policy show 在运行时把该作用域报告为 node 托管,而不是把本地审批文件当作事实来源。

如果配套应用 UI 不可用,任何正常情况下会提示的请求都由 ask fallback 解决(默认 deny)。

原生聊天审批客户端可以在待定审批消息上附加渠道专属快捷操作。Matrix 预置表情回应快捷方式(✅ 允许一次、♾️ 总是允许、❌ 拒绝),同时保留消息中的 /approve ... 作为后备。

对原生聊天审批界面,node exec 在发起该次工具调用内等待决定并在其中返回命令输出。关闭或取消该回合会使其待定授权失效,迟到的批准无法重启它。收到类型化的 SYSTEM_RUN_DENIED 结果表示 node 拒绝了执行,而不是命令可能已运行。

设置与存储

审批策略保存在执行主机上所选的共享状态数据库中。SQLite 时由 OPENCLAW_STATE_DIR 选择状态目录,否则使用默认 OpenClaw 状态目录:

$OPENCLAW_STATE_DIR/state/openclaw.sqlite#exec_approvals_config
# 否则
~/.openclaw/state/openclaw.sqlite#exec_approvals_config

#exec_approvals_config 后缀是单行记录的显示定位符,不是数据库文件名的一部分。选择 PostgreSQL 时该行位于所选 PostgreSQL 数据库中;本地 state/openclaw.sqlite 只是引擎锚点,不含审批策略。该行以下面展示的 JSON 文档作为权威值。

macOS 应用在两种引擎上都通过本地 OpenClaw CLI 提供的受限操作接口读写该策略。CLI 路由到运行中的共享状态属主,或在无属主运行时取得独占离线托管;绝不会从 Swift 直接打开共享数据库。保存策略需要携带最后观察到的哈希;过期保存会失败并要求重新加载。Gateway 与无头执行通过共享属主执行同一策略。

原生最终提交会在锁定写事务内按当前生效策略重新授权命令。保持命令被允许的策略编辑不会拒绝它;执行不要求策略哈希未变。

属主或 PostgreSQL 数据库不可用时,原生执行以 Exec policy unavailable 诊断拒绝。检查 openclaw gateway status 与所选数据库,或更新应用与 CLI。停止 Gateway 仅在所选数据库仍可达时允许离线策略操作。UI 中显示的策略快照仅供展示,不能授权执行。

socket 路径与认证令牌单独保存在所解析客户端状态根下的本地 client/credentials.sqlite,绝不进入共享策略行或其比较-交换哈希。默认审批 socket 跟随该本地根:$OPENCLAW_STATE_DIR/exec-approvals.sock,未设置该变量时为 ~/.openclaw/exec-approvals.sock。

原生策略切换不改变共享模式,也不迁移策略数据。更新或回滚时保持应用与本地 CLI 兼容。仍被接纳于 SQLite 的旧版应用读取同一共享策略行,但无法读取 PostgreSQL 策略。既有对已退役共享凭据访问的拒绝仍要求更新应用并运行对应 Doctor 修复。带着缺少属主操作的旧 CLI 或 Gateway 的新应用会以诊断拒绝执行。回滚需要兼容的应用、CLI 与策略格式;恢复旧策略快照会倒退权限,不属于回滚步骤。

状态目录是独立的信任域。当 OPENCLAW_STATE_DIR 指向别处时,OpenClaw 不会从默认状态目录导入或归档审批。为自定义状态目录单独配置审批。若活动状态目录仍含遗留 exec-approvals.json,停止 Gateway 并运行一次 openclaw doctor --fix 导入。Doctor 也只在遗留 plugin-binding-approvals.json 属于活动状态目录时导入它。

遗留允许列表条目的 lastUsedAt 或 lastUsedCommand 可能为 null。Doctor 在导入时把这两个使用字段视为缺失——即使配置仍需修复。这不会放松对当前策略的校验:其他畸形字段或冲突的遗留策略仍保留供操作员恢复,且在遗留文件解决前 exec 审批保持阻止。修复后用同一状态目录运行 openclaw approvals get 验证。

共享策略示例(socket 凭据由本地客户端属主持有):

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/path/to/**/bin/rg",
          "argPattern": "sha256:argv:...",
          "source": "allow-always",
          "lastUsedAt": 1737150000000,
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        },
        {
          "pattern": "~/path/to/**/bin/git"
        }
      ],
      "mcpTools": [
        {
          "server": "project-docs",
          "tool": "publish_page",
          "source": "allow-always",
          "addedAt": 1737150000000
        }
      ]
    }
  }
}

策略旋钮

tools.exec.mode

tools.exec.mode 是主机 exec 首选的归一化策略面:

值行为
deny阻止主机 exec。
allowlist仅运行允许列表中的命令,不提示。
ask使用允许列表策略,未命中时提示。
auto允许列表命中直接运行;对符合条件未命中者给出 allow(一次)、deny(原因返回给智能体)或 ask(人工审批)审查结论。
full不做普通策略提示地运行主机 exec;strict inline-eval 行为见下。

Doctor 会把受支持的遗留 tools.exec.security / tools.exec.ask 组合迁移为 tools.exec.mode。如果部署脚本、模板或配置生成器仍在发送旧字段,config patch 与 Gateway config.patch 会拒绝混合策略而不修改文件。在错误指名的同一 exec 对象里更新该来源,包括智能体覆盖的 agents.entries.<agentId>.tools.exec。存在精确等价时用建议的 mode 值替换 security/ask,例如 security: "full", ask: "off" 变为 mode: "full"。

不完整的组合在转换前需要显式选择意图策略。带 ask: "always" 的组合或 security: "full", ask: "on-miss" 没有精确的 mode 等价:保留两个遗留字段并从同一对象移除 mode 以维持其策略。替换对象时保留其他 exec 设置。对仍需迁移的已保存文件运行 openclaw doctor --fix;再次运行不会更新过期的部署源。

exec.security

security("deny" | "allowlist" | "full"):

  • deny —— 阻止全部主机 exec 请求。
  • allowlist —— 仅允许允许列表中的命令。
  • full —— 不要求允许列表匹配。不授予提权访问。

gateway/node 主机默认 full;sandbox 主机默认 deny。

exec.ask

ask("off" | "on-miss" | "always"):主机 exec 的已配置询问策略,控制来自 tools.exec.mode 与主机审批默认值的基础提示行为。默认 off。按调用的 ask 工具参数只能收紧该基线;渠道来源的模型调用在生效主机 ask 为 off 时忽略它。

  • off —— 无普通策略提示。单独启用的 strict inline-eval 检查仍可能要求审批。
  • on-miss —— 仅在允许列表未命中时提示。
  • always —— 每条命令都提示。生效 ask 为 always 时,allow-always 持久信任不会抑制提示。

askFallback

askFallback("deny" | "allowlist" | "full"):需要提示但无可达 UI(或提示超时)时的解决方式。省略时默认 deny。

  • deny —— 阻止。
  • allowlist —— 仅允许列表匹配时允许。
  • full —— 对活动 security 策略不加更严的后备限制。允许列表限制与显式审批要求(如识别出的 strict inline-eval 形式)仍然适用。

tools.exec.strictInlineEval

布尔值,默认 false。普通主机审批评估运行时,true 把识别出的内联代码求值形式视为仅审批——包括普通 full/off 策略或允许列表中的解释器二进制下。这是对无法干净映射到单一稳定文件操作数的解释器加载器的纵深防御。

strict 模式捕获的示例:python -c、node -e/--eval/-p、ruby -e、perl -e/-E、php -r、lua -e、osascript -e(以及 awk、sed、make、find -exec、xargs 的内联形式)。

在该审批路径上,这些命令需要审查者或显式审批。tools.exec.mode: "auto" 下,符合条件的命令收到 allow/deny/ask 结论。审查者可授予一次低/中风险执行、向智能体返回拒绝原因或转人工。Gateway 命令必须通过可变文件绑定检查,但不需要带固定路径的渲染命令即可进入审查。POSIX 登录或交互 shell 包装器跳过审查者并在绑定成功时要求人工审批,因为其隐式启动文件在操作数绑定之外。既有的绑定拒绝(含交互式代码加载形式)保持拒绝。到达审查者后备的 Codex app-server 命令审批会转人工,因为其审批请求不暴露可强制执行的已解析可执行文件。allow-always 不会为内联求值命令持久化新的允许列表条目。

仅配置 tools.exec.mode: "full" 不会绕过本设置。Gateway 上生效 security full 且 ask off 的完整权限会话跳过主机审批评估;exec 与主机审批策略都允许 full/off 时的获准 elevated-full 执行同样跳过。这些路径跳过 strict inline-eval 检测。对完整会话仅做 ask 收紧会恢复审批路径,同时保留其主机文件下限例外。

tools.exec.commandHighlighting

布尔值,默认 false。仅影响展示:启用后 OpenClaw 可附带解析器导出的命令片段,使 Web 审批提示能高亮命令 token。不改变 security、ask、允许列表匹配、strict inline-eval 行为、审批转发或命令执行。

全局设在 tools.exec.commandHighlighting,或按智能体设在 agents.entries.*.tools.exec.commandHighlighting。

YOLO 模式(免审批)

要在无审批提示下运行主机 exec,需要同时打开两层策略:OpenClaw 配置中的请求策略(tools.exec.*)和执行主机审批文档中的主机本地审批策略。

要在无提示下普通配置 full 模式执行识别出的内联求值形式,保持 tools.exec.strictInlineEval 未设置或为 false(默认)。若启用 strict 检测,askFallback: "full" 不能替代审查者或显式审批。上文所述的 Gateway 会话与 elevated 例外跳过该检测。

省略的 askFallback 默认 deny。当无 UI 的审批提示应回退为允许时,显式把主机 askFallback 设为 full。

层YOLO 设置
tools.exec.modegateway/node 上 full
主机 askFallbackfull

警告——重要区别:

  • tools.exec.host=auto 决定 exec 在哪里运行:有沙箱用沙箱,否则 gateway。
  • YOLO 决定主机 exec 如何被审批:security=full 加 ask=off。
  • YOLO 不会在已配置的主机 exec 策略之上新增启发式命令混淆审批门或脚本预检拒绝层。node 准备阶段仍读取目标策略并一次性解析工作目录。双侧都允许 full/off 且 strict inline eval 关闭时,普通路径别名与内联脚本不需要审批绑定。限制性策略与后续策略变更仍然生效。
  • auto 不让 node/gateway 路由成为来自沙箱会话的自由覆盖。仅当无沙箱运行时活动时,auto 才允许按调用的 host=node 与 host=gateway 请求。要稳定的非 auto 默认,显式设置 tools.exec.host 或使用 /exec host=...。

对 OpenClaw 托管的 Claude 会话,OpenClaw 以 default 权限模式启动 Claude Code。即便原始 Claude 后端参数请求 bypassPermissions,OpenClaw 的生效 exec 策略仍经由原生工具钩子与权限请求保持权威——包括 YOLO 与限制性策略。

想要更保守的配置,把 OpenClaw exec 策略收紧回 allowlist/on-miss 或 deny。

持久 gateway 主机"从不提示"配置

  1. 设置请求侧配置策略:
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.mode full
openclaw config set tools.exec.strictInlineEval false
openclaw gateway restart
  1. 匹配主机审批文档:
openclaw approvals set --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

本地快捷方式

openclaw exec-policy preset yolo

同时更新本地 tools.exec.host/security/ask 与本地审批文件默认值(含 askFallback: "full")。它有意只做本地,并要求独占离线托管所选状态。使用 exec-policy set 或 preset 前先通过服务属主停止运行中的 Gateway——当其他活 Gateway 拥有该状态时,这些命令在改变策略前拒绝。远程修改 gateway 主机或 node 主机审批用 openclaw approvals set --gateway 或 openclaw approvals set --node <id|name|ip>。

撤回权限的 Gateway 策略变更可能在某条 cron 命令正在启动时被拒绝。待命令启动稳定后重试;拒绝时原策略保持不变。

其他内置预设:cautious(host=gateway、security=allowlist、ask=on-miss、askFallback=deny)与 deny-all(host=gateway、security=deny、ask=off、askFallback=deny)。同样方式应用:openclaw exec-policy preset cautious。

要设置单个字段而非整套预设,用 openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> 并任选这些标志的子集。

Node 主机

在 node 上应用同一审批文档:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

仅限本地的限制:

  • openclaw exec-policy 不同步 node 审批。
  • openclaw exec-policy set --host node 被拒绝。
  • Node exec 审批在运行时从 node 获取。用 openclaw approvals get --node <id|name|ip> 查看、openclaw approvals set --node <id|name|ip> --file <path>(或 --stdin)替换;见 Approvals CLI。

会话与回合快捷方式

  • /exec security=full ask=off <task> 仅为当前消息请求该策略。任务须写进同一条消息;单独的指令不影响下一条消息。会话权限模式与主机策略仍可限制该请求。
  • /elevated full 是紧急通道快捷方式,仅当请求策略与主机审批文档都解析为 security: "full" 且 ask: "off" 时才跳过 exec 审批。更严的主机文件(如 ask: "always")仍会提示。

在完整权限 Gateway 会话例外之外,若主机审批文档比配置更严,更严的主机策略仍然胜出。

允许列表(按智能体)

允许列表按智能体配置。存在多个智能体时,在 macOS 应用中切换要编辑的智能体。模式为 glob 匹配。

模式可以是解析后的二进制路径 glob 或裸命令名 glob。裸名字只匹配经 PATH 调用的命令——rg 能在命令为 rg 时匹配 /opt/homebrew/bin/rg,但不匹配 ./rg 或 /tmp/rg。要信任特定二进制位置请用路径 glob。

仍使用遗留 agents.default 键或 commandText 字段的已保存策略在加载时不转换:OpenClaw 拒绝它们,直到 openclaw doctor --fix 把 agents.default 迁到 agents.main 并丢弃 commandText;openclaw update 运行同一 Doctor 流程。插件与操作员 API 仍接受遗留形状作为输入并在保存前归一化。见官方 Doctor 文档的 exec approval policy 迁移。echo ok && pwd 这类 shell 链仍需每个顶层段都满足允许列表规则。

示例:

  • rg
  • ~/path/to/**/bin/peekaboo
  • ~/.local/bin/*
  • /opt/homebrew/bin/rg

用 argPattern 限制参数

当允许列表条目要同时匹配二进制与特定参数形态时添加 argPattern。OpenClaw 在所有主机上使用 ECMAScript(JavaScript)正则语义,并把表达式作用于解析后的命令参数(不含可执行 token argv[0])。手写条目的参数以单个空格连接,需要精确匹配时请锚定模式。

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

该条目允许 python3 safe.py;python3 other.py 是允许列表未命中。若同一二进制还存在仅路径条目,未匹配的参数仍可回退到该仅路径条目。要把二进制限制为声明的参数时应省略仅路径条目。

审批流程保存的条目使用内部分隔符格式做精确 argv 匹配。请优先用 UI 或审批流程重新生成这些条目,而不是手改编码值。OpenClaw 无法解析某命令段的 argv 时,带 argPattern 的条目不匹配。

生成的 allow-always 条目同时绑定精确 argv 与批准时的工作目录。选择 Always allow here 只在该目录授权同一命令;在其他目录运行是允许列表未命中。

2026.8.1 之前保存的生成条目不绑定目录,升级后失效。openclaw update 会在其自动 Doctor 流程中移除它们,也可自行运行 openclaw doctor --fix。重跑受影响的工作流并选择 Always allow here 创建替代条目。手动允许列表规则不变;手动仅路径规则省略 source 与 argPattern。

每个允许列表条目支持:

字段含义
pattern解析后的二进制路径 glob 或裸命令名 glob
argPatternECMAScript argv 正则或生成的精确 argv 哈希;省略即仅路径
id稳定不透明 ID;缺失时生成 UUID
source生成条目来源(如 allow-always);手动条目省略
commandText遗留纯文本输入;已保存条目需 openclaw doctor --fix
lastUsedAt最后使用时间戳
lastUsedCommand最后匹配的命令;生成的哈希 argv 条目省略
lastResolvedPath最后解析的二进制路径

MCP 工具授权

对 Gateway 托管的 Codex 运行,Allow Always 可以为 mcp.servers 中配置的一个服务器上的单个 MCP 工具保存持久授权。Gateway 把授权写入同一审批文档的 agents.<agentId>.mcpTools。它覆盖精确的智能体、已配置服务器名与工具名,连同任意参数;不授予其他智能体、服务器或工具访问。

每个条目含 server、tool、source: "allow-always" 与 addedAt(Unix 毫秒);lastUsedAt 可选。Codex 应用、原生插件服务器与电脑控制服务器不接收 OpenClaw MCP 工具授权。OpenClaw 只在提供持久化且能无歧义地把审批关联到活跃 Gateway 拥有的工具调用时创建授权;缺失或歧义关联时保留 Codex 既有原生/会话行为。

服务器 codex.defaultToolsApprovalMode 为 auto 或未指定时授权生效。显式 prompt 胜过已存授权并继续询问;显式 approve 本就绕过按调用审批。见官方 MCP 文档的 Codex tool approvals。

持久授权在 OpenClaw 下一次准备 Codex 线程配置与钩子注册时读取(如新会话或重启后);当前会话继续使用 Codex 记住的决定。OpenClaw 不会为每次工具调用重载授权。

查看授权运行 openclaw approvals get --gateway。撤销一个:导出文档、从 agents.<agentId>.mcpTools 移除该条目、用既有 set 命令替换:

openclaw approvals get --gateway --json | jq '.file' > approvals.json
# 编辑 approvals.json,保留其他设置、允许列表与授权。
openclaw approvals set --gateway --file approvals.json

编辑本地审批时从两条命令中去掉 --gateway。撤销同样在下一次线程准备/注册时生效;开启新会话或重启以丢弃活动会话记住的审批。若 Codex 也在其原生配置中单独持久化了审批,请一并移除该原生授权。

自动化的常设授权

Gateway 托管自动化(cron)运行产生的审批只投递给已连接的 exec 审批客户端:Control UI、macOS/iOS/Android 应用,以及声明 approvals 或 exec-approvals 能力的 API 客户端。TUI 不渲染 exec 审批卡片;聊天渠道从不接收自动化审批(否则每次出现都会重复一张卡)。有审查界面连接时,计划运行像交互运行一样等待决定。自动化任务同一时刻只允许一次待定运行(single-flight),每个任务同时至多一张卡待定。无审批界面连接时请求立即被拒绝,运行的错误会解释策略修复方式。Node 主机自动化 exec 保持完全无头策略(无卡片),直到 node 执行获得自己的常设授权路径。

当审批来自自动化的隔离运行时,用 Always allow 解决不会写入 JSON 允许列表条目,而是由 Gateway 创建一个作用域常设授权,绑定该精确智能体、自动化、任务配置与操作(命令文本、工作目录、请求的环境)。此后同一任务的同一操作在授权有效期内不再提示。审批卡会预先说明:自动化审批带有一行作用域描述,说明 Always allow 将授予什么。

卡片与台账预览截断净化文本时不会切开 UTF-16 代理对;这些显示限制不缩短用于绑定与匹配授权的命令、工作目录或环境。

授权覆盖什么、何时停止

任务被删除或实质定义变化时授权被拒绝并要求普通提示——即使后续编辑恢复了早先定义也一样。暂停并重新启用未变化的自动化保留授权。命令、工作目录或环境相差哪怕一个字节、授权被撤销或过期、原始审批记录消失时,授权停止匹配。每次使用都检查当前授权与审批行。一次使用提交后只授权该次启动;撤销或任务编辑可能与已检查的启动竞争。运行存活与主机策略仍在进程拉起前立即检查。可变文件操作数与需要显式审查的命令(heredoc、strict inline eval、审计抑制)保持逐次提示。非自动化审批不变。

授权生命周期

默认授权直到撤销——与产品中其他地方 Always allow 的含义相同。条款在创建时冻结,从不回溯变更:

  • tools.exec.grantExpiryDays(默认未设置)为未来授权设置默认天数期限。既有授权保留创建时的条款;提前退役用撤销。这是面向需要周期性重审批的批量受管部署的策略设置。
  • 解决界面可用 approval.resolve / exec.approval.resolve 的 grantExpiresInDays 字段或 openclaw approvals resolve <id> allow-always --expires-in-days <n> 按次覆盖;覆盖胜过配置默认。
  • 过期授权回退为提示,并在系统时机合适时被清理。

列出与撤销

每个常设授权可见且可撤销:

  • Control UI:Settings → Approvals 显示常设授权台账——自动化、精确命令、使用次数与状态(直到撤销/N 天后过期、已过期、已撤销)——每行活动条目带 Revoke 操作。
  • CLI:openclaw approvals grants list 渲染同一台账;openclaw approvals grants revoke <grant-id> 撤销一个授权。重复撤销无额外效果。它阻止后续授权消费(重新提示);已消费的使用仍可能启动。
  • 删除或实质编辑自动化、或撤销创建它的那次审批,同样使授权失效而不触碰授权界面;暂停并重新启用未变化的自动化不会。

创建它的 operator_approvals 行始终是唯一授权属主:授权是派生关联,每次使用都对照活动审批行、自动化行与撤销状态重新验证。

自动允许 skill CLI

启用 Auto-allow skill CLIs(autoAllowSkills)后,已知 skills 引用的可执行文件在节点(macOS 节点或无头节点主机)上视为已列入允许列表。这经 Gateway RPC 的 skills.bins 获取 skill 二进制列表。要严格手动允许列表请禁用。

skill 信任属于提供它的 Gateway。切换 Gateway 会退役先前缓存,包括 Mac 应用的受信二进制列表与仍在进行的审批检查。刷新失败可保留同一 Gateway 的最后已知信任;不能导入其他 Gateway 的信任。

所选 Gateway 连接时,Mac 的 Exec Approvals 面板刷新受信二进制与智能体选择。本地策略、所选作用域与未完成的允许列表编辑留在 Mac 上。

警告:

  • 这是隐式便利允许列表,独立于手动路径允许列表条目。
  • 面向 Gateway 与 node 处于同一信任边界的受信操作员环境。
  • 需要严格显式信任时保持 autoAllowSkills: false 并只用手动路径允许列表条目。

安全二进制与审批转发

安全二进制(仅 stdin 快速通道)、解释器绑定细节,以及把审批提示转发到 Slack/Discord/Telegram(或作为原生审批客户端运行),见 Exec approvals 进阶(官方)。

Control UI 编辑

用 Control UI → Devices → Command approvals 卡片编辑默认值、按智能体覆盖与允许列表。选择作用域(Defaults 或某智能体),调整策略,增删允许列表模式后 Save。UI 显示每个模式的最后使用元数据,便于保持列表整洁。

目标选择器选 Gateway(本地审批)或 Node。节点须通告 system.execApprovals.get/set(macOS 应用或无头节点主机);请求继续经 exec.approvals.node.get/set 路由到所选 node。节点尚未通告 exec 审批时,在该主机本地使用属主背书的 openclaw approvals 命令。

部分 node 主机(含 Windows 配套应用)拥有不同的审批策略格式,Control UI 对这些主机原生策略只读。用配套应用或 openclaw approvals set --node <id|name|ip> 按原生策略形状编辑。见 Approvals CLI。

审批流程

需要提示时,gateway 向操作员客户端广播 exec.approval.requested。Control UI 与 macOS 应用经 exec.approval.resolve 处理,gateway 再把已批准的请求转发给 node 主机。

在其提示截止前被接受的审批在 Gateway 的活动移交窗口内保持有效;派发期间越过提示截止不撤销该决定。已关闭的运行、过期的移交窗口与被复用的 Allow Once 审批仍拒绝执行。

记录或消费一个 Allow Once 审批、以及为通知读取它,都不改变 exec 策略;这些操作不阻塞已批准命令的最终策略检查。待定中的策略编辑与持久 MCP 工具授权仍会在生效前拦截执行,命令必须在启动前一刻通过当前策略。

macOS 审批面板保持普通命令紧凑,提供的智能体与主机合入一条摘要;工作目录显示在完整换行命令下方,更长命令可滚动。展开 Details 检查可执行文件路径;目录与可执行文件路径保持全选。Copy 复制显示的命令,含控制字符与不可见字符的可见转义。主机来自请求;显示面板的 Mac 可以远离该 gateway 或 node。

选择 Allow Once 或按 Command-Return 批准一次执行;单独 Return 不批准。Escape 关闭面板,在 Don’t Allow 可用时拒绝请求,否则无决定关闭。仅当请求策略允许持久审批时出现 Always Allow Here。

原生执行前,共享属主检查当前策略,并把决定连同任何 allow-always 授权与使用更新一并提交。提示打开期间的策略撤销、智能体删除拦截或提交失败都会拒绝执行。提交返回后,应用检查原 socket 请求仍存活,并在拉起进程前复查绑定的可执行文件与工作目录。取消或断开请求不能经由迟到批准复活。没有数据库事务跨越 IPC 等待。

host=node 时,审批请求携带预准备的 systemRunPlan 载荷。gateway 转发已批准的 system.run 请求时以该计划作为权威命令/cwd/会话上下文:

  • node exec 路径预先准备一份计划。
  • 审批记录存储该计划及其绑定元数据。
  • 获批后,最终转发的 system.run 复用已存计划,而不是信任调用方后续编辑。
  • 审批请求创建后对 command、rawCommand、cwd、agentId、sessionKey 的编辑被丢弃:gateway 转发已存值。变更的 env 覆盖仍作为审批不匹配被拒绝。

审批作用域摘要

审批属主可以附加类型化、仅供展示的作用域,描述动作影响哪些人或资源。OpenClaw 在渠道审批卡上渲染净化后的摘要,并把有界作用域纳入 Control UI 客户端可用的安全审批展示。独立审批链接在决定按钮前显示所供作用域,包括自动化授权条款。作用域从不授予授权或改变审批策略。

  • message-send:目的地、收件人数、可选收件人预览,以及受众是内部还是外部。
  • payment:精确十进制金额、币种与收款方或支付系统。
  • external-post:目的地与帖子是公开还是受限。

例如邮件审批可能显示 Send to 3 recipients via email (external): [email protected], [email protected], +1 more。这些事实由属主提供,渠道绝不从命令或消息文本推断。无声明作用域时审批卡渲染与从前完全一致。

系统事件与拒绝

审批可投递时,普通智能体运行等待决定并在同一回合收到 exec 结果;最终回复走原始投递路径,包括入站 A2A 任务。操作员拒绝返回被拒绝的工具结果而不运行命令。

显式使用异步执行的诊断与导出命令保留单独的后续投递。对这些工作流:exec 生命周期在 node 报告完成后向智能体会话发布 Exec finished 系统消息;审批通过后经 tools.exec.approvalRunningNoticeMs(默认 10000,0 禁用)OpenClaw 还可发出进行中通知。被拒的 exec 审批对该主机命令是终态:命令不运行。

  • 对带来源会话的主智能体异步审批,OpenClaw 把拒绝作为内部后续投回该会话,使智能体停止等待异步命令并避免缺失结果修复。
  • 无会话或会话无法恢复时,OpenClaw 仍可向操作员或直接聊天路由报告简短拒绝。
  • 子代理与 cron 会话的拒绝不投回该会话。

Gateway 主机 exec 审批复用审批 id 关联待定请求与其完成/拒绝消息(Exec finished (gateway id=...) / Exec denied (gateway id=...))。

影响

  • full 权限很大,尽量优先允许列表。
  • ask 让你保持知情,同时仍允许快速审批。
  • 按智能体的允许列表防止一个智能体的审批泄漏到其他智能体。
  • 审批只适用于来自授权发送者的主机执行请求;未授权发送者无法发出 /exec。
  • /exec security=full <task> 是授权操作员的当前回合请求,受生效会话与主机策略约束。要硬性阻止 exec,请经工具策略拒绝 exec 工具。完整访问会话对主机审批下限的例外见官方 Exec 文档的 session overrides。

相关页面

译注:本页对应官方文档 Exec approvals,按 2026-11-06 检出的官方仓库固定快照逐节核对重写(官方该页自本站旧译后有大规模扩充:存储改为共享状态数据库、新增 tools.exec.mode、strictInlineEval、MCP 工具授权、自动化常设授权等);正式发布前字段与默认值应以官方最新文档复核。