跳转至

权限请求

插件权限请求

插件权限请求允许插件代码将工具调用或插件拥有的操作暂停,直到用户批准或拒绝为止。它们使用 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 客户端并重试。

审核者列表会在路由新请求时检查,并在接受审批决策时再次检查。更改列表不会撤回现有卡片,也不会取消已排队等待投递的消息。前审核者可能仍能看到此类卡片,但在失去访问权限后无法批准它。已过期或已取消请求的卡片不能授权任何操作。

当提示包含手动审批文本时,请使用所提供的决策之一来解决它:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

参见 高级 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