快速开始
二维码
openclaw qr
根据当前的 Gateway 网关配置生成移动设备配对二维码和设置代码。
openclaw qropenclaw qr --setup-code-onlyopenclaw qr --jsonopenclaw qr --remoteopenclaw qr --url wss://gateway.example/ws当设置代码的元数据匹配时，官方 OpenClaw iOS 和 Android 应用会自动连接。如果请求仍处于待处理状态（例如使用非官方客户端或元数据不匹配），请查看并批准该请求：
openclaw devices listopenclaw devices approve <requestId>选项
--remote：优先使用gateway.remote.url；如果未设置该 URL，则回退到gateway.tailscale.mode=serve|funnel。忽略device-pair插件的publicUrl。--url <url>：覆盖载荷中使用的 Gateway 网关 URL--public-url <url>：覆盖载荷中使用的公共 URL--token <token>：覆盖引导流程用于身份验证的 Gateway 网关令牌--password <password>：覆盖引导流程用于身份验证的 Gateway 网关密码--setup-code-only：仅输出设置代码--no-ascii：跳过 ASCII 二维码渲染--json：输出 JSON（setupCode、gatewayUrl、可选的gatewayUrls、auth、urlSource）
--token 和 --password 互斥。
设置代码内容
设置代码携带的是不透明的短期 bootstrapToken，而不是共享的 Gateway 网关令牌或密码。内置引导流程会签发：
- 一个主要的
node令牌，带有scopes: [] - 一个受限的
operator交接令牌，其权限仅限于operator.approvals、operator.read、operator.talk.secrets和operator.write
配对变更权限范围和 operator.admin 仍需要单独获批的操作员配对或令牌流程。
Gateway 网关 URL 解析
对于使用 Tailscale 或公共 ws:// 的 Gateway 网关 URL，移动设备配对会以失败关闭方式处理：请使用 Tailscale Serve/Funnel 或 wss:// Gateway 网关 URL。专用局域网地址和 .local Bonjour 主机仍支持通过普通 ws:// 连接。
当选定的 Gateway 网关 URL 来自 gateway.bind=lan 时，OpenClaw 还会检查持久化的 tailscale serve status --json 路由。任何代理到活动 Gateway 网关 local loopback 端口的 HTTPS Serve 根路由都会作为回退项包含在内。二维码命令仅针对 lan 添加此回退项；custom 和 tailnet 会保留其明确公布的路由。当前 iOS 客户端会按顺序探测公布的路由，并保存第一个可访问的路由；旧版 url 字段保持不变，以供较旧的客户端使用。
使用 --remote 时，必须配置 gateway.remote.url 或 gateway.tailscale.mode=serve|funnel 之一。
身份验证解析（不使用 --remote）
未传入 CLI 身份验证覆盖参数时，本地 Gateway 网关身份验证 SecretRef 按以下方式解析：
| 条件 | 解析为 |
|---|---|
gateway.auth.mode="token"，或推断模式下不存在优先级更高的密码来源 |
gateway.auth.token |
gateway.auth.mode="password"，或推断模式下身份验证配置和环境变量中不存在优先级更高的令牌 |
gateway.auth.password |
同时配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRef），且未设置 gateway.auth.mode |
失败；请显式设置 gateway.auth.mode |
身份验证解析（使用 --remote）
如果实际生效的远程凭据被配置为 SecretRef，并且未传入 --token 或 --password，该命令会从活动的 Gateway 网关快照中解析这些凭据。如果 Gateway 网关不可用，该命令会立即失败。
