OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

配置

配对

“配对”是 OpenClaw 明确的访问审批步骤。 它用于两个方面：

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

安全上下文：安全

1）私信配对（入站聊天访问）

当渠道配置了私信策略 pairing 时，未知发送者会收到一个短代码，在你批准之前，其消息不会被处理。

默认私信策略记录于：安全

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

配对代码：

  • 8 个字符、大写、不含易混淆字符（0O1I）。
  • 1 小时后过期。机器人仅在创建新请求时发送配对消息（每位发送者大约每小时一次）。
  • 待处理的私信配对请求上限为每个渠道账户 3 个；在其中一个请求过期或获批之前，其他请求将被忽略。

批准发送者

bash
openclaw pairing list telegramopenclaw pairing approve telegram <CODE>

在批准命令中添加 --notify，可通过同一渠道通知请求者。多账户渠道接受 --account <id>。

如果尚未配置命令所有者，批准私信配对代码还会将 commands.ownerAllowFrom 引导设置为已批准的发送者，例如 telegram:123456789。 这会为首次设置明确指定一位所有者，用于特权命令和 Exec 审批提示。所有者存在后，后续配对批准仅授予私信 访问权限；不会添加更多所有者。

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

可复用的发送者组

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

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

json5
{  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 行；不会合并旧文件

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

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

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

从 Control UI 配对（推荐）

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

  1. 打开 Control UI，然后前往 Settings → Devices。
  2. 在 Devices 页面上，点击 Pair mobile device。
  3. 保留 Full access (recommended)，或选择 Limited access 以省略 Gateway 网关管理控制权限。
  4. 点击 Create setup code。
  5. 在手机上打开 OpenClaw 应用 → Settings → Gateway。
  6. 扫描二维码或粘贴设置代码，然后连接。

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

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

通过 Telegram 配对

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

  1. 在 Telegram 中向你的机器人发送消息：/pair
  2. 机器人会回复两条消息：一条说明消息和一条单独的设置代码消息（便于在 Telegram 中复制/粘贴）。
  3. 在手机上打开 OpenClaw iOS 应用 → Settings → Gateway。
  4. 扫描二维码（/pair qr）或粘贴设置代码并连接。
  5. 官方移动应用会自动连接。如果 /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 的 Limited access 和 openclaw qr --limited 会省略 operator.admin，同时保留其他操作员权限范围
  • 明文 LAN ws:// 设置会自动使用相同的受限配置文件； 请配置 wss:// 或 Tailscale Serve，并生成新代码以获得完整访问权限
  • 后续令牌轮换/吊销仍同时受设备已批准的 角色契约和调用方会话操作员权限范围的约束

设置代码有效期间，请像对待密码一样保护它。

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

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

对于 gateway.bind=lan 设置 URL，OpenClaw 会检测代理活动 Gateway 网关 环回端口的持久 Tailscale Serve HTTPS 根地址，并将其与 LAN 路由一起公布。设置命令仅 为 lan 添加此后备选项；custom 和 tailnet 保留其明确公布的路由。iOS 应用会按顺序探测公布的路由，并保存第一个可达的 端点。

批准节点设备

bash
openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

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

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

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

默认情况下，设备配对仍需手动进行。对于严格管控的节点网络， 可以使用显式 CIDR 或确切 IP，选择启用首次节点自动批准：

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

这仅适用于没有请求权限范围的新 role: node 配对请求。 操作员、浏览器、Control UI 和 WebChat 客户端仍需要手动 批准。角色、权限范围、元数据和公钥更改仍需要手动 批准。

节点配对状态存储

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

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

旧版 Gateway 网关将此状态保存在 ~/.openclaw/devices/*.json 中；这些文件会 在 Gateway 网关启动时导入 SQLite，并使用 .migrated 后缀归档。

注意事项

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

相关文档

Was this useful?
On this page

On this page