OpenClaw `clawbot` 命令别名命名空间：兼容性保障与向现代命令的迁移指南

人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载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 qropenclaw 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即可。建议在修改脚本时同步做以下检查全局搜索旧命令前缀在维护中的脚本里搜索clawbot逐一确认是否只包含clawbot qr形式当前仅此一个别名其他clawbot ...形式在当前版本并不存在属于无效命令同步迁移配套命令qr生成配对二维码后设备审批流程使用的是openclaw devices list与openclaw devices approve requestId详见 docs/cli/devices.md这些配套命令也需要一并更新验证输出迁移后运行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选项说明--remote使用配置中的gateway.remote.url及远端 token/password忽略 device-pair 插件的 publicUrl--url url覆盖生成载荷中使用的 Gateway URL--public-url url覆盖生成载荷中使用的公网 URL--token token覆盖生成载荷中的 Gateway token--password password覆盖生成载荷中的 Gateway password--setup-code-only只输出 setup code不渲染 ASCII 二维码--no-ascii跳过 ASCII 二维码渲染--json输出 JSON字段为setupCode、gatewayUrl、auth、urlSource关键行为细节--token与--password互斥同时传入会直接报错cli/qr-cli.ts不传任何覆盖参数时qr会读取当前配置--remote模式下优先使用gateway.remote.url要求已配置否则快速失败错误信息为 qr --remote requires gateway.remote.url (or gateway.tailscale.modeserve/funnel)见 cli/qr-cli.ts并可通过 gateway 解析远端凭据的 SecretRef非--remote模式则读取本地 Gateway 的认证配置本地凭据解析遵循明确的优先级cli/qr-cli.ts显式传--token/--password时跳过本地密码 SecretRef 解析auth.modepassword时解析gateway.auth.passwordauth.modetoken时解析 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.modeserve、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核心流程如下解析认证通过materializePairingSetupAuthConfig把配置中的 SecretRef如{ source: env, provider: default, id: ... }解析为真实值环境变量OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD优先然后根据gateway.auth.mode或有 token 用 token、有密码用密码的推断规则确定认证标签token或password解析 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 地址签发引导 token调用issueDeviceBootstrapToken生成一次性引导令牌bootstrap token与 URL 一起构成载荷编码将{ url, bootstrapToken }JSON 序列化后做 Base64 编码并把替换为-、/替换为_、去掉尾部得到可用于二维码或手动分享的 setup codepairing/setup-code.ts。若 Gateway 仅绑定 loopbackgateway.bindloopback且未配置 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 --jsonqr的终端输出会包含 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.modeserve|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即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenTelemetry Go semconv v1.32.0 迁移指南Metric 命名空间分包、标识符重命名与兼容性清单OpenTelemetry Go semconv v1.32.0 迁移指南Metric 命名空间分包、标识符重命名与兼容性清单 本篇指南围绕 go.opent可观测性Unison move 命令全解析一条命令统一移动 term、type 与命名空间Unison move 命令全解析一条命令统一移动 term、type 与命名空间 导读 move 是 Unison 代码库管理器ucm中最常用的改名/编程语言编译器语言运行时开发工具Unison 的 alias.manycopy命令批量创建别名与整理命名空间实战指南Unison 的 alias.many copy命令批量创建别名与整理命名空间实战指南 alias.many 是 Unison 命令行交互工具UCM中编程语言编译器语言运行时开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考