feat: add one-step gateway setup pairing by Solvely-Colin · Pull Request #98263 · openclaw/openclaw

Solvely-Colin · 2026-06-30T20:12:54Z

Related: #98242
Supersedes the gateway half of #98243.

What Problem This Solves

Users setting up OpenClaw Mobile had to scan or paste a long setup code and then complete separate device/node approval steps. That made QR/setup-code onboarding feel like many steps instead of the intended one-step mobile setup.

Why This Change Was Made

This makes Setup Code and QR onboarding the primary one-step path: the app receives the Gateway URL/bootstrap auth from the setup-code payload, connects, and the Gateway silently approves only fresh baseline mobile device/node surfaces. The setup short code is a gateway-local convenience for typing the same setup-code payload on reachable local/co-resident Gateway flows; the long setup-code QR remains the durable fallback.

The node approval boundary is platform-specific for current iOS and Android app-declared capabilities/commands/permissions. Cross-platform, plugin, arbitrary, upgraded, or dangerous node command surfaces remain pending unless the Gateway owner explicitly allows them.

User Impact

A fresh mobile app can scan the QR or enter the setup code, save the Gateway URL/bootstrap auth, connect, receive bounded node/operator handoff tokens, and land connected without a separate manual approval step. Operators still get explicit pending approval flows for non-baseline or upgraded node surfaces.

Evidence

Physical iPhone + Tailscale QR proof succeeded locally: app connected; Gateway showed pending device/node counts at 0 after setup.
Redacted visual proof: https://gist.github.com/Solvely-Colin/0d647e2ffd90500925a062dc043d3764
node scripts/run-vitest.mjs src/gateway/server.auth.control-ui.test.ts --testNamePattern "qr setup code" passed: 7 tests, 33 skipped.
node scripts/run-vitest.mjs src/plugins/contracts/deprecated-internal-config-api.test.ts passed.
node scripts/run-vitest.mjs src/pairing/setup-short-code.test.ts src/gateway/server-http.probe.test.ts src/cli/qr-cli.test.ts passed: 3 shards, 4 + 28 + 25 tests.
node scripts/format-docs.mjs --check docs/cli/qr.md docs/channels/pairing.md docs/gateway/protocol.md docs/docs_map.md && node scripts/check-docs-mdx.mjs docs/cli/qr.md docs/channels/pairing.md docs/gateway/protocol.md docs/docs_map.md && node scripts/docs-link-audit.mjs docs/cli/qr.md docs/channels/pairing.md docs/gateway/protocol.md docs/docs_map.md && node scripts/generate-docs-map.mjs --check passed.
git diff --check && node scripts/run-oxlint.mjs src/pairing/setup-short-code.ts src/gateway/pairing-setup-short-code-http.ts src/gateway/server.auth.control-ui.suite.ts src/gateway/server/ws-connection/message-handler.ts && node scripts/check-deprecated-api-usage.mjs passed.
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.gateway-comments.tsbuildinfo passed.
.agents/skills/autoreview/scripts/autoreview --mode local --prompt "Review the PR #98263 final comment-response patch only..." clean: no accepted/actionable findings.
Crabbox/Testbox not run per request to skip Crabbox.

clawsweeper · 2026-06-30T20:14:04Z

Codex review: stale review; fresh review needed.

Summary
The latest durable ClawSweeper review was for head 23252947130bca60aeed755558ac870292ff78a6, but the PR head is now 45941eadc017a8eb45d58914d9e0f334e9d67de1. Its old verdict and PR readiness labels are no longer current.

Next step
Run or wait for a fresh ClawSweeper review on the current PR head.

Copilot

Pull request overview

Adds a one-step mobile pairing path by introducing gateway-local setup short codes that redeem into the existing setup-code payload, and extending the setup-code bootstrap flow to auto-approve baseline mobile device + first node pairing.

Changes:

