配对 - OpenClaw 中文文档

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

DM 配对（允许谁可以与机器人交谈）
节点配对（允许哪些设备/节点加入网关网络）

安全上下文：安全

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

当某个频道配置了 DM 策略 pairing 时，未知发送者会收到一个短码，在你批准之前，他们的消息不会被处理。默认 DM 策略记录在：安全 dmPolicy: "open" 仅在生效的 DM 白名单包含 "*" 时才是公开开放的。对于公开开放配置，设置和验证都需要该通配符。如果现有状态中包含带具体 allowFrom 条目的 open，运行时仍然只接纳这些发送者，而配对存储中的批准不会扩大 open 访问范围。配对码：

8 个字符，大写，不包含易混淆字符（0O1I）。
1 小时后过期。机器人仅在创建新请求时发送配对消息（每个发送者大约每小时一次）。
待处理的 DM 配对请求上限为每个频道账号 3 个；在某个请求过期或被批准之前，额外请求将被忽略。

从控制界面批准

打开 设置 → 频道 → DM 访问请求。队列会合并所有已配置频道账号中 dmPolicy 为 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 的条目。这会为首次配置提供一个明确的拥有者，用于特权命令和 exec 批准提示。拥有者存在后，后续配对批准只会授予 DM 访问权限；不会再添加更多拥有者。

WhatsApp 的登录二维码会将一个 WhatsApp 账号链接到 OpenClaw。DM 访问请求则是批准向该账号发消息的人。这是两个独立的流程。

支持的频道（任何声明配对功能的已安装频道插件；像 openclaw-weixin 这样的外部插件可以添加更多）：discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, signal, slack, sms, synology-chat, telegram, twitch, whatsapp, zalo, zalouser。

可复用的发送者组

当相同的受信任发送者集合应适用于多个消息频道，或同时适用于 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"] },
  },
}

访问组的详细文档在这里：访问组

状态存储位置

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

channel_pairing_requests 中的待处理请求
channel_pairing_allow_entries 中已批准的发送者

账号范围行为：

每个请求和已批准的发送者都按频道和账号键控
运行时只读取规范的 SQLite 行；不会合并旧文件

旧版网关会将 <channel>-pairing.json 和 <channel>-<accountId>-allowFrom.json 写入 ~/.openclaw/credentials/。启动迁移和 openclaw doctor --fix 会把这些文件导入 SQLite，并在成功导入后删除每个源文件。请将 SQLite 数据库视为敏感信息，因为这些记录决定了对你的助手的访问权限。

配对白名单存储用于 DM 访问。群组授权是分开的。批准 DM 配对码不会自动允许该发送者在群组中运行命令或控制机器人。首次拥有者引导是 commands.ownerAllowFrom 中的独立配置状态，而群聊投递仍遵循频道的群组白名单（例如 groupAllowFrom、groups，或按频道不同的每群组/每主题覆盖项）。

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

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

从 Control UI 配对（推荐）

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

打开 Control UI 并前往 设置 → 设备。
在设备页面，点击 配对设备。
保持选择完整访问权限（推荐），或选择受限访问权限以省略管理员 Gateway 控制。
点击 创建设置码。
在手机上打开 OpenClaw 应用 → 设置 → 网关。
扫描二维码或粘贴设置码，然后连接。

当它们的设置码元数据匹配时，官方 OpenClaw iOS 和 Android 应用会自动批准。如果 待批准 显示一个请求（例如，对于非官方客户端或元数据不匹配），在批准之前请检查其角色和作用域。当当前 Control UI 会话没有管理员访问权限时，该按钮会被禁用。在这种情况下，请使用下面来自 Gateway 主机的 CLI 批准流程。

通过 Telegram 配对

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

在 Telegram 中，给你的机器人发送消息：/pair
机器人会回复两条消息：一条说明消息，以及一条单独的 设置码 消息（在 Telegram 中很容易复制/粘贴）。
在你的手机上，打开 OpenClaw iOS 应用 → 设置 → 网关。
扫描二维码（/pair qr）或粘贴设置码并连接。
官方移动端应用会自动连接。如果 /pair pending 显示一个请求，在批准前请检查其角色和作用域。

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

