权限请求
插件权限请求¶
插件权限请求允许插件代码将工具调用或插件拥有的操作暂停,直到用户批准或拒绝为止。它们使用 Gateway 的 plugin.approval.* 流程,以及与处理聊天批准按钮和 /approve 命令相同的批准 UI 界面。
将插件权限请求用于插件/应用权限。它们不能替代主机 exec 批准、可选工具允许列表或 Codex 的原生权限审查。
选择正确的门控¶
选择与您所需的决策点相匹配的门控:
| 门控 | 使用场景 | 控制内容 |
|---|---|---|
| 可选工具 | 工具在用户选择加入之前不应显示给模型。 | 通过 tools.allow 控制工具可见性。 |
| 插件权限请求 | 插件钩子或插件拥有的操作必须在单个操作运行前请求许可。 | 通过 plugin.approval.* 进行运行时批准。 |
| Exec 批准 | 主机命令或类似 shell 的工具需要操作员批准。 | 主机 exec 策略和持久化 exec 允许列表。 |
| Codex 原生权限请求 | Codex 在原生 shell、文件、MCP 或应用服务器操作之前请求许可。 | Codex 应用服务器或原生钩子批准处理,当 OpenClaw 拥有提示词时,通过插件批准路由。 |
| MCP 批准征询 | Codex MCP 服务器为工具调用请求批准。 | 通过 OpenClaw 插件批准桥接 MCP 批准响应。 |
可选工具是发现时门控。插件权限请求是每次调用时门控。当敏感工具需要模型在可见之前明确选择加入、并在操作运行前获得批准时,应同时使用两者。
在工具调用前请求批准¶
大多数由插件编写的提示词应在 before_tool_call 钩子中启动。该钩子在模型选择工具之后、OpenClaw 执行之前运行:
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
export default definePluginEntry({
id: "deploy-policy",
name: "Deploy Policy",
register(api) {
api.on("before_tool_call", async (event) => {
if (event.toolName !== "deploy_service") {
return;
}
const environment =
typeof event.params.environment === "string" ? event.params.environment : "unknown";
return {
requireApproval: {
title: "Deploy service",
description: `Deploy service to ${environment}.`,
severity: environment === "production" ? "critical" : "warning",
allowedDecisions:
environment === "production"
? ["allow-once", "deny"]
: ["allow-once", "allow-always", "deny"],
timeoutMs: 120_000,
onResolution(decision) {
console.log(`deploy approval resolved: ${decision}`);
},
},
};
});
},
});
为将要批准操作的人员编写提示文本:
- 保持
title简短且以操作为中心。Gateway 将其限制为 80 个字符。 - 保持
description具体且有边界。Gateway 将其限制为 512 个字符。 - 包含操作、目标和风险。不要包含不应出现在聊天批准界面中的密钥、令牌或私有负载。
severity在省略时默认为"warning"。仅对错误决策可能导致生产环境损坏或数据丢失的操作使用"critical"。allowedDecisions在省略时默认为["allow-once", "allow-always", "deny"]。当持久信任对该操作不安全时,传入["allow-once", "deny"]。timeoutMs默认为 120000(2 分钟),并且无论请求的值是多少,都被限制在 600000(10 分钟)以内。
声明批准作用域¶
当您的插件了解操作的后果时,设置 requireApproval.scope。作用域是类型化的、可选的,并且仅用于显示:它帮助审查者理解操作,但从不授予权限或改变批准决策。声明批准的插件提供这些事实。频道永远不会从命令、标题或消息文本中推断作用域。
对于发送给三位外部收件人的电子邮件,请包含目标、收件人总数、可选的预览和受众:
requireApproval: {
title: "Send customer update",
scope: {
kind: "message-send",
target: "email",
recipientCount: 3,
recipients: ["alice@example.com", "bob@example.com"],
audience: "external",
},
}
对于付款,请提供精确的十进制金额字符串、其货币以及收款人或支付系统:
requireApproval: {
title: "Pay invoice",
scope: {
kind: "payment",
amount: "49.99",
currency: "EUR",
target: "Stripe",
},
}
对于外部帖子,请标识其目标并声明其可见性:
requireApproval: {
title: "Publish announcement",
scope: {
kind: "external-post",
target: "github",
visibility: "public",
},
}
消息受众可以是 internal 或 external。外部帖子的可见性可以是 public 或 restricted。收件人预览最多包含五个身份标识。所有字符串在显示前都会经过清理和长度限制:目标和收件人身份限制为 128 个字符,付款金额为 40 个,货币为 12 个。如果清理后超出限制,OpenClaw 会省略作用域,同时保留正常的批准提示。
决策行为¶
OpenClaw 会创建一个带有 plugin: ID 的待审批项,将其投递到可用的审批界面,并等待决策。
| 决策 | 结果 |
|---|---|
allow-once |
当前调用继续执行。 |
allow-always |
当前调用继续执行,并且决策会传递给插件。 |
deny |
该调用会被阻止,并返回一个已拒绝的工具结果。 |
| 超时 | 该调用会被阻止。 |
| 取消 | 当运行被中止时,该调用会被阻止。 |
| 无审批路由 | 由于没有已连接的审批界面可以解决它,该调用会被阻止。 |
只有请求所允许的精确 allow-once 和 allow-always 决策才允许执行。未知、格式错误、不匹配、缺失以及超时的决策都会失败关闭。
allow-always 仅当请求方插件或运行时实现了该持久化时才会持久生效。对于普通的 before_tool_call.requireApproval 钩子,OpenClaw 将 allow-once 和 allow-always 视为当前调用的审批决策,并将解析后的值传递给 onResolution。如果你的插件提供 allow-always,请准确记录并实现它所信任的未来调用范围。
如果钩子还返回 params,OpenClaw 会在请求审批时对基础参数和这些覆盖项进行快照,并且仅在审批成功后应用这些覆盖项。较低优先级的钩子仍然可以阻止执行,但不能重写待审批所覆盖的参数。
allowedDecisions 限制向用户显示的按钮和命令。Gateway 会拒绝针对请求未提供的任何决策的解决尝试。
路由审批提示¶
审批提示可以在本地 UI 界面或支持审批处理的聊天频道中解决。要将插件审批提示转发到明确的聊天目标,请配置 approvals.plugin:
{
approvals: {
plugin: {
enabled: true,
mode: "targets",
agentFilter: ["main"],
targets: [{ channel: "slack", to: "U12345678" }],
},
},
}
approvals.plugin 独立于 approvals.exec。启用 exec 审批转发不会路由插件审批提示,启用插件审批转发也不会更改主机 exec 策略。
对于 Slack 决策,approvals.plugin.slack 可以在不更改机器人消息访问列表的情况下限制审核者。默认 approvers 列表适用于所有插件审批。plugins 条目会为某个选定的原生工具插件覆盖该列表。工具条目会为某个精确工具覆盖该插件的列表:
{
approvals: {
plugin: {
slack: {
approvers: ["team:T12345678:user:U12345678"],
plugins: {
"catalog-tools": {
approvers: ["team:T12345678:user:U23456789"],
tools: {
"create%20issue": {
approvers: ["team:T12345678:user:U34567890"],
},
},
},
},
},
},
},
}
对于原生 OpenClaw 工具,请使用工具注册中的插件 ID,以及工具键 encodeURIComponent(rawToolName)。只有精确匹配的列表会生效:先工具,再插件,最后默认。Slack 审核者接受所选 Slack 账户内的原始 U…/W… 用户 ID,或如上所示的工作区限定 ID。决策绑定到机器人已认证的工作区;来自其他工作区的限定审核者不会收到审批 DM。显式空列表会拒绝该层级的 Slack 决策。如果省略默认 approvers 字段,具有已知选定所有者且没有匹配覆盖项的请求将保留现有 Slack 账户的 allowFrom 或 defaultTo 授权。当存在插件覆盖项时,缺少选定所有者会拒绝 Slack 决策。这些列表授权 Slack 卡片按钮和 /approve,而已认证的 Gateway 审批客户端仍使用其自身的作用域。即使没有普通机器人 DM 访问权限,卡片按钮对列表中的审核者也可用;键入的 /approve 仍需要该访问权限。即使审核者无法读取源 DM 或私有频道,工具卡片也可以显示插件提供的请求标题和描述;选择审核者时应考虑该可见性。工具覆盖项要求精确匹配所选工具;当该标识不可用时,请求不能继承更广泛的审核者列表。有效的非空审核者列表会为该请求启用原生 Slack 投递,独立于原生 exec 审批和插件转发。原生工具列表仅在策略或钩子请求对该工具进行审批时适用;设置审核者本身不会触发审批提示。当选择 Slack 审核者列表时,Slack 仅通过原生审核者 DM 投递卡片。通用的 approvals.plugin.targets Slack 转发无法强制该收件人列表,即使目标指定了某个审核者。如果原生 Slack 处理器不可用,通用转发不会发送卡片;请连接机器人或支持审批的 Gateway 客户端并重试。
审核者列表会在路由新请求时检查,并在接受审批决策时再次检查。更改列表不会撤回现有卡片,也不会取消已排队等待投递的消息。前审核者可能仍能看到此类卡片,但在失去访问权限后无法批准它。已过期或已取消请求的卡片不能授权任何操作。
当提示包含手动审批文本时,请使用所提供的决策之一来解决它:
参见 高级 exec 审批,了解完整的转发模型、同一聊天中的审批行为、原生频道投递以及特定频道的审核者规则。
Codex 原生权限¶
Codex 原生权限提示也可以经由插件审批传递,但 它们的归属与插件编写的钩子不同。
- Codex app-server 审批请求在 Codex 审查后通过 OpenClaw 路由。
- 当该中继启用时,原生钩子
permission_request中继可以通过plugin.approval.request发起询问。 - 当 Codex 将
_meta.codex_approval_kind标记为"mcp_tool_call"时,MCP 工具审批请求会经由插件审批路由。
请参阅 Codex 测试运行时 以了解 Codex 特定行为和回退规则。
故障排查¶
工具提示插件审批不可用。 没有审批 UI 或已配置的审批路由接受该请求。连接支持审批的客户端,使用支持同一聊天中 /approve 的通道,或配置 approvals.plugin。
allow-always 出现,但下一次调用再次提示。 通用插件审批流程不会自动为任意钩子持久化信任。在 onResolution("allow-always") 之后,在你的插件中持久化插件拥有的信任,或仅提供 allow-once 和 deny。
/approve 拒绝该决策。 该请求限制了 allowedDecisions。请使用提示中打印的其中一个决策。
Discord、Matrix、Slack 或 Telegram 提示的路由方式与 exec 审批不同。 插件审批和 exec 审批使用独立的配置,并可能使用不同的授权检查。请验证 approvals.plugin 以及通道的插件审批支持,而不是仅检查 approvals.exec。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw