`openclaw qr`¶

根据当前 Gateway 配置生成移动端配对 QR 和设置代码。

旧版 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 应用会在其设置代码元数据匹配时自动连接。如果请求仍处于待处理状态（例如，来自非官方客户端或元数据不匹配），请审查并批准它：

openclaw devices list
openclaw devices approve <requestId>

选项¶

--remote：优先使用 gateway.remote.url 和远程凭据；当远程 URL 未设置时，回退到 Tailscale Serve/Funnel。忽略 device-pair 插件的 publicUrl；显式 --url 或 --public-url 仍然优先。
--url <url>：覆盖 payload 中使用的 Gateway URL
--public-url <url>：覆盖 payload 中使用的公共 URL
--token <token>：覆盖 bootstrap 流程进行身份验证的 Gateway token
--password <password>：覆盖 bootstrap 流程进行身份验证的 Gateway 密码
--limited：从交接的 operator token 中省略管理 Gateway 访问权限
--voice-node：颁发 node 凭据，并且仅包含 operator.read 和 operator.talk
--setup-code-only：仅打印设置代码；--json 优先，并改为输出 JSON 文档
--no-ascii：跳过 ASCII QR 渲染
--json：输出 JSON（setupCode、gatewayUrl、可选 gatewayUrls、auth、access、可选 accessDowngraded、urlSource）

--token 和 --password 互斥。--limited 和 --voice-node 互斥。

设置代码内容¶

设置代码携带一个不透明的、短生命周期的 bootstrapToken，而不是共享 Gateway token/密码。对于 wss:// 端点（或同主机回环），默认 bootstrap 流程会颁发：

一个主 node token，其 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 方法。

明文 LAN ws:// 设置仍然可用，但 OpenClaw 会自动使用受限配置，因为网络观察者可能捕获并抢先使用 bearer bootstrap token。配置 wss:// 或 Tailscale Serve，然后生成新代码以获得完整访问权限。

Gateway URL 解析¶

对于 Tailscale/公共 ws:// Gateway URL，移动端配对会失败关闭：请对这些使用 Tailscale Serve/Funnel 或 wss:// Gateway URL。

私有 LAN 地址和 .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，否则在 URL 解析运行之前，--remote 要求 gateway.remote.url 或 gateway.tailscale.mode=serve|funnel。仅 gateway.publicOrigin 不满足该前提条件。

URL 选择会保留现有路由：显式配对覆盖、首选远程 URL、Tailscale Serve/Funnel、非首选远程 URL，然后是 bind 派生地址。对于本地 QR 设置，gateway.publicOrigin 是在仅回环错误之前的最终回退。如果没有 --remote，已配置的 plugins.entries.device-pair.config.publicUrl 提供覆盖。与 QR 设置不同，云注册明确要求同一解析器对新的云 worker 优先使用公共入口而不是发现。

QR 设置、加入代码和云注册会在完全限定 URL 中保留上下文路径。device-pair 插件的 /pair 命令保留其历史性的仅 origin URL，包括当配置的 publicUrl 包含路径时。

身份验证解析（无 `--remote`）¶

具有 gateway.auth.mode="trusted-proxy" 的 Gateway 可以在没有共享 token 或密码的情况下生成设置代码。代理仍会在移动端连接到达 Gateway 之前对其进行身份验证。设置代码不会绕过 Cloudflare Access 或其他代理登录。 bootstrap 过期、设备绑定和访问配置保持不变。

当未传递 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

openclaw qr¶

选项¶