企业官网建设流程全解析

OpenClaw pairing 命令完全指南：DM 配对请求的审批、owner 引导与账户级管控

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

openclaw pairing是 OpenClaw 用于审批 DM 配对请求的核心 CLI 命令，负责管理支持配对模式的聊天渠道中"谁可以给机器人发消息"这一准入环节。本指南以 docs/cli/pairing.md 为骨架，结合 docs/channels/pairing.md 中的配对协议与 src/cli/pairing-cli.ts、src/pairing/pairing-store-sqlite.ts 等源码实现，讲解pairing list/pairing approve的完整用法、账户过滤规则、首次 owner 自动引导机制以及状态存储位置。读完本文，你将能独立完成一个聊天渠道从"未知发送者请求接入"到"审批通过并（可选）成为命令所有者"的全流程操作，并理解其背后的安全边界。

一、配对机制概述：什么是 DM pairing

OpenClaw 将"配对（pairing）"定义为显式的访问审批步骤，它出现在两个场景中：

1. DM 配对：决定谁被允许与机器人进行私聊；
2. 节点配对：决定哪些设备/节点被允许加入 Gateway 网络。

openclaw pairing命令只处理前者（聊天 DM），节点/设备配对走openclaw devices，Node 能力审批走openclaw nodes pending|approve|reject|remove|rename（见 docs/channels/pairing.md 中的说明）。

当一个渠道配置了dmPolicy: "pairing"时，未知发送者发来的消息不会立即被处理，而是会收到一个短配对码，直到管理员审批通过。配对码的生成遵循以下规则（来自 docs/channels/pairing.md）：

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

从源码看，配对挑战的发放统一走 src/pairing/pairing-challenge.ts 中的issuePairingChallenge()：先 upsert 请求（不存在才创建），只在新建时回复配对码，并异步触发channel_pairing_requested钩子（不阻塞配对码回复），保证每个渠道遵循一致的"先创建再回复"流程。

注意：dmPolicy: "open"只有在有效 DM 允许列表中包含"*"时才等于公开访问。如果已有状态中open搭配了具体allowFrom条目，运行时仍只放行这些发送者，且配对库的审批不会扩大open的访问范围（见 docs/channels/pairing.md）。

二、快速上手：三条最常用命令

# 列出 telegram 渠道的待审批配对请求 openclaw pairing list telegram # 指定渠道与账户列出待审批请求 openclaw pairing list --channel telegram --account work # 以 JSON 格式输出，便于脚本处理 openclaw pairing list telegram --json # 审批某个配对码（只有单个配对渠道时） openclaw pairing approve <code> # 审批某个渠道的配对码 openclaw pairing approve telegram <code> # 审批并通过 --notify 通知请求者 openclaw pairing approve --channel telegram --account work <code> --notify

其中--account <accountId>用于将命令限制在某个渠道账户内：省略时，list会显示该渠道所有账户的待处理请求，approve则使用匹配请求所属的账户。显式传入空值或纯空白值（如--account ""）会被拒绝并报错--account must not be blank——这是源码 src/cli/pairing-cli.ts 中resolveAccountId()的刻意设计：省略账户不做限定，但显式空白绝不能被静默当成"无限制"处理。

在 Control UI 中，同样的待处理请求显示在Settings → Channels → DM access requests页面，支持审批、可选的请求者通知以及忽略（Dismiss 只移除当前请求，不会永久屏蔽发送者）。

三、pairing list：查看待审批队列

pairing list用于列出某个渠道的待处理配对请求。

几个关键的解析规则（来自源码 src/cli/pairing-cli.ts 的parseChannel()与list子命令）：

• 若配置了多个支持配对的渠道，必须用位置参数或--channel指明渠道；若同时传了--channel和位置参数但两者不一致，会报Conflicting pairing channels错误；
• 未传任何渠道且恰好只有一个配对渠道时，会自动使用该渠道；若一个都没有，会提示改用openclaw devices approve处理 TUI/设备请求；
• 扩展渠道同样可用，只要渠道 id 合法（/^[a-z][a-z0-9_-]{0,63}$/）即可，无需在核心注册表中；
• 非 JSON 模式下，输出渲染为表格，包含Code、ID（senderId）、Meta（发送者元数据）、Requested（创建时间）四列，其中 ID 列标签由resolvePairingIdLabel()按渠道类型解析；
• --json模式输出{ channel, requests }结构，适合脚本消费。

四、pairing approve：审批配对码并放行发送者

