#22712: fix(gateway): auto-approve all device pairing for localhost connections
gateway
size: XS
Cluster:
Device Pairing and Gateway Fixes
Fixes #22688
## Problem
CLI tools like `openclaw tui` and `openclaw gateway status` were stuck in an infinite "pairing required" loop when using token auth mode, even from localhost. The gateway auto-approved initial device pairing but required manual approval for scope/role upgrades, causing CLI tools to fail when requesting elevated scopes.
## Root Cause
Device pairing auto-approval was conditional on both `isLocalClient` AND `reason === 'not-paired'`. Subsequent connections with scope upgrades (`reason === 'scope-upgrade'` or `'role-upgrade'`) required manual pairing approval even from localhost.
## Solution
Changed silent pairing condition from:
```typescript
silent: isLocalClient && reason === "not-paired"
```
to:
```typescript
silent: isLocalClient
```
This auto-approves ALL device pairing requests from localhost (initial pairing, role upgrades, scope upgrades), eliminating the pairing loop for local CLI tools while maintaining security for remote connections.
## Testing
- Updated test "requires pairing for scope upgrades" to "auto-approves scope upgrades for local clients"
- Test now expects scope upgrade to succeed immediately for localhost
- All quality gate checks pass:
- ✅ pnpm build
- ✅ pnpm tsgo
- ✅ pnpm lint
- ✅ pnpm test
## Files Changed
- `src/gateway/server/ws-connection/message-handler.ts`: Updated silent pairing logic
- `src/gateway/server.auth.e2e.test.ts`: Updated test expectations
---
*AI-assisted contribution*
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Changed silent pairing condition to auto-approve all device pairing requests from localhost (initial pairing, role upgrades, scope upgrades), fixing an infinite pairing loop for CLI tools while maintaining security for remote connections.
- Simplified `silent` pairing logic in `message-handler.ts:737` from `isLocalClient && reason === "not-paired"` to just `isLocalClient`
- Updated test expectations to verify scope upgrades now succeed immediately for local clients
- Security boundary properly maintained: `isLocalClient` returns false for connections with proxy headers (like `x-forwarded-for`) unless from trusted proxies, ensuring remote connections still require manual pairing approval
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The change correctly solves the CLI tool pairing issue by simplifying the auto-approval logic for localhost connections. Security is maintained because `isLocalClient` properly validates that connections are truly local (checks client IP is loopback AND verifies no proxy headers or only trusted proxies). The existing test on line 746 confirms remote connections still require pairing. Test updates are appropriate and all quality gates pass.
- No files require special attention
<sub>Last reviewed commit: b180dd8</sub>
<!-- greptile_other_comments_section -->
<sub>(5/5) You can turn off certain types of comments like style [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#17425: fix(gateway): auto-approve scope/role upgrades for already-paired d...
by sauerdaniel · 2026-02-15
91.5%
#22280: fix(gateway): silently auto-approve local paired-device scope upgrades
by abhishekp76 · 2026-02-21
90.5%
#22587: fix(gateway): silently auto-approve local paired-device scope upgrades
by abhishekp76 · 2026-02-21
89.5%
#23708: fix(gateway): auto-approve scope upgrades for loopback clients
by widingmarcus-cyber · 2026-02-22
88.4%
#22794: fix: allow local clients to auto-pair without manual approval
by Matrix-Meta · 2026-02-21
86.4%
#23690: fix(gateway): subagent sessions fail with pairing required on loopb...
by yinghaosang · 2026-02-22
86.0%
#22365: fix(gateway): auto-approve loopback scope upgrades
by AIflow-Labs · 2026-02-21
85.9%
#21666: fix(gateway): restrict auto-paired device scopes to safe defaults
by AI-Reviewer-QS · 2026-02-20
85.2%
#16310: fix(ws-connection): skip device pairing when client authenticates w...
by nawinsharma · 2026-02-14
84.8%
#22253: fix: auto-approve local loopback pairing for role/scope upgrades
by cjpraia · 2026-02-20
84.8%