ContextQMD
Back to Openclaw

QR

docs/cli/qr.md

2026.5.52.9 KB
Original Source

openclaw qr

Generate a mobile pairing QR and setup code from your current Gateway configuration.

Usage

bash
openclaw qr
openclaw qr --setup-code-only
openclaw qr --json
openclaw qr --remote
openclaw qr --url wss://gateway.example/ws

Options

  • --remote: prefer gateway.remote.url; if it is unset, gateway.tailscale.mode=serve|funnel can still provide the remote public URL
  • --url <url>: override gateway URL used in payload
  • --public-url <url>: override public URL used in payload
  • --token <token>: override which gateway token the bootstrap flow authenticates against
  • --password <password>: override which gateway password the bootstrap flow authenticates against
  • --setup-code-only: print only setup code
  • --no-ascii: skip ASCII QR rendering
  • --json: emit JSON (setupCode, gatewayUrl, auth, urlSource)

Notes

  • --token and --password are mutually exclusive.
  • The setup code itself now carries an opaque short-lived bootstrapToken, not the shared gateway token/password.
  • In the built-in node/operator bootstrap flow, the primary node token still lands with scopes: [].
  • If bootstrap handoff also issues an operator token, it stays bounded to the bootstrap allowlist: operator.approvals, operator.read, operator.talk.secrets, operator.write.
  • Bootstrap scope checks are role-prefixed. That operator allowlist only satisfies operator requests; non-operator roles still need scopes under their own role prefix.
  • Mobile pairing fails closed for Tailscale/public ws:// gateway URLs. Private LAN ws:// remains supported, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a wss:// gateway URL.
  • With --remote, OpenClaw requires either gateway.remote.url or gateway.tailscale.mode=serve|funnel.
  • With --remote, if effectively active remote credentials are configured as SecretRefs and you do not pass --token or --password, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
  • Without --remote, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
    • gateway.auth.token resolves when token auth can win (explicit gateway.auth.mode="token" or inferred mode where no password source wins).
    • gateway.auth.password resolves when password auth can win (explicit gateway.auth.mode="password" or inferred mode with no winning token from auth/env).
  • If both gateway.auth.token and gateway.auth.password are configured (including SecretRefs) and gateway.auth.mode is unset, setup-code resolution fails until mode is set explicitly.
  • Gateway version skew note: this command path requires a gateway that supports secrets.resolve; older gateways return an unknown-method error.
  • After scanning, approve device pairing with:
    • openclaw devices list
    • openclaw devices approve <requestId>