← Back to PRs

#23678: fix(ui): Control UI shows no guidance on 1008 pairing required (#23663)

by yinghaosang open 2026-02-22 15:45 View on GitHub →
app: web-ui size: S trusted-contributor
## 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