| --- |
| summary: "CLI reference for `openclaw qr` (generate iOS pairing QR + setup code)" |
| read_when: |
| - You want to pair the iOS app with a gateway quickly |
| - You need setup-code output for remote/manual sharing |
| title: "qr" |
| --- |
| |
| # `openclaw qr` |
|
|
| Generate an iOS 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`: use `gateway.remote.url` plus remote token/password from config |
| - `--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. |
| - 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>` |
|
|
