#23678: fix(ui): Control UI shows no guidance on 1008 pairing required (#23663)
app: web-ui
size: S
trusted-contributor
Cluster:
Device Pairing and Gateway Fixes
## Summary
When the Control UI gets a `1008: pairing required` disconnect, it shows the raw error string with no guidance on what to do. The `authHint` in `overview.ts` only matches "unauthorized" and "connect failed" — it doesn't handle "pairing required" at all. So mobile users (or anyone hitting the UI from a new device) just see a cryptic error and have no idea they need to run `openclaw devices approve`.
Closes #23663
lobster-biscuit
## Root Cause
`renderOverview` in `overview.ts` has an `authHint` IIFE that checks for "unauthorized" or "connect failed" in `lastError`, but there's no branch for "pairing required". The TUI already got this guidance (see changelog), but the Control UI never did.
## Changes
- Before: `disconnected (1008): pairing required` shown with no hint — user is stuck
- After: pairing hint shows `openclaw devices list` / `openclaw devices approve <requestId>`, plus a note for mobile users to copy the full tokenized URL, with a link to the pairing docs
Added `shouldShowPairingHint` in a separate `overview-hints.ts` file (no browser deps) so it's testable in node. i18n keys added for all four locales (en, zh-CN, zh-TW, pt-BR).
## Tests
- `overview.node.test.ts` — 6 tests covering the hint matching logic (true for pairing errors, false for auth/unrelated/connected/null)
- `pnpm build && pnpm check` pass
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR adds pairing guidance to the Control UI when users hit a `1008: pairing required` disconnect error. Previously, the UI showed only the cryptic error with no actionable steps. The fix mirrors the TUI's existing pairing hint (added in #21841) by displaying instructions to run `openclaw devices list` and `openclaw devices approve <requestId>`, plus a mobile-specific note about copying the full tokenized URL.
**Key changes:**
- Extracted pairing hint logic to `overview-hints.ts` (testable in Node, no browser deps)
- Added `pairingHint` IIFE in `overview.ts` that renders when `shouldShowPairingHint` returns true
- Added i18n keys `overview.pairing.hint` and `overview.pairing.mobileHint` across all 4 locales
- 6 unit tests cover hint matching (true for pairing errors, false for auth/unrelated/connected/null)
- Links to docs at `https://docs.openclaw.ai/web/control-ui#device-pairing-first-connection`
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with no risks identified
- Clean, focused fix with comprehensive test coverage (6 test cases), proper i18n for all locales, and consistent with existing TUI pattern. Logic is straightforward (case-insensitive string match), properly extracted for testability, and follows repo conventions.
- No files require special attention
<sub>Last reviewed commit: 54dadf2</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#20456: fix(control-ui): show device pairing approval prompt when a new dev...
by mmaghsoodnia · 2026-02-18
82.0%
#11868: control-ui: pairing required guided flow (Clairephone V2 Candidate A)
by shojikumaru · 2026-02-08
80.3%
#22712: fix(gateway): auto-approve all device pairing for localhost connect...
by NewdlDewdl · 2026-02-21
79.2%
#6846: fix: bridge node.pair.* tools to device pairing store
by cortexuvula · 2026-02-02
79.0%
#22262: fix(gateway): add pairing-repair command hint on 1008 connect failures
by karimnaguib · 2026-02-20
78.9%
#17425: fix(gateway): auto-approve scope/role upgrades for already-paired d...
by sauerdaniel · 2026-02-15
78.3%
#23798: docs: add Docker pairing cross-reference to Control UI page
by dglewis · 2026-02-22
77.4%
#21148: fix(gateway): add request-aware pairing recovery hints and docs
by cluster2600 · 2026-02-19
76.5%
#3744: Gateway: fix device pairing when local connection retries with exis...
by photon3710 · 2026-01-29
76.0%
#17605: fix: preserve scopes when disableControlUiDeviceAuth is enabled
by MisterGuy420 · 2026-02-16
75.8%