• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

openclaw clawbot是 OpenClaw CLI 中为向后兼容而保留的旧版别名命名空间（legacy alias namespace），其唯一作用是把早期脚本中习惯使用的clawbot子命令名称继续映射到现代顶层命令。本文基于 docs/cli/clawbot.md 官方 CLI 参考，并结合仓库源码（cli/clawbot-cli.ts、cli/qr-cli.ts、cli/program/subcli-descriptors.ts 等）说明该别名机制的实现原理、当前支持的别名清单，以及如何把旧脚本平滑迁移到openclaw顶层命令，避免因命令演进导致自动化脚本失效。

什么是openclaw clawbot？

在 OpenClaw 的早期版本中，clawbot是用户与 Agent CLI 交互时惯用的子命令前缀。随着 CLI 演进，OpenClaw 将命令收敛为更清晰的顶层命令结构（如openclaw qr、openclaw devices、openclaw pairing），但为了不破坏既有脚本与使用习惯，CLI 仍保留了一个名为clawbot的占位命名空间，专门用于承接旧命令。

从源码结构看，clawbot与qr、pairing、plugins等一起被声明在子命令描述符表中（cli/program/subcli-descriptors.ts），其描述为 "Legacy clawbot command aliases"，并标记为拥有子命令（hasSubcommands: true）。CLI 在启动时通过 cli/program/register.subclis.ts 惰性加载 cli/clawbot-cli.ts，注册命令树；对应地，cli/program/register.subclis.test.ts 也验证了无主命令场景下clawbot占位符会被正常注册，说明这是一个被测试覆盖的正式兼容层。

clawbot的实现非常轻量（cli/clawbot-cli.ts）：

• 使用 commander 注册clawbot顶层命令，描述为 "Legacy clawbot command aliases"；
• 在帮助文本末尾追加指向docs/cli/clawbot的文档链接；
• 将qr子命令的注册函数（registerQrCli）直接挂载到clawbot命名空间下。

也就是说，clawbot本身并不包含任何独立的业务逻辑，它的全部能力都来自被挂载的子命令，目前唯一支持的别名是qr。

当前支持的别名：clawbot qr

openclaw clawbot qr与顶层命令openclaw qr行为完全一致，都是根据当前 Gateway 配置生成 iOS 配对二维码与 setup code。注册代码在 cli/clawbot-cli.ts 中通过registerQrCli(clawbot)复用 cli/qr-cli.ts 的完整实现，因此别名路径天然继承qr的全部选项、输出格式与错误处理，不会出现两套行为分叉。

仓库变更记录也印证了这一别名引入的背景：CHANGELOG.md 中明确记载 "register theopenclaw clawbot qrlegacy alias path"（同时优化了qr --remote对gateway.remote.url的优先级）。如果你维护的脚本中出现的是openclaw clawbot qr ...，可以放心把它视为openclaw qr ...的等价写法。

迁移指南：从clawbot到顶层命令

官方文档明确建议优先直接使用现代顶层命令，目前唯一的迁移映射是：

openclaw clawbot qr -> openclaw qr

迁移本身零成本：因为clawbot qr与qr共享同一个命令注册函数，参数、选项、输出格式完全一致，只需把命令前缀从clawbot qr改为qr即可。建议在修改脚本时同步做以下检查：

1. 全局搜索旧命令前缀：在维护中的脚本里搜索clawbot，逐一确认是否只包含clawbot qr形式（当前仅此一个别名，其他clawbot ...形式在当前版本并不存在，属于无效命令）；
2. 同步迁移配套命令：qr生成配对二维码后，设备审批流程使用的是openclaw devices list与openclaw devices approve <requestId>（详见 docs/cli/devices.md），这些配套命令也需要一并更新；
3. 验证输出：迁移后运行openclaw qr --json（或--setup-code-only）确认 JSON 结构与旧脚本的解析逻辑兼容。

另外需要留意：clawbot在 CLI 命令树中仍被声明为"拥有子命令"（cli/program/subcli-descriptors.ts），这意味着未来若旧命令继续存在，新别名也可能追加到该命名空间下；但它始终是兼容性占位符，不应在新代码中作为首选入口。

深度理解：qr命令的完整行为与选项

由于clawbot qr完全等价于qr，理解qr的全部选项就等于掌握了别名路径的全部能力。qr从当前 Gateway 配置生成配对信息（docs/cli/qr.md），完整用法如下：

openclaw qr openclaw qr --setup-code-only openclaw qr --json openclaw qr --remote openclaw qr --url wss://gateway.example/ws --token '<token>'

支持的选项（cli/qr-cli.ts）：

关键行为细节：

• --token与--password互斥，同时传入会直接报错（cli/qr-cli.ts）；
• 不传任何覆盖参数时，qr会读取当前配置：--remote模式下优先使用gateway.remote.url（要求已配置，否则快速失败，错误信息为 "qr --remote requires gateway.remote.url (or gateway.tailscale.mode=serve/funnel)"，见 cli/qr-cli.ts），并可通过 gateway 解析远端凭据的 SecretRef；非--remote模式则读取本地 Gateway 的认证配置；
• 本地凭据解析遵循明确的优先级（cli/qr-cli.ts）：显式传--token/--password时跳过本地密码 SecretRef 解析；auth.mode=password时解析gateway.auth.password；auth.mode=token时解析 token；若gateway.auth.token与gateway.auth.password同时配置且gateway.auth.mode未设置，setup code 生成会失败，直到显式设置 mode（对应 pairing/setup-code.ts 中的assertExplicitGatewayAuthModeWhenBothConfigured校验）；
• 输出的 JSON 中urlSource字段用于标注 Gateway URL 的来源（如gateway.remote.url、gateway.tailscale.mode=serve、plugins.entries.device-pair.config.publicUrl），便于脚本判断当前使用的 URL 策略；
• 该命令路径依赖 Gateway 的secrets.resolve方法，旧版本 Gateway 会返回 unknown-method 错误，升级 Gateway 后即可解决（docs/cli/qr.md）。

底层实现：setup code 如何生成

qr（及clawbot qr）的 setup code 生成逻辑位于 pairing/setup-code.ts，核心流程如下：

1. 解析认证：通过materializePairingSetupAuthConfig把配置中的 SecretRef（如{ source: "env", provider: "default", id: "..." }）解析为真实值，环境变量OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD优先；然后根据gateway.auth.mode或"有 token 用 token、有密码用密码"的推断规则确定认证标签（token或password）；
2. 解析 URL：按优先级依次尝试publicUrl（来自plugins.entries.device-pair.config.publicUrl）→gateway.remote.url（--remote时优先）→ Tailscale serve/funnel（通过tailscale status解析 MagicDNS 主机名，URL 为wss://<host>）→ Gateway 绑定地址（根据gateway.bind、customBindHost与端口推导，LAN 地址优先于 Tailnet 地址）；
3. 签发引导 token：调用issueDeviceBootstrapToken生成一次性引导令牌（bootstrap token），与 URL 一起构成载荷；
4. 编码：将{ url, bootstrapToken }JSON 序列化后做 Base64 编码，并把+替换为-、/替换为_、去掉尾部=，得到可用于二维码或手动分享的 setup code（pairing/setup-code.ts）。

若 Gateway 仅绑定 loopback（gateway.bind=loopback），且未配置 remote URL、Tailscale 或 device-pair publicUrl，解析会失败并提示 "Gateway is only bound to loopback"，对应的测试用例位于 cli/qr-cli.test.ts。该测试文件还覆盖了--remote、JSON 输出、SecretRef 解析、Tailscale serve 等多种场景，可作为理解命令行为的补充参考。

使用clawbot qr的完整工作流示例

以本地 Gateway + token 认证为例，旧脚本中的典型流程与迁移后写法对照如下：

# 旧写法（legacy alias） openclaw clawbot qr --json # 迁移后的新写法（推荐） openclaw qr --json

qr的终端输出会包含 ASCII 二维码、setup code、Gateway 地址、认证方式与来源信息，并提示扫码后用以下命令审批设备：

openclaw devices list openclaw devices approve <requestId>

对于远程 Gateway，使用--remote会让命令直接采用gateway.remote.url与远端凭据：

openclaw qr --remote --setup-code-only

此写法在gateway.remote.url或gateway.tailscale.mode=serve|funnel未配置时会快速失败（对应 CHANGELOG.md 中的 fail-fast 修复），避免生成无法使用的配对二维码。

小结

• openclaw clawbot是 OpenClaw 为向后兼容保留的别名命名空间，当前唯一支持的子命令是qr，与顶层openclaw qr完全等价；
• 新脚本应直接使用顶层命令，旧脚本建议按openclaw clawbot qr→openclaw qr的映射迁移；
• 该兼容层在源码中通过 cli/clawbot-cli.ts 复用qr注册函数实现，并由子命令描述符表与注册测试共同保障，后续旧命令演进仍会集中沉淀在该命名空间下，迁移时应一并更新配套的openclaw devices list/openclaw devices approve审批流程。

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