openclaw qr¶
根据当前 Gateway 配置生成移动端配对二维码和设置代码。
旧版 openclaw clawbot qr 别名接受以下所有标志。
openclaw qr
openclaw qr --setup-code-only
openclaw qr --json
openclaw qr --remote
openclaw qr --limited
openclaw qr --voice-node
openclaw qr --url wss://gateway.example/ws
当设置代码元数据匹配时,官方 OpenClaw iOS 和 Android 应用会自动连接。如果请求仍处于待处理状态(例如,来自非官方客户端或元数据不匹配),请审查并批准它:
选项¶
--remote:优先使用gateway.remote.url和远程凭据;当未设置远程 URL 时,回退到 Tailscale Serve/Funnel。忽略device-pair插件的publicUrl;显式--url或--public-url仍然优先。--url <url>:覆盖载荷中使用的 Gateway URL--public-url <url>:覆盖载荷中使用的公共 URL--token <token>:覆盖引导流程用于认证的 Gateway token--password <password>:覆盖引导流程用于认证的 Gateway 密码--limited:从交接的 operator token 中省略管理 Gateway 访问权限--voice-node:颁发节点凭据,并且仅包含operator.read和operator.talk--setup-code-only:仅打印设置代码;--json优先,并改为输出 JSON 文档--no-ascii:跳过 ASCII 二维码渲染--json:输出 JSON(setupCode、gatewayUrl、可选gatewayUrls、auth、access、可选accessDowngraded、urlSource)
--token 和 --password 互斥。--limited 和 --voice-node 互斥。
设置代码内容¶
设置代码携带一个不透明的、短生命周期的 bootstrapToken,而不是共享的 Gateway token/密码。对于 wss:// 端点(或同主机回环),默认引导流程会颁发:
- 一个主
nodetoken,其scopes: [] - 一个完整的原生移动端
operator交接 token,包含operator.admin、operator.approvals、operator.read、operator.talk.secrets和operator.write
使用 --limited 可保留相同的 node token,同时从 operator 交接中省略 operator.admin。配对变更权限范围绝不会通过设置代码交接。
对于嵌入式或房间语音客户端,请使用 --voice-node。它会保留 node token,并交接一个仅限 operator.read 和 operator.talk 的独立 operator token;它不能发送消息、修改配置或调用一般写权限范围的 Gateway 方法。
明文局域网 ws:// 设置仍然可用,但 OpenClaw 会自动使用受限配置,因为网络观察者可能捕获并抢先使用 bearer 引导 token。请配置 wss:// 或 Tailscale Serve,然后生成新代码以获得完整访问权限。
Gateway URL 解析¶
对于 Tailscale/公共 ws:// Gateway URL,移动端配对会失败关闭:对于这些 URL,请使用 Tailscale Serve/Funnel 或 wss:// Gateway URL。私有局域网地址和 .local Bonjour 主机仍支持通过普通 ws:// 连接,并具有上述受限 operator 访问权限。
QR 命令仅在 OpenClaw 通过 gateway.tailscale.mode=serve|funnel 拥有路由时,才会通告 Tailscale URL。指向普通 Gateway 监听器的旧版外部 Serve 路由不会被通告,因为该监听器会拒绝形似 Tailscale 的代理入口。
如果旧设置使用了 gateway.bind=lan 以及持久化的默认 HTTPS Serve 路由,请运行 openclaw doctor 进行检查。Doctor 不会迁移或清除该路由,因为其状态无法证明该路由的所有者,即使使用 --fix 也是如此;如果你确认它已过期,请仅清除其根处理器,手动配置 gateway.bind=loopback 以及 gateway.tailscale.mode=serve,然后重启 Gateway。自定义 Serve 端口和已退役的命名 Service 路由需要相同的手动清理;Doctor 会打印相关指导。
除非提供了 --url 或 --public-url,否则 --remote 要求在 URL 解析运行之前具备 gateway.remote.url 或 gateway.tailscale.mode=serve|funnel。仅 gateway.publicOrigin 不满足该前提条件。
URL 选择会保留现有路由:显式配对覆盖、首选远程 URL、Tailscale Serve/Funnel、非首选远程 URL,然后是绑定派生地址。对于本地 QR 设置,gateway.publicOrigin 是在仅回环错误之前的最终回退。如果没有 --remote,已配置的 plugins.entries.device-pair.config.publicUrl 提供覆盖。与 QR 设置不同,云注册 明确要求同一解析器为新的云 worker 优先使用公共入口而不是发现。
QR 设置、加入代码和云注册会在完全限定的 URL 中保留上下文路径。device-pair 插件的 /pair 命令保留其历史性的仅源 URL,包括当配置的 publicUrl 包含路径时。
认证解析(无 --remote)¶
具有 gateway.auth.mode="trusted-proxy" 的 Gateway 可以在没有共享 token 或密码的情况下生成设置代码。代理仍会在移动连接到达 Gateway 之前对其进行认证。设置代码不会绕过 Cloudflare Access 或其他代理登录。引导过期、设备绑定和访问配置保持不变。
当未传递 CLI 认证覆盖时,本地 Gateway 认证 SecretRefs 解析如下:
| 条件 | 解析结果 |
|---|---|
gateway.auth.mode="token",或推断模式且没有胜出的密码来源 |
gateway.auth.token |
gateway.auth.mode="password",或推断模式且 auth/env 中没有胜出的 token |
gateway.auth.password |
| 条件 | 解析结果 |
|---|---|
同时配置了 gateway.auth.token 和 gateway.auth.password(包括 SecretRefs),且未设置 gateway.auth.mode |
失败;请显式设置 gateway.auth.mode |
认证解析(--remote)¶
如果实际生效的远程凭据以 SecretRefs 形式配置,且未传入 --token 或 --password,该命令会从当前网关快照中解析它们。如果网关不可用,该命令会快速失败。
Note
此命令路径需要支持 secrets.resolve RPC 方法的网关。旧版网关会返回未知方法错误。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw