OpenClaw pairing 命令完全指南DM 配对请求的审批、owner 引导与账户级管控【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawopenclaw 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 pairingOpenClaw 将配对pairing定义为显式的访问审批步骤它出现在两个场景中DM 配对决定谁被允许与机器人进行私聊节点配对决定哪些设备/节点被允许加入 Gateway 网络。openclaw pairing命令只处理前者聊天 DM节点/设备配对走openclaw devicesNode 能力审批走openclaw nodes pending|approve|reject|remove|rename见 docs/channels/pairing.md 中的说明。当一个渠道配置了dmPolicy: pairing时未知发送者发来的消息不会立即被处理而是会收到一个短配对码直到管理员审批通过。配对码的生成遵循以下规则来自 docs/channels/pairing.md8 位字符大写不含易混淆字符0O1I1 小时后过期机器人仅在新请求创建时发送配对消息每个发送者大约每小时一次每个渠道账户的待处理 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用于列出某个渠道的待处理配对请求。OptionDescription[channel]位置参数形式的渠道 id--channel channel显式指定渠道 id--account accountId多账户渠道的账户 id--json机器可读输出几个关键的解析规则来自源码 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、IDsenderId、Meta发送者元数据、Requested创建时间四列其中 ID 列标签由resolvePairingIdLabel()按渠道类型解析--json模式输出{ channel, requests }结构适合脚本消费。四、pairing approve审批配对码并放行发送者pairing approve审批一个待处理配对码并允许该发送者。支持三种用法openclaw pairing approve channel code两个位置参数openclaw pairing approve --channel channel codeopenclaw 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 bootstrappairing approve有一个容易被忽略但至关重要的副作用当commands.ownerAllowFrom为空时CLI 会把被审批的发送者记录为命令所有者command owner使用渠道作用域的条目例如telegram:123456789。命令所有者是可以执行 owner-only 命令、审批/diagnostics、/export-session、/export-trajectory、/config以及 exec 审批等危险操作的人类操作员账户。需要特别强调的是配对只让发送者能与 agent 对话本身并不授予 owner 权限仅此一次性引导例外只引导第一个 owner之后的配对审批绝不会替换或扩充commands.ownerAllowFromControl 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 审批的差异维度CLIpairing approveControl UI DM access requests通知请求者可选--notify独立的 Notify the requester after approval 选项owner 引导自动ownerAllowFrom为空时独立复选框且仅当无 owner 且会话具备operator.admin时显示审批能力任何有 CLI 访问权限的操作者需 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 数据库视为敏感数据因为这些行直接控制谁能访问你的助手。七、常见问题与排障指引问题原因与处理No chat DM pairing channels are configured没有渠道声明配对能力TUI/设备请求请改用openclaw devices approveChannel x does not support pairing该渠道插件未声明plugin.pairing适配器或渠道 id 拼写有误Conflicting pairing channels同时用位置参数和--channel指定了不同渠道只保留一种写法--account must not be blank显式传了空账户值省略该参数即可No pending pairing request found for code配对码不存在、已过期1 小时或已被审批先用pairing list复核Failed to notify requester--notify通知发送失败不影响审批结果检查渠道适配器与账户配置已审批但无法执行 owner 命令手动 allowlist 不会自动成为 owner用openclaw doctor检查commands.ownerAllowFrom并按提示执行openclaw config set commands.ownerAllowFrom ...如需了解配对码生成细节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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenClaw pairing 命令完全指南：DM 配对请求的审批、owner 引导与账户级管控
OpenClaw pairing 命令完全指南DM 配对请求的审批、owner 引导与账户级管控【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawopenclaw 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 pairingOpenClaw 将配对pairing定义为显式的访问审批步骤它出现在两个场景中DM 配对决定谁被允许与机器人进行私聊节点配对决定哪些设备/节点被允许加入 Gateway 网络。openclaw pairing命令只处理前者聊天 DM节点/设备配对走openclaw devicesNode 能力审批走openclaw nodes pending|approve|reject|remove|rename见 docs/channels/pairing.md 中的说明。当一个渠道配置了dmPolicy: pairing时未知发送者发来的消息不会立即被处理而是会收到一个短配对码直到管理员审批通过。配对码的生成遵循以下规则来自 docs/channels/pairing.md8 位字符大写不含易混淆字符0O1I1 小时后过期机器人仅在新请求创建时发送配对消息每个发送者大约每小时一次每个渠道账户的待处理 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用于列出某个渠道的待处理配对请求。OptionDescription[channel]位置参数形式的渠道 id--channel channel显式指定渠道 id--account accountId多账户渠道的账户 id--json机器可读输出几个关键的解析规则来自源码 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、IDsenderId、Meta发送者元数据、Requested创建时间四列其中 ID 列标签由resolvePairingIdLabel()按渠道类型解析--json模式输出{ channel, requests }结构适合脚本消费。四、pairing approve审批配对码并放行发送者pairing approve审批一个待处理配对码并允许该发送者。支持三种用法openclaw pairing approve channel code两个位置参数openclaw pairing approve --channel channel codeopenclaw 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 bootstrappairing approve有一个容易被忽略但至关重要的副作用当commands.ownerAllowFrom为空时CLI 会把被审批的发送者记录为命令所有者command owner使用渠道作用域的条目例如telegram:123456789。命令所有者是可以执行 owner-only 命令、审批/diagnostics、/export-session、/export-trajectory、/config以及 exec 审批等危险操作的人类操作员账户。需要特别强调的是配对只让发送者能与 agent 对话本身并不授予 owner 权限仅此一次性引导例外只引导第一个 owner之后的配对审批绝不会替换或扩充commands.ownerAllowFromControl 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 审批的差异维度CLIpairing approveControl UI DM access requests通知请求者可选--notify独立的 Notify the requester after approval 选项owner 引导自动ownerAllowFrom为空时独立复选框且仅当无 owner 且会话具备operator.admin时显示审批能力任何有 CLI 访问权限的操作者需 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 数据库视为敏感数据因为这些行直接控制谁能访问你的助手。七、常见问题与排障指引问题原因与处理No chat DM pairing channels are configured没有渠道声明配对能力TUI/设备请求请改用openclaw devices approveChannel x does not support pairing该渠道插件未声明plugin.pairing适配器或渠道 id 拼写有误Conflicting pairing channels同时用位置参数和--channel指定了不同渠道只保留一种写法--account must not be blank显式传了空账户值省略该参数即可No pending pairing request found for code配对码不存在、已过期1 小时或已被审批先用pairing list复核Failed to notify requester--notify通知发送失败不影响审批结果检查渠道适配器与账户配置已审批但无法执行 owner 命令手动 allowlist 不会自动成为 owner用openclaw doctor检查commands.ownerAllowFrom并按提示执行openclaw config set commands.ownerAllowFrom ...如需了解配对码生成细节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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考