OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI 命令

QR

openclaw qr

根据当前 Gateway 网关配置生成移动设备配对二维码和设置代码。

bash
openclaw qropenclaw qr --setup-code-onlyopenclaw qr --jsonopenclaw qr --remoteopenclaw qr --limitedopenclaw qr --url wss://gateway.example/ws

当设置代码元数据匹配时，OpenClaw 官方 iOS 和 Android 应用会自动连接。如果请求仍处于待处理状态（例如，来自非官方客户端或元数据不匹配），请检查并批准该请求：

bash
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 网关密码
  • --limited：从移交的操作员令牌中省略 Gateway 网关管理访问权限
  • --setup-code-only：仅输出设置代码
  • --no-ascii：跳过 ASCII 二维码渲染
  • --json：输出 JSON（setupCode、gatewayUrl、可选的 gatewayUrls、auth、access、可选的 accessDowngraded、urlSource）

--token 和 --password 互斥。

设置代码内容

设置代码携带的是不透明的短期 bootstrapToken，而不是共享的 Gateway 网关令牌/密码。对于 wss:// 端点（或同一主机上的环回地址），默认引导流程会签发：

  • 一个具有 scopes: [] 的主要 node 令牌
  • 一个完整的原生移动端 operator 移交令牌，具有 operator.admin、operator.approvals、operator.read、operator.talk.secrets 和 operator.write

使用 --limited 可保留同一节点令牌，同时从操作员移交中省略 operator.admin。设置代码绝不会移交配对变更权限范围。

明文局域网 ws:// 设置仍然可用，但 OpenClaw 会自动使用受限配置文件，因为网络观察者可能会捕获持有者引导令牌并抢先使用它。配置 wss:// 或 Tailscale Serve，然后生成新代码以获得完整访问权限。

Gateway 网关 URL 解析

对于 Tailscale/公共 ws:// Gateway 网关 URL，移动设备配对会以失败关闭方式处理：请为这些 URL 使用 Tailscale Serve/Funnel 或 wss:// Gateway 网关 URL。仍支持通过明文 ws:// 访问私有局域网地址和 .local Bonjour 主机，但操作员访问权限会按上述方式受到限制。

当选定的 Gateway 网关 URL 来自 gateway.bind=lan 时，OpenClaw 还会检查持久化的 tailscale serve status --json 路由。任何代理当前 Gateway 网关环回端口的 HTTPS Serve 根路由都会作为回退路由包含在内。QR 命令仅为 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 网关不可用，该命令会快速失败。

相关内容

Was this useful?
On this page

On this page