pairing approve审批一个待处理配对码，并允许该发送者。

支持三种用法：

• openclaw pairing approve <channel> <code>（两个位置参数）
• openclaw pairing approve --channel <channel> <code>
• openclaw pairing approve <code>（当恰好配置了一个配对渠道时，单个参数即视为配对码）

选项：--channel <channel>、--account <accountId>、--notify（审批通过后在同一渠道向请求者发送确认消息）。

审批成功后的行为：

• 终端输出Approved <channel> sender <senderId>；
• 若同时配置了--notify，会通过渠道适配器调用notifyPairingApproved()发送默认确认文案✅ OpenClaw access approved. Send a message to start chatting.（见 src/channels/plugins/pairing-message.ts），通知失败会被捕获并输出警告而不中断流程；
• 审批不存在的配对码会报错No pending pairing request found for code "..."，并提示先用openclaw pairing list --channel <channel>查看待审批列表。

从 src/channels/plugins/pairing.ts 的listPairingChannels()可以看到，配对能力是通过渠道插件的plugin.pairing适配器声明的，因此任何已安装且声明支持配对的渠道插件都能使用此命令，外部插件（如openclaw-weixin）也可以扩展此列表。

Owner 引导（Owner bootstrap）

pairing approve有一个容易被忽略但至关重要的副作用：当commands.ownerAllowFrom为空时，CLI 会把被审批的发送者记录为命令所有者（command owner），使用渠道作用域的条目，例如telegram:123456789。

命令所有者是可以执行 owner-only 命令、审批/diagnostics、/export-session、/export-trajectory、/config以及 exec 审批等危险操作的人类操作员账户。需要特别强调的是：

• 配对只让发送者能与 agent 对话，本身并不授予 owner 权限，仅此一次性引导例外；
• 只引导第一个 owner：之后的配对审批绝不会替换或扩充commands.ownerAllowFrom；
• Control UI 将此提权行为呈现为独立的operator.admin保护复选框，而不是像 CLI 那样自动应用。

其实现位于 src/pairing/command-owner.ts 的bootstrapCommandOwnerFromPairing()：先格式化 owner 条目，读取配置快照，若已配置任何命令所有者则返回already-configured；否则将commands.ownerAllowFrom: [ownerEntry]写入配置。CLI 审批时若返回configured状态，会额外输出Command owner configured <entry> (commands.ownerAllowFrom was empty).（见 src/cli/pairing-cli.ts 第 205-213 行）。

手动加入允许列表的发送者不会自动成为命令所有者。如果已授权发送者没有 owner 权限，owner-only 命令会回复精确的openclaw config set commands.ownerAllowFrom ...命令供操作员执行。若你在 owner 引导功能出现之前就审批过发送者，运行openclaw doctor会给出警告，并显示修复所需的精确openclaw config set commands.ownerAllowFrom ...命令。

与 Control UI 审批的差异

两种方式都只授予私聊（DM）访问权，不授予群组访问权。群组命令执行仍遵循渠道的群组允许列表（如groupAllowFrom、groups或按群组/话题的覆盖项）。

五、账户级管控与多账户渠道

对于多账户渠道（例如一个渠道配置了多个机器人账户），--account的语义如下：

• list：省略时展示该渠道所有账户的待处理请求，指定时只展示该账户的；
• approve：省略时使用匹配请求所属的账户，指定时严格限定在该账户内审批；
• 显式空值（--account ""）直接报错--account must not be blank。

在存储层，每个请求和已批准发送者都按channel + account双键定位。SQLite 实现见 src/pairing/pairing-store-sqlite.ts：请求与允许条目分别存储在channel_pairing_requests、channel_pairing_allow_entries两张表中，均以channel_key过滤、按account_id排序，其中account_id缺失时归入DEFAULT_ACCOUNT_ID。元数据里的accountId只是冗余信息，真正决定请求/审批归属的是索引列（注释明确指出"duplicated metadata may be absent or stale and must never move a request or approval across accounts"）。

六、状态存储：数据存在哪里

配对相关状态保存在共享 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 数据库视为敏感数据，因为这些行直接控制谁能访问你的助手。

七、常见问题与排障指引

如需了解配对码生成细节（8 位、无0O1I、1 小时过期、每账户 3 条上限）以及 DM 访问控制的完整安全模型，参见 渠道配对文档 与 安全模型；所有渠道的 DM 策略（pairing/allowlist/open/disabled）默认值及配置方式，可参考对应渠道文档，例如 Telegram、WhatsApp、Discord。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw