企业官网建设流程全解析

openclaw clawbot：旧版命令命名空间的兼容机制与迁移指南

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

openclaw clawbot是 OpenClaw CLI 中一个保留的旧版（legacy）命令命名空间，专门用于保持与历史脚本的向后兼容。本文围绕 docs/cli/clawbot.md 展开，说明该命名空间的注册原理、与顶层openclaw qr命令的等价关系、迁移路径以及移动端配对（pairing）命令的完整用法，帮助维护旧脚本的开发者快速判断哪些命令可以安全替换、哪些参数在新命令下依然有效。

一、clawbot是什么：一个为兼容而生的命令命名空间

在 OpenClaw 的命令体系中，clawbot不是一个独立的功能模块，而是一个legacy alias namespace（旧版别名命名空间）。它存在的唯一目的，是让早期使用openclaw clawbot ...写法的脚本和习惯仍然可以运行，避免因为命令改名而破坏已有的自动化流程。

从源码来看，这个命名空间的定义非常精简。在 src/cli/clawbot-cli.ts 中：

// Legacy clawbot command namespace kept for QR/linking aliases. import type { Command } from "commander"; import { formatDocsLink } from "../../packages/terminal-core/src/links.js"; import { theme } from "../../packages/terminal-core/src/theme.js"; import { registerQrCli } from "./qr-cli.js"; export function registerClawbotCli(program: Command) { const clawbot = program .command("clawbot") .description("Legacy clawbot command aliases") .addHelpText( "after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/clawbot", "docs.openclaw.ai/cli/clawbot")}\n`, ); registerQrCli(clawbot); }

关键信息有两点：

1. clawbot命名空间在帮助文本中直接链接到本页文档（/cli/clawbot），方便使用者随时查阅迁移说明；
2. 它通过registerQrCli(clawbot)把qr子命令注册到clawbot命名空间之下——这正是“与顶层命令等价”这一说法的来源：clawbot下唯一实际注册的命令就是qr。

在子命令注册表 src/cli/program/subcli-descriptors.ts 中，clawbot被登记为：

{ name: "clawbot", description: "Legacy clawbot command aliases", hasSubcommands: true, },

注意hasSubcommands: true——它是一个“有子命令的命令组”，而它的子命令列表里只有qr。相关的注册测试（如 src/cli/help-exit.process.test.ts 与 src/cli/program/register.subclis.test.ts）也验证了clawbot会被正常注册为顶层子命令组。

二、核心机制：openclaw clawbot qr与openclaw qr完全等价

既然registerQrCli(clawbot)和顶层 CLI 注册的是同一个qr命令实现（见 src/cli/qr-cli.ts 中的registerQrCli导出），那么：

openclaw clawbot qr [flags] ≡ openclaw qr [flags]

两条命令走的是同一套参数解析、同一套配对逻辑、同一个输出格式。这意味着：

• openclaw clawbot qr接受openclaw qr的全部 flag；
• 两者的行为完全一致，不存在功能差异；
• 因此旧脚本可以放心迁移，替换后不需要调整任何参数。

迁移对照

按 docs/cli/clawbot.md 给出的官方迁移指引，唯一的迁移规则是：

此外，如果旧脚本中还有openclaw clawbot qr --xxx这类带参数的形式，直接替换命令名为openclaw qr --xxx即可，flag 列表完全继承。

三、qr子命令详解：移动端配对二维码与 Setup Code

由于clawbot命名空间唯一有效的命令就是qr，理解它的能力就等于理解了clawbot命名空间的实际用途：从当前 Gateway 配置生成移动端配对二维码（QR）与 setup code，用于把 OpenClaw 官方 iOS / Android 应用快速接入当前网关。

基本用法

# 生成配对二维码（终端 ASCII 渲染） openclaw qr # 只输出 setup code（便于复制粘贴/远程分享） openclaw qr --setup-code-only # 输出 JSON 文档（便于脚本解析） openclaw qr --json # 优先使用远程网关地址 openclaw qr --remote # 受限访问权限的配对 openclaw qr --limited # 语音节点配对 openclaw qr --voice-node # 显式指定网关 URL openclaw qr --url wss://gateway.example/ws

完整参数表

这些参数的实现可在 src/cli/qr-cli.ts 的.option(...)定义中逐一对应；互斥约束（--token/--password二选一、--limited/--voice-node二选一）也在 action 入口处显式校验：

if (opts.token && opts.password) { throw new Error("Use either --token or --password, not both."); } if (opts.limited && opts.voiceNode) { throw new Error("Use either --limited or --voice-node, not both."); }

配对后的审批流程

官方 OpenClaw iOS / Android 应用在 setup-code 元数据匹配时会自动连接。若请求保持 pending（例如非官方客户端或元数据不匹配），需要手动审批：

openclaw devices list openclaw devices approve <requestId>

这一步在qr命令的终端输出中也会被直接提示（见 src/cli/qr-cli.ts）。

四、Setup Code 的内容与访问级别

Setup code 内部携带的是一个不透明且短期有效的bootstrapToken，而不是共享的网关 token/password。对于wss://端点（或同主机 loopback），默认 bootstrap 流程会签发：

