How to Use OpenClaw QR Pairing for Mobile Nodes

openclaw qr is the fast path for pairing a mobile node app with a Gateway. It generates a QR code and setup code from your current Gateway configuration, including the URL and auth material needed for the bootstrap flow. Use it when you want a phone or tablet node connected without hand-writing a setup payload.

Basic commands

The default command renders the pairing flow. If you are sending setup details through a safer manual channel, print only the setup code. If you are automating or building a small internal helper, use JSON output.

openclaw qr
openclaw qr --setup-code-only
openclaw qr --json

Local versus remote pairing

For remote pairing, the docs expose --remote and URL overrides. With --remote, OpenClaw prefers gateway.remote.url; if that is unset, gateway.tailscale.mode=serve|funnel can still provide the remote public URL. Without an available remote URL, remote mode fails instead of guessing.

openclaw qr --remote
openclaw qr --url wss://gateway.example/ws
openclaw qr --public-url https://gateway.example

The mobile security note is important: pairing fails closed for Tailscale/public ws:// gateway URLs. Private LAN ws:// remains supported, but Tailscale or public mobile routes should use Tailscale Serve/Funnel or a wss:// gateway URL.

Token and password options

The QR command can override token or password, but the docs say --token and --password are mutually exclusive. Without overrides, SecretRefs can be resolved from the active gateway snapshot when possible. If both token and password auth sources are configured and auth mode is unset, setup-code resolution fails until the mode is explicit. That failure is good; ambiguous auth should not silently pick a secret.

Approve the device

Generating the QR is not the whole pairing process. After scanning, approve the device pairing request from the CLI. That keeps the Gateway from accepting arbitrary nodes just because they saw a setup screen.

openclaw devices list
openclaw devices approve <requestId>

My operator advice: generate QR codes only when the person pairing the device is ready, prefer short-lived setup codes over screenshots, and avoid posting QR payloads in broad channels. Pairing data is operationally sensitive even when the bootstrap token is opaque and short-lived.

If you are turning mobile node pairing into real operations instead of a demo, The OpenClaw Playbook is the shortcut I wish every operator had: identity files, memory rules, safety boundaries, channel discipline, and production habits in one field-tested guide.

Secure handoff

A setup code is easier to share than a QR screenshot, but both should be treated as temporary pairing material. Generate it when the device owner is ready, use the narrowest transport you trust, and avoid leaving the payload in shared chat history. Pairing is supposed to be convenient, not ambient.

After approval

Approving the device is only the start. Send a low-risk command or presence check through the node path, confirm the reported capabilities match the device you expected, and then write down the device name or role. That prevents future confusion when multiple mobile nodes are paired to the same gateway.

Runbook detail

For How to Use OpenClaw QR Pairing for Mobile Nodes, the important operator move is to record the exact documented surface you used and the condition that proves it worked. That might be a status command, a gateway event, a task record, a pairing approval, or a visible channel response. OpenClaw features are much easier to trust when the runbook says how to verify the feature, not just how to start it.

Operator checkpoint

Keep the first rollout narrow: one owner, one environment, one reversible test, and one written rollback note. Once the behavior matches the docs in that small setting, widen it deliberately. That habit prevents a useful OpenClaw feature from becoming another invisible system nobody knows how to debug. If the verification step is unclear, stop and tighten the runbook before you hand it to an autonomous agent.