mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-08 20:13:59 +00:00
129e0a8cf0
* feat(gateway): add device.pair.setupCode RPC for connect QR
The OpenClaw mobile/companion app scans a pairing setup code to connect to the gateway, but that code + QR could only be produced by the openclaw qr CLI (ASCII to stdout). Non-terminal clients driving onboarding had no way to display the connect QR.
Add a device.pair.setupCode gateway method that reuses resolvePairingSetupFromConfig + encodePairingSetupCode + renderQrPngDataUrl to return { setupCode, qrDataUrl?, gatewayUrl, auth, urlSource }. The embedded setup code mints a short-lived bootstrap token that hands off broad operator scopes (read/write/approvals/talk.secrets), so the method requires operator.admin (matching the wizard methods a companion already uses) and is not advertised. auth is a label only; the gateway credential is never returned, and an oversized QR is omitted so the response always satisfies the result schema.
Refs #94661.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(ui): pair mobile devices from Control UI
* docs: refresh generated docs map
* docs: clarify mobile QR auto-connect
* docs: clarify mobile QR auto-connect
* docs: clarify mobile QR auto-connect
---------
Co-authored-by: Barbara Kudiess <76582160+bkudiess@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw qr` (generate mobile pairing QR + setup code)"
|
|
read_when:
|
|
- You want to pair a mobile node app with a gateway quickly
|
|
- You need setup-code output for remote/manual sharing
|
|
title: "QR"
|
|
---
|
|
|
|
# `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.
|
|
- Built-in setup-code bootstrap returns a primary `node` token with `scopes: []` plus a bounded `operator` handoff token for trusted mobile onboarding.
|
|
- The handed-off operator token is limited to `operator.approvals`, `operator.read`, `operator.talk.secrets`, and `operator.write`; pairing mutation scopes and `operator.admin` still require a separate approved operator pairing or token flow.
|
|
- Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN addresses and `.local` Bonjour hosts remain supported over `ws://`, 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.
|
|
- Official OpenClaw iOS and Android apps connect automatically when their
|
|
setup-code metadata matches. If a request remains pending (for example, for a
|
|
non-official client or mismatched metadata), review and approve it with:
|
|
- `openclaw devices list`
|
|
- `openclaw devices approve <requestId>`
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|
|
- [Pairing](/cli/pairing)
|