• 一个主nodetoken，scopes: []（空权限）；
• 一个完整的原生移动端operator交接 token，包含operator.admin、operator.approvals、operator.read、operator.talk.secrets、operator.write权限。

在源码中，这两条路径分别对应 src/shared/device-bootstrap-profile.ts 中的PAIRING_SETUP_BOOTSTRAP_PROFILE与VOICE_NODE_PAIRING_SETUP_BOOTSTRAP_PROFILE，在qraction 中通过--voice-node/--limited选择（见 src/cli/qr-cli.ts）。

明文传输的安全降级

纯文本 LANws://的 setup 仍然可用，但 OpenClaw 会自动使用受限（limited）profile：因为网络上的观察者可能截获并抢跑 bearer bootstrap token。此时命令会打印类似下面的警告：

This Gateway URL uses plaintext ws://, so the setup code was limited for safety. Use wss:// or Tailscale Serve, then generate a new code for full access.

想获得完整访问权限，请配置wss://或 Tailscale Serve 后重新生成 code（警告文案定义见 src/cli/qr-cli.ts 的LIMITED_TRANSPORT_WARNING）。

五、Gateway URL 解析与安全边界

移动端配对在以下场景会fail closed（默认拒绝）：

• Tailscale / 公网ws://网关 URL不可用于配对——请改用 Tailscale Serve/Funnel 或wss://；
• 私有 LAN 地址与.localBonjour 主机仍然支持明文ws://，但如上所述只能获得受限 operator 访问权限。

关于 Tailscale URL 的广告策略：QR 命令只在 OpenClaw 自己拥有该路由（即gateway.tailscale.mode=serve|funnel）时才广告 Tailscale URL。那些指向普通 Gateway listener 的旧式外部 Serve 路由不会被广告，因为该 listener 会拒绝 Tailscale 形状的代理入站流量。

旧配置迁移注意事项（gateway.bind=lan）

如果旧环境使用过gateway.bind=lan并长期保留了一条默认的 HTTPS Serve 路由，请运行openclaw doctor检查。需要注意：

• Doctor不会自动迁移或清除该路由，因为其状态无法证明路由归属，即使带--fix也不会动手；
• 若确认路由已过期，请手动执行：清除其 root handler → 配置gateway.bind=loopback+gateway.tailscale.mode=serve→ 重启 Gateway；
• 自定义 Serve 端口和已退役的 named-Service 路由也需要同样的手动清理；Doctor 会打印相应指引。

--remote的前置条件

使用--remote时，gateway.remote.url与gateway.tailscale.mode=serve|funnel二者至少配置其一，否则命令直接报错（对应源码 src/cli/qr-cli.ts 中的校验逻辑）。

六、认证解析规则

不传--remote时（本地认证）

当没有 CLI 认证参数覆盖时，本地 Gateway auth SecretRef 按如下规则解析：

这个“两种凭证都配置但没指定模式就报错”的设计，是为了避免歧义，防止凭据选择出现不确定性。本地密码解析的代码路径可见 src/cli/qr-cli.ts（shouldResolveLocalGatewayPasswordSecret与resolveLocalGatewayPasswordSecretIfNeeded）。

传--remote时（远程认证）

如果当前生效的远程凭证以 SecretRef 形式配置，且未传--token/--password，命令会从活跃的网关快照中解析凭证（通过resolveCommandSecretRefsViaGateway，见 src/cli/qr-cli.ts）。若网关不可用，命令快速失败。

注意：该路径要求网关支持secrets.resolveRPC 方法；旧版本网关会返回 unknown-method 错误。

七、实战：将旧脚本一键迁移到现代命令

综合以上内容，给出一个完整的迁移示例。假设旧脚本内容为：

# 旧脚本：生成配对二维码 openclaw clawbot qr --setup-code-only # 旧脚本：受限访问配对 openclaw clawbot qr --limited --remote

迁移后等价写法为：

# 新写法：生成配对二维码（行为完全一致） openclaw qr --setup-code-only # 新写法：受限访问配对（行为完全一致） openclaw qr --limited --remote

迁移要点总结：

1. 直接把clawbot从命令中删掉，其余参数原样保留；
2. 不需要修改任何 flag、环境变量或配置；
3. 迁移后建议用openclaw qr --json验证输出结构是否与预期一致；
4. 若脚本按 JSON 解析，注意字段固定为setupCode、gatewayUrl、gatewayUrls（可选）、auth、access、accessDowngraded（可选）、urlSource。

八、关联文档与进一步阅读

clawbot命名空间的官方文档位于 docs/cli/clawbot.md，其「Related」章节指向如下页面，可直接在仓库内查阅：

• CLI 总览
• openclaw qr完整参考
• 设备管理openclaw devices
• 配对openclaw pairing

实现层面，可继续阅读：

• 命名空间注册：src/cli/clawbot-cli.ts
• QR 子命令完整实现：src/cli/qr-cli.ts
• 子命令注册表（clawbot条目）：src/cli/program/subcli-descriptors.ts
• 注册测试：src/cli/program/register.subclis.test.ts、src/cli/help-exit.process.test.ts

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