Add a core plugin-state–backed short-code issuer/redeemer and expose a pre-auth HTTP redeem endpoint.
Extend gateway WS connect handling to auto-approve baseline mobile node pairing during setup-code bootstrap (and add suite coverage for the approval boundary).
Update openclaw qr output (text + JSON) and docs to include the short code and the new one-step behavior.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/pairing/setup-short-code.ts	Implements short-code issuance, normalization/formatting, and single-use redemption backed by plugin state.
src/pairing/setup-short-code.test.ts	Adds unit tests for issuing/redeeming, expiry behavior, and input normalization.
src/gateway/pairing-setup-short-code-http.ts	Adds the pre-auth HTTP handler for redeeming short codes into the setup payload with rate limiting.
src/gateway/server-http.ts	Routes `/api/v1/pairing/setup-code/redeem` to the new handler via lazy import.
src/gateway/auth-rate-limit.ts	Adds a dedicated rate-limit scope for setup short-code redemption attempts.
src/gateway/hooks-test-helpers.ts	Extends the HTTP request test fixture to support request bodies for JSON endpoints.
src/gateway/server-http.test-harness.ts	Plumbs request bodies through the gateway HTTP in-memory test harness.
src/gateway/server-http.probe.test.ts	Adds probe tests covering the redeem endpoint (success, one-time semantics, method checks, rate limiting).
src/gateway/server/ws-connection/message-handler.ts	Adds setup-code bootstrap-driven auto-approval for baseline mobile node pairing on connect.
src/gateway/server.auth.control-ui.suite.ts	Extends control-ui suite to cover node auto-approval for baseline mobile surfaces and pending behavior for upgrades.
src/cli/qr-cli.ts	Prints/registers short codes (where appropriate) and extends JSON output with optional short-code fields.
src/cli/qr-cli.test.ts	Covers CLI behavior for short-code registration, output rendering, and JSON field omission when unavailable.
docs/gateway/protocol.md	Documents one-step mobile bootstrap behavior and the short-code redeem endpoint contract.
docs/cli/qr.md	Documents new `openclaw qr` JSON fields, short-code semantics, and updated approval guidance.
docs/channels/pairing.md	Updates channel pairing docs to reflect one-step baseline mobile auto-approval and upgrade approval flow.

Solvely-Colin · 2026-06-30T20:40:45Z

Updated this PR at 23252947130 to address the review feedback.

What changed:

Kept the product path framed as Setup Code / QR onboarding; setup short code remains the optional gateway-local typing helper.
Replaced the short-code normalizer spread with a direct character loop for oxlint.
Regenerated docs/docs_map.md for the protocol/docs heading changes.
Removed the duplicate redeem-route helper from src/gateway/pairing-setup-short-code-http.ts; routing stays centralized in src/gateway/server-http.ts.
Tightened setup-code/QR mobile node auto-approval so dangerous commands require explicit gateway.nodes.allowCommands, while gateway.nodes.denyCommands still removes matching commands before auto-approval.

Proof on the pushed SHA:

node scripts/run-vitest.mjs src/gateway/server.auth.control-ui.test.ts --testNamePattern "qr setup code" passed: 7 tests, 33 skipped.
node scripts/run-vitest.mjs src/pairing/setup-short-code.test.ts src/gateway/server-http.probe.test.ts src/cli/qr-cli.test.ts passed: 3 shards, 4 + 28 + 25 tests.
node scripts/format-docs.mjs --check docs/cli/qr.md docs/channels/pairing.md docs/gateway/protocol.md docs/docs_map.md && node scripts/check-docs-mdx.mjs docs/cli/qr.md docs/channels/pairing.md docs/gateway/protocol.md docs/docs_map.md && node scripts/docs-link-audit.mjs docs/cli/qr.md docs/channels/pairing.md docs/gateway/protocol.md docs/docs_map.md && node scripts/generate-docs-map.mjs --check passed.
git diff --check && node scripts/run-oxlint.mjs src/pairing/setup-short-code.ts src/gateway/pairing-setup-short-code-http.ts src/gateway/server.auth.control-ui.suite.ts src/gateway/server/ws-connection/message-handler.ts passed.
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.gateway-comments.tsbuildinfo passed.
.agents/skills/autoreview/scripts/autoreview --mode local --prompt "Review the PR #98263 comment-response patch only..." clean: no accepted/actionable findings.

@clawsweeper re-review

clawsweeper · 2026-06-30T20:40:47Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Solvely-Colin · 2026-06-30T20:54:31Z