url：Gateway WebSocket URL（ws://... 或 wss://...）
urls：在可用时，移动应用可以按顺序尝试的 LAN/Tailnet 路由
bootstrapToken：用于初始配对握手的一次性引导令牌；Gateway 会在 10 分钟后过期它

配对完成后，运行 /pair cleanup 以使未使用的设置码失效。该引导令牌携带内置的配对引导配置：

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

在设置码有效期间，请将其视为密码。 iOS 和 Android 的 设置 → 网关页面会显示完整或受限访问权限。要将受限手机升级，请先配置安全的 wss:// 或 Tailscale Serve 路由，然后生成一个新的完整访问权限设置码，在该设置页面中扫描或粘贴它，并重新连接。对于 Tailscale、公共网络或其他远程移动端配对，请使用 Tailscale Serve/Funnel 或其他 wss:// Gateway URL。明文 ws:// 设置码仅接受用于回环、本地 LAN 地址、.local Bonjour 主机以及 Android 模拟器主机。非回环明文路由会获得受限访问权限。Tailnet CGNAT 地址、.ts.net 名称和公共主机在二维码/设置码发放前仍会失败并关闭。对于 gateway.bind=lan 设置 URL，OpenClaw 会检测持续存在的 Tailscale Serve HTTPS 根路径，这些根路径代理活动 Gateway 的回环端口，并将它们与 LAN 路由一起公布。设置命令只在 lan 下添加此回退；custom 和 tailnet 会保留其明确公布的路由。iOS 应用会按顺序探测公布的路由，并保存第一个可达的端点。

批准一个节点设备

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

当显式批准被拒绝，是因为批准配对设备会话是以仅配对范围打开的， CLI 会使用 operator.admin 重新尝试同一个请求。这使得现有的具备管理员能力的配对设备能够恢复一个新的 Control UI/浏览器配对，而无需手动编辑配对存储。Gateway 仍会验证重试后的连接；无法使用 operator.admin 进行身份验证的令牌仍会被阻止。如果同一设备使用不同的认证详情重试（例如不同的角色/范围/公钥），先前的待处理请求会被取代，并创建一个新的 requestId。

已配对的设备不会在不提示的情况下获得更宽的访问权限。如果它重新连接并请求更多范围或更宽的角色，OpenClaw 会保持现有批准不变，并创建一个新的待升级请求。在批准之前，请使用 openclaw devices list 比较当前已批准的访问权限与新请求的访问权限。

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

设备配对默认仍需人工处理。对于严格受控的节点网络，你可以通过显式 CIDR 或精确 IP 启用首次节点自动批准：

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

这仅适用于没有请求范围的全新 role: node 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍然需要人工批准。角色、范围、元数据和公钥的更改仍然需要人工批准。

节点配对状态存储

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

待处理的设备配对请求（短期存在；5 分钟后过期）
已配对设备 + 令牌

较早的网关会将此状态保存在 ~/.openclaw/devices/*.json 中；这些文件会在网关启动时导入到 SQLite，并以 .migrated 后缀归档。

说明

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

概览

主流消息平台

开发者与自托管

区域平台

配置

配对

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

从控制界面批准

从 CLI 批准

可复用的发送者组

状态存储位置

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

从 Control UI 配对（推荐）

通过 Telegram 配对

批准一个节点设备

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

节点配对状态存储

说明

相关文档

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

​从控制界面批准

​从 CLI 批准

​可复用的发送者组

​状态存储位置

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

​从 Control UI 配对（推荐）

​通过 Telegram 配对

​批准一个节点设备

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

​节点配对状态存储

​说明

​相关文档

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

从控制界面批准

从 CLI 批准

可复用的发送者组

状态存储位置

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

从 Control UI 配对（推荐）

通过 Telegram 配对

批准一个节点设备

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

节点配对状态存储

说明

相关文档