openclaw qr CLI Reference: Generate Mobile Pairing QR and Setup Code

openclaw qr

From your current Gateway configuration, produce a mobile pairing QR and setup code.

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

The official OpenClaw iOS and Android applications connect automatically when their setup code metadata matches. For a request that stays pending (due to a non official client or mismatched metadata, for example), review it and grant approval:

openclaw devices list
openclaw devices approve <requestId>

Options

• --remote: uses gateway.remote.url as the preferred option; if that URL is not configured, it falls back to gateway.tailscale.mode=serve|funnel. The device-pair plugin publicUrl is disregarded.
• --url <url>: replace the gateway URL that appears inside the payload
• --public-url <url>: replace the public URL that appears inside the payload
• --token <token>: replace the gateway token used during bootstrap authentication
• --password <password>: replace the gateway password used during bootstrap authentication
• --limited: remove administrative Gateway access from the operator token that gets handed off
• --setup-code-only: output only the setup code
• --no-ascii: do not render the ASCII QR
• --json: produce JSON output (setupCode, gatewayUrl, optional gatewayUrls, auth, access, optional accessDowngraded, urlSource)

You cannot use --token and --password together.

Setup code contents

The setup code contains an opaque, short lived bootstrapToken rather than the shared gateway token or password. For a wss:// endpoint (or a loopback on the same host), the default bootstrap flow issues:

• a primary node token with scopes: []
• a full native mobile operator handoff token with operator.admin, operator.approvals, operator.read, operator.talk.secrets, and operator.write

To retain the same node token while excluding operator.admin from the operator handoff, use --limited. A setup code never hands off pairing mutation scope.

Plaintext LAN ws:// setup is still available, but OpenClaw automatically applies the limited profile because a network observer could capture and race the bearer bootstrap token. After configuring wss:// or Tailscale Serve, generate a new code to obtain full access.

Gateway URL resolution

For Tailscale or public ws:// gateway URLs, mobile pairing fails closed. In those cases, use Tailscale Serve/Funnel or a wss:// gateway URL. Private LAN addresses and .local Bonjour hosts remain supported over plain ws://, with limited operator access as described above.

When the chosen Gateway URL originates from gateway.bind=lan, OpenClaw also checks persistent tailscale serve status --json routes. Any HTTPS Serve root that proxies the active Gateway's loopback port is included as a fallback. The QR command adds this fallback only for lan; custom and tailnet keep their explicitly advertised routes. Current iOS clients probe the advertised routes in order and store the first one they can reach; the legacy url field stays unchanged for older clients.

With --remote, either gateway.remote.url or gateway.tailscale.mode=serve|funnel is mandatory.

Auth resolution (no --remote)

When no CLI auth override is provided, local gateway auth SecretRefs are resolved in this way:

Auth resolution (--remote)

When remote credentials active at runtime are specified as SecretRefs and neither --token nor --password is provided, the command resolves them from the current gateway snapshot. If the gateway is unreachable, the command fails immediately.

Note

This command path depends on a gateway that exposes the secrets.resolve RPC method. Older gateways respond with an unknown-method error.

Related

• CLI reference
• Devices
• Pairing