openclaw
diff --git a/‎docs/channels/pairing.md‎
Lines changed: 15 additions & 5 deletions b/‎docs/channels/pairing.md‎
Lines changed: 15 additions & 5 deletions
diff --git a/‎docs/cli/qr.md‎
Lines changed: 7 additions & 3 deletions b/‎docs/cli/qr.md‎
Lines changed: 7 additions & 3 deletions
diff --git a/‎docs/gateway/protocol.md‎
Lines changed: 34 additions & 0 deletions b/‎docs/gateway/protocol.md‎
Lines changed: 34 additions & 0 deletions
diff --git a/‎src/cli/qr-cli.test.ts‎
Lines changed: 79 additions & 0 deletions b/‎src/cli/qr-cli.test.ts‎
Lines changed: 79 additions & 0 deletions
diff --git a/‎src/cli/qr-cli.ts‎
Lines changed: 48 additions & 1 deletion b/‎src/cli/qr-cli.ts‎
Lines changed: 48 additions & 1 deletion
diff --git a/‎src/gateway/auth-rate-limit.ts‎
Lines changed: 1 addition & 0 deletions b/‎src/gateway/auth-rate-limit.ts‎
Lines changed: 1 addition & 0 deletions
@@ -113,8 +113,12 @@ If you use the `device-pair` plugin, you can do first-time device pairing entire
 1. In Telegram, message your bot: `/pair`
 2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
 3. On your phone, open the OpenClaw iOS app → Settings → Gateway.
-4. Scan the QR code or paste the setup code and connect.
-5. Back in Telegram: `/pair pending` (review request IDs, role, and scopes), then approve.
+4. Scan the QR code or paste the setup code and connect. For the built-in
+   setup-code mobile baseline, the Gateway silently approves the fresh mobile
+   device and its node pairing during the bootstrap handshake.
+5. Back in Telegram: `/pair pending` only if the app reports a pending repair or
+   upgrade. Review request IDs, role, scopes, and capability changes before
+   approving.
 
 The setup code is a base64-encoded JSON payload that contains:
 
@@ -127,26 +131,32 @@ That bootstrap token carries the built-in pairing bootstrap profile:
   `node` plus a bounded `operator` handoff
 - the handed-off `node` token stays `scopes: []`
 - the handed-off `operator` token is limited to `operator.approvals`,
-  `operator.read`, and `operator.write`
+  `operator.read`, `operator.talk.secrets`, and `operator.write`
 - `operator.admin` and `operator.pairing` are not granted by QR/setup-code
   bootstrap; they require a separate approved operator pairing or token flow
 - later token rotation/revocation remains bounded by both the device's approved
   role contract and the caller session's operator scopes
 
-Treat the setup code like a password while it is valid.
+Treat the setup code like a password while it is valid. `openclaw qr` also
+prints an 8-character setup short code. The short code is a 5-minute, single-use
+pointer to the same setup-code payload on that Gateway. A QR/setup code carries
+the Gateway URL directly; a bare short code still requires the app to know which
+Gateway host to redeem against.
 
 For Tailscale, public, or other remote mobile pairing, use Tailscale Serve/Funnel
 or another `wss://` Gateway URL. Plaintext `ws://` setup codes are accepted only
 for loopback, private LAN addresses, `.local` Bonjour hosts, and the Android
 emulator host. Tailnet CGNAT addresses, `.ts.net` names, and public hosts still
 fail closed before QR/setup-code issuance.
 
-### Approve a node device
+### Approve a node device or upgrade
 
 ```bash
 openclaw devices list
 openclaw devices approve <requestId>
 openclaw devices reject <requestId>
+openclaw nodes pending
+openclaw nodes approve <requestId>
 ```
 
 When an explicit approval is denied because the approving paired-device session
 
@@ -29,14 +29,17 @@ openclaw qr --url wss://gateway.example/ws
 - `--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`)
