配对

“配对”是 OpenClaw 的显式访问审批步骤。 它用于两个地方：

1. DM 配对（谁被允许与机器人对话）
2. 节点配对（哪些设备/节点被允许加入网关网络）

安全上下文：安全

1) DM 配对（入站聊天访问）¶

DM 配对适用于实现了 OpenClaw 配对 API 的渠道。当 DM 策略为 pairing 时，未知发送者会收到一个短代码，并且其消息在你批准之前不会被处理。

默认 DM 策略记录在：安全

dmPolicy: "open" 仅当有效 DM 允许列表包含 "*" 时才公开。 设置和验证要求公开开放配置使用该通配符。如果现有状态包含带有具体 allowFrom 条目的 open，运行时仍只允许这些发送者，并且配对存储中的批准不会扩大 open 访问权限。

配对代码：

• 8 个字符，大写，不含易混淆字符（0O1I）。
• 1 小时后过期。机器人只在新请求创建时发送配对消息（大致每个发送者每小时一次）。
• 待处理的 DM 配对请求上限为每个渠道账户 3 个；额外请求会被忽略，直到其中一个过期或被批准。

从 Control UI 批准¶

打开 设置 → 渠道 → DM 访问请求。队列会合并所有已配置且 DM 策略为 pairing 的渠道账户中的待处理请求。 按渠道或账户筛选，查看发送者 ID 和元数据，然后选择 批准。

批准仅授予直接消息访问权限。它不会授予群组访问权限。当受支持时，批准对话框还提供以下显式选项：

• 批准后通知请求者
• 同时将此发送者设为首个命令所有者，仅当不存在命令所有者且 Control UI 会话具有 operator.admin 时显示

选择 忽略 可在不批准的情况下移除待处理请求。忽略不是永久阻止；发送者之后可以再次请求访问。

从 CLI 批准¶

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

添加 --notify 以在同一渠道上通知请求者。多账户渠道使用 --account <id>。

与 Control UI 的显式复选框不同，CLI 会在未配置命令所有者时自动初始化 commands.ownerAllowFrom，使用类似 telegram:123456789 的条目。这为首次设置提供了一个显式所有者，用于特权命令和执行审批提示。在存在所有者之后，后续的配对批准仅授予 DM 访问权限；它们不会添加更多所有者。

手动加入允许列表的发送者不会自动成为命令所有者。如果已授权的发送者没有所有者访问权限，仅限所有者的命令会回复确切的 openclaw config set commands.ownerAllowFrom 命令，供操作员运行。

在不使用 DM 配对的情况下设置所有者¶

运行 openclaw channels add 并完成渠道设置。当不存在命令所有者时，向导会单独提供 设置我的操作员账户，与聊天访问权限分开。输入你的个人用户 ID，并确认可以管理此安装的准确账户。暂时跳过 会保持所有权不变。

这也适用于 Discord 服务器和其他已禁用 DM 的群组渠道。所有者可以使用 /update、重启 Gateway、更改配置并批准命令。所有权不会授予聊天访问权限：现有渠道和群组访问规则仍然适用。向导绝不会自动提升聊天允许列表或替换现有所有者。

支持的渠道包括：discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, signal, slack, sms, synology-chat, telegram, twitch, whatsapp, zalo, zalouser。

已安装的外部插件如果实现了 OpenClaw 的配对 API，也可以支持 DM 配对。请查看插件文档了解特定版本的限制。

可复用的发送者组¶

当同一组受信任的发送者需要应用于多个消息渠道，或同时应用于 DM 和群组允许列表时，使用顶层 accessGroups。

静态组使用 type: "message.senders"，并从渠道允许列表中通过 accessGroup:<name> 引用：

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}

访问组在此处有详细说明：访问组

状态存储位置¶

对于使用 OpenClaw 配对 API 的渠道，状态存储在共享 SQLite 数据库 ~/.openclaw/state/openclaw.sqlite 中：

• 待处理请求位于 channel_pairing_requests
• 已批准的发送者位于 channel_pairing_allow_entries

账户范围行为：

• 每个请求和已批准的发送者都以渠道和账户作为键
• 使用配对 API 的渠道只读取规范的 SQLite 行；它们不会合并旧版文件

旧版网关会在 ~/.openclaw/credentials/ 下写入 <channel>-pairing.json 和 <channel>-<accountId>-allowFrom.json。 openclaw doctor --fix 会将这些文件导入 SQLite，并在成功导入后删除每个源文件。正常 Gateway 启动会保持这些旧版文件不变。由于这些行控制对你助手的访问，请将 SQLite 数据库视为敏感数据。

2) 节点设备配对（iOS/Android/macOS/无头节点）¶

节点以 role: node 的设备身份连接到 Gateway。Gateway 会创建设备配对请求，该请求必须被批准。

从 Control UI 配对（推荐）¶

使用一个已连接且具有 operator.admin 访问权限的 Control UI 会话：

1. 打开 Control UI，进入 设置 → 设备。
2. 在 设备 页面，点击 配对设备。
3. 保持 完全访问（推荐），或选择 受限访问 以省略管理 Gateway 控制。
4. 点击 创建设置代码。
5. 在手机上，打开 OpenClaw 应用 → 设置 → Gateway。
6. 扫描二维码或粘贴设置代码，然后连接。

当官方 OpenClaw iOS 和 Android 应用的设置代码元数据匹配时，它们会被自动批准。如果 待批准 中显示某个请求（例如来自非官方客户端或元数据不匹配），请在批准前检查其角色和权限范围。

如果当前 Control UI 会话没有管理员访问权限，该按钮会被禁用。在这种情况下，请在 Gateway 主机上使用下面的 CLI 批准流程。

通过 Telegram 配对¶

