#21148: fix(gateway): add request-aware pairing recovery hints and docs

## Summary This PR improves the repair path when a gateway client fails handshake with `pairing required` during device scope upgrades. Closes #21146. ## What changed ### 1) Pairing close reason now includes request id In handshake pairing rejection, the gateway now closes with: - `pairing required (requestId: <id>)` instead of only `pairing required`. File: - `src/gateway/server/ws-connection/message-handler.ts` ### 2) CLI close error now prints direct repair commands Gateway close formatting now detects pairing-required reasons and appends concrete recovery guidance: - `openclaw devices approve <requestId>` when a request id is present - fallback `openclaw devices approve --latest` - `openclaw devices list` verification command File: - `src/gateway/call.ts` ### 3) Added tests for request-aware/fallback pairing hints New assertions verify both: - request-id aware hint path - fallback `--latest` hint path File: - `src/gateway/call.test.ts` ### 4) Expanded troubleshooting documentation Added a detailed runbook for: - pairing-required scope-upgrade loops - device token mismatch recovery - service token drift (config token vs service token) Files: - `docs/gateway/troubleshooting.md` - `docs/cli/devices.md` - `docs/web/control-ui.md` ## Validation - `pnpm -C /Users/maxime/openclaw exec vitest run src/gateway/call.test.ts` - `pnpm -C /Users/maxime/openclaw format:check` ## Why this helps Users now get immediate, actionable output for the most common repair path instead of a generic pairing failure loop. This reduces false “gateway is broken” diagnoses and shortens time-to-recovery. <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR enhances the pairing recovery flow by embedding request IDs in close reasons and providing actionable CLI hints when gateway connections fail due to pairing requirements. The gateway now closes with `pairing required (requestId: <id>)` instead of just `pairing required`, and the CLI formats this into concrete recovery commands like `openclaw devices approve <requestId>` or the fallback `openclaw devices approve --latest`. - Added request-aware pairing close reason in `message-handler.ts:700` - Implemented hint formatting logic with regex extraction in `call.ts:318-339` - Added comprehensive test coverage for both request-id and fallback paths - Expanded troubleshooting docs with detailed runbooks for pairing loops, token mismatches, and service token drift The implementation follows existing patterns, uses proper error formatting, and provides immediate value to users experiencing pairing failures. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk - The changes are well-isolated, focused on improving error messaging and documentation. The code modifications are minimal (3 lines changed in production code), follow existing patterns, include comprehensive test coverage for both code paths, and have been validated by the author. The regex extraction logic was independently verified to work correctly. Documentation additions are helpful and don't modify any behavior. - No files require special attention _{Last reviewed commit: 5dbabc4} <!-- greptile_other_comments_section --> _{(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!} <!-- /greptile_comment -->