+- `--json`: emit JSON (`setupCode`, optional `shortCode`/`shortCodeExpiresAtMs`, `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.
+- Normal QR/setup-code mobile onboarding is one step: scan the QR or paste the setup code, then the app connects with bootstrap auth and the Gateway silently approves the fresh baseline mobile device plus its node pairing.
+- `openclaw qr` also prints an 8-character setup short code. The short code is a 5-minute, single-use pointer to the same setup-code payload on that Gateway. A bare short code still needs the app to know which Gateway host to redeem against; the QR/setup code carries the Gateway URL directly.
 - 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`; `operator.admin` and `operator.pairing` require a separate approved operator pairing or token flow.
+- Auto-approval is limited to the fresh setup-code mobile baseline. Later role, scope, metadata, or node capability upgrades still create pending requests that require explicit approval.
 - 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`.
@@ -46,9 +49,10 @@ openclaw qr --url wss://gateway.example/ws
   - `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:
+- If onboarding reports a pending repair or upgrade instead of connecting, review it with:
   - `openclaw devices list`
-  - `openclaw devices approve <requestId>`
+  - `openclaw nodes pending`
+  - `openclaw devices approve <requestId>` or `openclaw nodes approve <requestId>`
 
 ## Related
 
 
@@ -177,6 +177,40 @@ a separate approved operator pairing or token flow. Clients should persist
 when the connect used bootstrap auth on trusted transport such as `wss://` or
 loopback/local pairing.
 
+For current native onboarding, that same baseline setup-code bootstrap can also
+silently approve the fresh mobile device and its first node pairing. This is
+limited to the built-in setup profile and mobile client metadata. Later role,
+scope, device metadata, or node capability changes still create pending pairing
+requests for explicit review.
+
+### Setup Short-Code Redeem
+
+`POST /api/v1/pairing/setup-code/redeem` redeems the 8-character setup short
+code printed by `openclaw qr` into the canonical setup-code payload:
+
+```json
+{ "code": "ABCD2345" }
+```
+
+Success:
+
+```json
+{
+  "ok": true,
+  "payload": {
+    "url": "wss://gateway.example.com",
+    "bootstrapToken": "…"
+  },
+  "expiresAtMs": 1737264300000
+}
+```
+
+The endpoint is intentionally pre-auth so a fresh mobile app can redeem a code.
+The short code is single-use, expires after 5 minutes, is rate-limited per
+client IP, and points only to the same setup-code payload that the QR/setup-code
+path would have carried. It does not expose the long-lived shared Gateway token
+or password by default.
+
 ### Node example
 
 ```json
 
@@ -12,6 +12,13 @@ const mocks = vi.hoisted(() => ({
     diagnostics: [] as string[],
   })),
   renderTerminal: vi.fn(async () => "ASCII-QR"),
+  registerShortCode: vi.fn(() => ({
+    ok: true as const,
+    code: "ABCD2345",
+    expiresAtMs: 456,
+    authLabel: "token" as const,
+    urlSource: "test",
+  })),
 }));
 const { defaultRuntime: runtime, resetRuntimeCapture } = createCliRuntimeCapture();
 const runtimeLog = runtime.log;
@@ -32,6 +39,10 @@ vi.mock("../process/exec.js", () => ({ runCommandWithTimeout: mocks.runCommandWi
 vi.mock("../media/qr-terminal.ts", () => ({
   renderQrTerminal: mocks.renderTerminal,
 }));
+vi.mock("../pairing/setup-short-code.js", () => ({
+  formatPairingSetupShortCode: (code: string) => `${code.slice(0, 4)}-${code.slice(4)}`,
+  registerPairingSetupShortCode: mocks.registerShortCode,
+}));
 vi.mock("./command-secret-gateway.js", () => ({
   resolveCommandSecretRefsViaGateway: mocks.resolveCommandSecretRefsViaGateway,
 }));
@@ -45,6 +56,7 @@ const loadConfig = mocks.loadConfig;
 const runCommandWithTimeout = mocks.runCommandWithTimeout;
 const resolveCommandSecretRefsViaGateway = mocks.resolveCommandSecretRefsViaGateway;
 const renderTerminal = mocks.renderTerminal;
+const registerShortCode = mocks.registerShortCode;
 
 const { registerQrCli } = await import("./qr-cli.js");
 
@@ -140,6 +152,8 @@ describe("registerQrCli", () => {
     const raw = calls[calls.length - 1]?.[0];
     return JSON.parse(typeof raw === "string" ? raw : "{}") as {
       setupCode?: string;
+      shortCode?: string;
+      shortCodeExpiresAtMs?: number;
       gatewayUrl?: string;
       auth?: string;
       urlSource?: string;
@@ -197,6 +211,7 @@ describe("registerQrCli", () => {
     });
     expect(runtime.log).toHaveBeenCalledWith(expected);
     expect(renderTerminal).not.toHaveBeenCalled();
+    expect(registerShortCode).not.toHaveBeenCalled();
     expect(resolveCommandSecretRefsViaGateway).not.toHaveBeenCalled();
   });
 
@@ -215,8 +230,66 @@ describe("registerQrCli", () => {
     const output = runtimeLog.mock.calls.map((call) => readRuntimeCallText(call)).join("\n");
     expect(output).toContain("Pairing QR");
     expect(output).toContain("ASCII-QR");
+    expect(output).toContain("Short code:");
+    expect(output).toContain("ABCD-2345");
     expect(output).toContain("Gateway:");
+    expect(output).toContain("Fresh mobile setup auto-approves");
+    expect(output).toContain("openclaw nodes pending");
     expect(output).toContain("openclaw devices approve <requestId>");
+    expect(output).toContain("openclaw nodes approve <requestId>");
+    expect(registerShortCode).toHaveBeenCalledWith({
+      payload: {
+        url: "ws://127.0.0.1:18789",
+        bootstrapToken: "bootstrap-123",
+      },
+      authLabel: "token",
+      urlSource: "gateway.bind=custom",
+    });
+  });
+
+  it("still prints the setup QR when short-code registration is unavailable", async () => {
+    loadConfig.mockReturnValue({
+      gateway: {
+        bind: "custom",
+        customBindHost: "127.0.0.1",
+        auth: { mode: "token", token: "tok" },
+      },
+    });
+    registerShortCode.mockImplementationOnce(() => {
+      throw new Error("state unavailable");
+    });
+
+    await runQr([]);
+
+    expect(renderTerminal).toHaveBeenCalledTimes(1);
+    const output = runtimeLog.mock.calls.map((call) => readRuntimeCallText(call)).join("\n");
+    expect(output).toContain("Pairing QR");
+    expect(output).toContain("ASCII-QR");
+    expect(output).toContain("Short code:");
+    expect(output).toContain("unavailable");
+    expect(output).toContain("Setup code:");
+    expect(output).toContain("Gateway:");
+  });
+
+  it("omits unavailable short-code fields from json output", async () => {
+    loadConfig.mockReturnValue({
+      gateway: {
+        bind: "custom",
+        customBindHost: "127.0.0.1",
+        auth: { mode: "token", token: "tok" },
+      },
+    });
+    registerShortCode.mockImplementationOnce(() => {
+      throw new Error("state unavailable");
+    });
+
+    await runQr(["--json"]);
+
+    const payload = parseLastLoggedQrJson();
+    expect(payload.setupCode).toBeTruthy();
+    expect(payload.gatewayUrl).toBe("ws://127.0.0.1:18789");
+    expect(payload.shortCode).toBeUndefined();
+    expect(payload.shortCodeExpiresAtMs).toBeUndefined();
   });
 
   it("fails fast for insecure remote mobile pairing setup urls", async () => {
@@ -482,8 +555,11 @@ describe("registerQrCli", () => {
 
     const payload = parseLastLoggedQrJson();
     expect(payload.gatewayUrl).toBe("wss://remote.example.com:444");
+    expect(payload.shortCode).toBeUndefined();
+    expect(payload.shortCodeExpiresAtMs).toBeUndefined();
     expect(payload.auth).toBe("token");
     expect(payload.urlSource).toBe("gateway.remote.url");
+    expect(registerShortCode).not.toHaveBeenCalled();
     expect(runCommandWithTimeout).not.toHaveBeenCalled();
   });
 
@@ -545,7 +621,10 @@ describe("registerQrCli", () => {
 
     const payload = parseLastLoggedQrJson();
     expect(payload.gatewayUrl).toBe("wss://ts-host.tailnet.ts.net");
+    expect(payload.shortCode).toBe("ABCD2345");
+    expect(payload.shortCodeExpiresAtMs).toBe(456);
     expect(payload.auth).toBe("token");
     expect(payload.urlSource).toBe("gateway.tailscale.mode=serve");
+    expect(registerShortCode).toHaveBeenCalled();
   });
 });
@@ -9,6 +9,11 @@ import { trimToUndefined } from "../gateway/credentials.js";
 import { resolveRequiredConfiguredSecretRefInputString } from "../gateway/resolve-configured-secret-input-string.js";
 import { renderQrTerminal } from "../media/qr-terminal.ts";
 import { resolvePairingSetupFromConfig, encodePairingSetupCode } from "../pairing/setup-code.js";
+import {
+  formatPairingSetupShortCode,
+  registerPairingSetupShortCode,
+  type PairingSetupShortCodeIssueResult,
+} from "../pairing/setup-short-code.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 import { defaultRuntime } from "../runtime.js";
 import { resolveCommandSecretRefsViaGateway } from "./command-secret-gateway.js";
@@ -28,6 +33,31 @@ type QrCliOptions = {
 function renderQrAscii(data: string): Promise<string> {
   return renderQrTerminal(data);
 }
+
+function tryRegisterPairingSetupShortCode(
+  params: Parameters<typeof registerPairingSetupShortCode>[0],
+): PairingSetupShortCodeIssueResult {
+  try {
+    return registerPairingSetupShortCode(params);
+  } catch {
+    return { ok: false, error: "short code unavailable" };
+  }
+}
+
+function shouldRegisterPairingSetupShortCode(params: {
+  explicitUrl?: string;
+  urlSource: string;
+}): boolean {
+  if (params.explicitUrl) {
+    return false;
+  }
+  return (
+    params.urlSource.startsWith("gateway.bind=") ||
+    params.urlSource.startsWith("gateway.tailscale.mode=") ||
+    params.urlSource === "plugins.entries.device-pair.config.publicUrl"
+  );
+}
+
 function readDevicePairPublicUrlFromConfig(cfg: OpenClawConfig): string | undefined {
   const value = cfg.plugins?.entries?.["device-pair"]?.config?.["publicUrl"];
   if (typeof value !== "string") {
@@ -216,9 +246,22 @@ export function registerQrCli(program: Command) {
           return;
         }
 
+        const shortCode = shouldRegisterPairingSetupShortCode({
+          explicitUrl,
+          urlSource: resolved.urlSource,
+        })
+          ? tryRegisterPairingSetupShortCode({
+              payload: resolved.payload,
+              authLabel: resolved.authLabel,
+              urlSource: resolved.urlSource,
+            })
+          : ({ ok: false, error: "short code unavailable" } satisfies PairingSetupShortCodeIssueResult);
+
         if (opts.json) {
           defaultRuntime.writeJson({
             setupCode,
+            shortCode: shortCode.ok ? shortCode.code : undefined,
+            shortCodeExpiresAtMs: shortCode.ok ? shortCode.expiresAtMs : undefined,
             gatewayUrl: resolved.payload.url,
             auth: resolved.authLabel,
             urlSource: resolved.urlSource,
@@ -238,14 +281,18 @@ export function registerQrCli(program: Command) {
         }
 
         lines.push(
+          `${theme.muted("Short code:")} ${shortCode.ok ? formatPairingSetupShortCode(shortCode.code) : "unavailable"}`,
           `${theme.muted("Setup code:")} ${setupCode}`,
           `${theme.muted("Gateway:")} ${resolved.payload.url}`,
           `${theme.muted("Auth:")} ${resolved.authLabel}`,
           `${theme.muted("Source:")} ${resolved.urlSource}`,
           "",
-          "Approve after scan with:",
+          "Fresh mobile setup auto-approves the baseline device and node.",
+          "If an upgraded surface remains pending:",
           `  ${theme.command("openclaw devices list")}`,
+          `  ${theme.command("openclaw nodes pending")}`,
           `  ${theme.command("openclaw devices approve <requestId>")}`,
+          `  ${theme.command("openclaw nodes approve <requestId>")}`,
         );
 
         defaultRuntime.log(lines.join("\n"));
 
@@ -55,6 +55,7 @@ export const AUTH_RATE_LIMIT_SCOPE_NODE_REAPPROVAL = "node-reapproval";
 // device signature can queue the bootstrap-pairing flow behind their
 // requests, blocking legitimate node onboarding during the attack.
 export const AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN = "bootstrap-token";
+export const AUTH_RATE_LIMIT_SCOPE_PAIRING_SETUP_SHORT_CODE = "pairing-setup-short-code";
 export const AUTH_RATE_LIMIT_SCOPE_HOOK_AUTH = "hook-auth";
 const BROWSER_ORIGIN_RATE_LIMIT_KEY_PREFIX = "browser-origin:";
 const IDENTITY_RATE_LIMIT_KEY_PREFIX = "identity:";