如果你使用 device-pair 插件，可以完全通过 Telegram 完成首次设备配对：

1. 在 Telegram 中向你的机器人发送：/pair
2. 机器人会回复两条消息：一条说明消息和一条单独的 设置代码 消息（便于在 Telegram 中复制/粘贴）。
3. 在手机上，打开 OpenClaw iOS 应用 → 设置 → Gateway。
4. 扫描二维码（/pair qr）或粘贴设置代码，然后连接。
5. 官方移动应用会自动连接。如果 /pair pending 显示某个请求，请在批准前检查其角色和权限范围。

设置代码是一个 base64 编码的 JSON 负载，其中包含：

• url：Gateway WebSocket URL（ws://... 或 wss://...）
• urls：如果可用，移动应用可尝试的有序 LAN/Tailnet 路由
• bootstrapToken：用于初始配对握手的单次引导 Token；Gateway 会在 10 分钟后使其过期

配对完成后，运行 /pair cleanup 使未使用的设置代码失效。

该引导 Token 携带内置的配对引导配置：

• 安全的 wss:// 设置（或同主机回环）默认使用 node 加上完整的原生移动 operator 访问权限
• 交接的 node Token 保持为 scopes: []
• 默认交接的 operator Token 包含 operator.admin、operator.approvals、operator.read、operator.talk.secrets 和 operator.write
• Control UI 的 受限访问 和 openclaw qr --limited 会省略 operator.admin，同时保留其他 operator 权限范围
• 明文 LAN ws:// 设置会自动使用相同的受限配置；请配置 wss:// 或 Tailscale Serve，并生成新的设置代码以获得完全访问权限
• 后续的 Token 轮换/吊销仍受设备已批准的角色契约和调用方会话的 operator 权限范围共同约束

在设置代码有效期内，请像对待密码一样对待它。

iOS 和 Android 的 设置 → Gateway 页面会显示 完全 或 受限 访问权限。要升级受限手机，请先配置安全的 wss:// 或 Tailscale Serve 路由，然后生成新的完全访问设置代码，在该设置页面中扫描或粘贴它，并重新连接。

对于 Tailscale、公网或其他远程移动配对，请使用 Tailscale Serve/Funnel 或其他 wss:// Gateway URL。明文 ws:// 设置代码仅接受回环、私有 LAN 地址、.local Bonjour 主机以及 Android 模拟器主机。非回环明文路由将获得受限访问权限。Tailnet CGNAT 地址、.ts.net 名称和公网主机在签发 QR/设置代码之前仍会失败关闭。

只有当 OpenClaw 通过 gateway.tailscale.mode=serve|funnel 拥有该路由时，才会通告 Tailscale 设置 URL。代理 gateway.bind=lan 监听器的旧版外部 Serve 路由不会被通告，因为普通监听器会拒绝 Tailscale 形状的代理入站流量。运行 openclaw doctor 检查路由；Doctor 会保持配置不变，因为它无法证明路由所有权。如果你确认它是来自旧版 OpenClaw 版本的过期路由，请仅使用 tailscale serve --yes --https=443 --set-path=/ off 或 tailscale funnel --yes --https=443 --set-path=/ off 移除其根处理器，然后手动配置 gateway.bind=loopback 和 gateway.tailscale.mode=serve，并重启 Gateway。如果另一个服务拥有该路由，请保持托管 Tailscale 入站关闭，并配置显式的 gateway.trustedProxies 兼容路径。自定义 Serve 端口和 Tailscale Services 需要手动迁移。对于已弃用的 gateway.tailscale.serviceName 配置，Doctor 会禁用托管入站，并打印清除保留 Service 路由所需的命令。

批准节点设备¶

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

如果显式批准被拒绝，原因是执行批准的已配对设备会话是以仅配对权限范围打开的，CLI 会使用 operator.admin 重试同一请求。这可以让现有具备管理员能力的已配对设备恢复新的 Control UI/浏览器配对，而无需手动编辑配对存储。Gateway 仍会验证重试的连接；无法使用 operator.admin 进行身份验证的 Token 仍会被阻止。

如果同一设备使用不同的身份验证详情重试（例如不同的角色/权限范围/公钥），之前的待处理请求会被取代，并创建新的 requestId。

可选的受信任 CIDR 节点自动批准¶

设备配对默认仍为手动。对于严格控制的节点网络，你可以选择使用显式 CIDR 或精确 IP 启用首次节点自动批准：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

这仅适用于新的 role: node 配对请求，且未请求任何作用域。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动审批。角色、作用域、元数据和公钥变更仍需要手动审批。

节点配对状态存储¶

存储在位于 ~/.openclaw/state/openclaw.sqlite 的共享 SQLite 状态数据库中：

• 待处理的设备配对请求（短期有效；5 分钟后过期）
• 已配对设备 + Token

旧版 Gateway 将此状态保存在 ~/.openclaw/devices/*.json 中。停止 Gateway，并运行 openclaw doctor --fix，将这些文件导入 SQLite，并以 .migrated 后缀归档。正常启动不会修改遗留文件。

备注¶

• node.pair.* API（CLI：openclaw nodes pending|approve|reject|remove|rename）管理存储在同一已配对设备记录中的节点能力审批。WS 节点仍需要设备配对；参见节点配对。
• 配对记录是已批准角色的持久事实来源。活动设备 Token 始终限制在该已批准角色集合内；已批准角色之外的游离 Token 条目不会创建新的访问权限。

相关文档¶

• 安全模型 + Prompt 注入：安全
• 安全更新（运行 doctor）：更新
• 通道配置：
• Telegram：Telegram
• WhatsApp：WhatsApp
• Signal：Signal
• iMessage：iMessage
• Discord：Discord
• Slack：Slack
• openclaw pairing — 通过 CLI 驱动配对