plugin.approval.* 流程,以及处理聊天批准按钮和
/approve 命令的相同批准 UI 表面。
将插件权限请求用于插件/应用权限。它们不能替代
宿主 exec 批准、可选工具允许列表,或 Codex 的原生权限
审查。
选择合适的闸门
选择与你需要的决策点相匹配的闸门:
可选工具是发现阶段的闸门。插件权限请求是按调用次数的闸门。若某个敏感工具在模型看到它之前就必须明确选择加入,并且在动作运行前还必须批准,则两者都使用。
在工具调用前请求批准
大多数插件编写的提示都应该从before_tool_call hook 开始。该 hook
在模型选择工具之后、OpenClaw 执行它之前运行:
- 保持
title简短且以动作为中心;Gateway 将其上限设为 80 个字符。 - 保持
description具体且有边界;Gateway 将其上限设为 512 个字符。 - 包含动作、目标和风险。不要包含不应出现在聊天审批界面中的密钥、令牌或 私有载荷。
- 当省略
severity时,默认为"warning"。仅对那些错误决策可能导致生产损害或数据丢失的 动作使用"critical"。 - 当省略
allowedDecisions时,默认为["allow-once", "allow-always", "deny"]。 对于持久信任对该动作不安全的情况,传入["allow-once", "deny"]。 timeoutMs默认为 120000(2 分钟),并且无论请求的值是多少,都会被限制为 600000(10 分钟)。
决策行为
OpenClaw 会创建一个带有plugin: ID 的待批准项,将其发送到
可用的批准界面,并等待决策。
只有请求明确允许的
allow-once 和 allow-always 决策才会允许执行。未知、格式错误、不匹配、缺失以及超时的决策都会以关闭方式失败。为兼容插件,旧的 timeoutBehavior 字段仍然被接受,但已弃用且会被忽略;不要在新的 hook 中设置它。
只有当请求插件或运行时实现了该持久化时,allow-always 才会真正持久化。对于普通的 before_tool_call.requireApproval hooks,OpenClaw 会将 allow-once 和 allow-always 视为当前调用的批准决策,并将解析后的值传递给 onResolution。如果你的插件提供 allow-always,请明确记录并实现它对未来哪些调用可信。
如果 hook 还返回 params,OpenClaw 会在请求批准时保存基础参数及其覆盖值,然后仅在批准成功后应用这些覆盖值。优先级较低的 hook 仍然可以阻止调用,但无法重写待批准项所涵盖的参数。
allowedDecisions 会限制展示给用户的按钮和命令。对于请求未提供的任何决策,
Gateway 都会拒绝解析尝试。
路由批准提示
批准提示可以在本地 UI 界面中解析,也可以在支持批准处理的聊天渠道中解析。 要将插件批准提示转发到显式聊天目标,请配置approvals.plugin:
approvals.plugin 与 approvals.exec 相互独立。启用 exec 批准
转发不会路由插件批准提示,启用插件批准转发也不会改变宿主 exec 策略。
当提示包含手动批准文本时,请使用其中一个提供的决策进行解析:
Codex 原生权限
Codex 原生权限提示也可以通过插件批准流转,但它们与 插件编写的 hooks 拥有不同的所有权。- Codex app-server 批准请求会在 Codex 审查后通过 OpenClaw 路由。
- 原生 hook
permission_request转发可在启用该转发时通过plugin.approval.request发起询问。 - 当 Codex 将
_meta.codex_approval_kind标记为"mcp_tool_call"时, MCP 工具批准引发请求会通过插件批准路由。
故障排查
工具提示插件批准不可用。 没有批准 UI 或已配置的 批准路由接受该请求。连接一个支持批准的客户端,使用支持同一聊天/approve 的渠道,或配置 approvals.plugin。
allow-always 出现了,但下一次调用又再次提示。 通用插件
批准流程不会自动为任意 hooks 持久化信任。请在你的插件中于
onResolution("allow-always") 后持久化插件拥有的信任,或者
只提供 allow-once 和 deny。
/approve 拒绝该决策。 该请求限制了
allowedDecisions。请使用提示中打印出的决策之一。
Discord、Matrix、Slack 或 Telegram 的提示路由与 exec
批准不同。 插件批准和 exec 批准使用的是不同的配置,且可能采用不同的授权检查。请验证
approvals.plugin 以及该频道对插件批准的支持,而不要只检查 approvals.exec。