Updated this PR again at 45941eadc01 after CI exposed the deprecated config-write guard in the new gateway tests.

Delta since the previous review-response push:

Replaced the test-only writeConfigFile(...) usage in src/gateway/server.auth.control-ui.suite.ts with replaceConfigFile({ nextConfig }).
Verified that both failed CI lanes had the same root cause: checks-fast-contracts-plugins-b failed deprecated-internal-config-api.test.ts, and check-additional-runtime-topology-architecture failed check-deprecated-api-usage.mjs on the same file/import.

Current proof on the final local patch:

node scripts/run-vitest.mjs src/gateway/server.auth.control-ui.test.ts --testNamePattern "qr setup code" passed: 7 tests, 33 skipped.
node scripts/run-vitest.mjs src/plugins/contracts/deprecated-internal-config-api.test.ts passed.
node scripts/run-vitest.mjs src/pairing/setup-short-code.test.ts src/gateway/server-http.probe.test.ts src/cli/qr-cli.test.ts passed: 3 shards, 4 + 28 + 25 tests.
git diff --check && node scripts/run-oxlint.mjs src/pairing/setup-short-code.ts src/gateway/pairing-setup-short-code-http.ts src/gateway/server.auth.control-ui.suite.ts src/gateway/server/ws-connection/message-handler.ts && node scripts/check-deprecated-api-usage.mjs passed.
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.gateway-comments.tsbuildinfo passed.
.agents/skills/autoreview/scripts/autoreview --mode local --prompt "Review the PR #98263 final comment-response patch only..." clean: no accepted/actionable findings.

The PR is still Setup Code / QR first; setup short code is the optional gateway-local typing helper.

@clawsweeper re-review

clawsweeper · 2026-06-30T20:54:35Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Solvely-Colin requested a review from a team as a code owner June 30, 2026 20:12

Copilot AI review requested due to automatic review settings June 30, 2026 20:12

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime cli CLI command changes size: XL maintainer Maintainer-authored PR labels Jun 30, 2026

Copilot started reviewing on behalf of Solvely-Colin June 30, 2026 20:13 View session

This was referenced Jun 30, 2026

feat(ios): redeem gateway setup short codes #98265

Closed

feat: make mobile setup-code pairing one step #98243

Closed

[Feature]: One-step mobile QR/setup-code pairing #98242

Open

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread src/gateway/server/ws-connection/message-handler.ts

Comment thread src/gateway/pairing-setup-short-code-http.ts Outdated

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels Jun 30, 2026

Solvely-Colin force-pushed the codex/gateway-qr-setup-autopair branch from 623f361 to 2325294 Compare June 30, 2026 20:39

feat: add one-step gateway setup pairing

45941ea

Solvely-Colin force-pushed the codex/gateway-qr-setup-autopair branch from 2325294 to 45941ea Compare June 30, 2026 20:54

clawsweeper Bot removed the status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. label Jun 30, 2026

clawsweeper Bot mentioned this pull request Jun 30, 2026

fix(android): require setup code for first-run gateway pairing #98275

Closed

This was referenced Jul 5, 2026

fix: mobile pairing should advertise usable LAN and Tailnet routes #100280

Closed

[Feature]: openclaw invite — shareable invite codes for mobile pairing #55914

Open

Solvely-Colin closed this Jul 16, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: add one-step gateway setup pairing#98263

feat: add one-step gateway setup pairing#98263
Solvely-Colin wants to merge 1 commit into
mainfrom
codex/gateway-qr-setup-autopair

Solvely-Colin commented Jun 30, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Solvely-Colin commented Jun 30, 2026

Uh oh!

clawsweeper Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

Solvely-Colin commented Jun 30, 2026

Uh oh!

clawsweeper Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

Solvely-Colin commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Solvely-Colin commented Jun 30, 2026

Uh oh!

clawsweeper Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Solvely-Colin commented Jun 30, 2026

Uh oh!

clawsweeper Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Solvely-Colin commented Jun 30, 2026 •

edited

Loading

clawsweeper Bot commented Jun 30, 2026 •

edited

Loading

clawsweeper Bot commented Jun 30, 2026 •

edited

Loading

clawsweeper Bot commented Jun 30, 2026 •

edited

Loading