PR #55113: FIX (gateway): skip device pairing for authenticated CLI connections in Docker

• Repository: openclaw/openclaw
• Author: sar618
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/55113

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Docker CLI commands fail with pairing required (1008) because shouldSkipBackendSelfPairing only matches gateway-client/backend mode. CLI connections use cli/cli mode and are excluded.
• Problem (secondary): isLocalDirectRequest returns false in Docker even when remoteAddress is 127.0.0.1, so the locality check fails as a second blocker.
• Why it matters: Every Docker deployment using CLI commands hits this. At least 12 issues report the same root cause (#2284, #4531, #4941, #6959, #9028, #12210, #19352, #20707, #23471, #30740, #42931, #45232). Users are forced to abandon Docker or lose CLI access entirely.
• What changed: handshake-auth-helpers.ts — extend shouldSkipBackendSelfPairing to match cli/cli clients. For CLI connections with valid shared auth (token/password), skip the locality check since the token is the trust anchor.
• What did NOT change (scope boundary): Pairing behavior for external clients (Control UI, mobile apps, nodes); backend self-connection locality requirement; auth validation logic; TLS checks.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #55067
• Related #12210, #23471, #30740, #30801
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: shouldSkipBackendSelfPairing gates on GATEWAY_CLIENT_IDS.GATEWAY_CLIENT + GATEWAY_CLIENT_MODES.BACKEND. CLI connections send GATEWAY_CLIENT_IDS.CLI + GATEWAY_CLIENT_MODES.CLI and are excluded from the bypass. Even if the client ID check is broadened, isLocalDirectRequest() returns false in Docker host networking despite remoteAddress being 127.0.0.1 — a secondary false-negative in the locality detection.
• Missing detection / guardrail: No test coverage for CLI-mode pairing bypass. No Docker-specific integration test for CLI→gateway WebSocket connectivity.
• Prior context: PR #30801 (merged March 2) added isBackendSelfConnection to broaden the bypass for TLS+subagent scenarios (#30740), but (a) the fix only covered gateway-client/backend mode, not cli/cli, and (b) the isBackendSelfConnection identifier is absent from built output on both v2026.3.23 and main at 2026.3.24-beta.1 — suggesting it was reverted or overwritten.
• Why this regressed now: This never worked — it's a design gap, not a regression. The pairing system was built for remote mobile/external clients and never accommodated co-located Docker containers.
• If unknown, what was ruled out: N/A — root cause is confirmed via debug instrumentation.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server/ws-connection/handshake-auth-helpers.test.ts
• Scenario the test should lock in: shouldSkipBackendSelfPairing returns true for cli/cli client with isLocalClient: true, sharedAuthOk: true, authMethod: "token". Returns false when remote or when auth fails.
• Why this is the smallest reliable guardrail: Unit test directly exercises the bypass function with CLI-mode inputs — catches any future narrowing of the client ID/mode match.
• Existing test that already covers this (if any): Existing tests only cover gateway-client/backend mode.
• If no new test is added, why not: New test IS added — three cases for CLI mode (local+auth passes, remote fails, no-auth fails).

User-visible / Behavior Changes

• docker compose run --rm openclaw-cli <command> now works in Docker deployments
• docker exec openclaw-openclaw-cli-1 openclaw <command> now works
• Internal callGateway() operations from CLI-mode clients no longer fail with pairing required

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: The CLI pairing bypass is gated on: (1) client ID is cli, (2) client mode is cli, (3) shared auth succeeded, (4) no browser origin header. A CLI connection with a valid token already has full operator access — skipping pairing does not expand the access surface. Backend self-connections retain the existing locality check as defense-in-depth.

Repro + Verification

Environment

• OS: Ubuntu (headless)
• Runtime/container: Docker Engine + Compose v2, host networking, network_mode: "service:openclaw-gateway" for CLI
• Model/provider: Not model-specific (moonshot/kimi-k2.5 in test)
• Integration/channel (if any): N/A
• Relevant config (redacted): gateway.auth.mode: "token", gateway.bind: "loopback", standard docker-compose.yml from repo

Steps

1. Deploy with Docker Compose (gateway + CLI containers sharing network namespace)
2. Run: docker compose run --rm --entrypoint /usr/local/bin/openclaw openclaw-cli cron list
3. Observe result

Expected

• Cron job list displayed

Actual

• Before fix: gateway closed (1008): pairing required
• After fix: 14 cron jobs listed successfully

Evidence

• Failing test/log before + passing after
• Trace/log snippets

Before:

gateway connect failed: GatewayClientRequestError: pairing required
Error: gateway closed (1008): pairing required
Gateway target: ws://127.0.0.1:18789
Source: local loopback

Debug instrumentation showing isLocalClient: false despite remoteAddress: "127.0.0.1":

{"isLocalClient":false,"remoteAddress":"127.0.0.1","hostHeader":"127.0.0.1:18789","xForwardedFor":null,"xRealIp":null,"xForwardedHost":null}

Debug instrumentation showing bypass function receiving correct values but blocked by isLocalClient:

{"clientId":"cli","clientMode":"cli","isLocalTrustedClient":true,"isLocalClient":false,"sharedAuthOk":true,"authMethod":"token"}

After fix: CLI returns full cron job listing (14 jobs).

Human Verification (required)

• Verified scenarios: CLI cron list works in Docker deployment after fix. Gateway starts cleanly. Web UI still works. Telegram/Discord bots unaffected.
• Edge cases checked: Backend self-connections unaffected (retain locality check); failed auth does not skip pairing; browser-origin header blocks bypass.
• What you did not verify: Non-Docker native installs (no access to test environment), TLS configurations, mobile app pairing.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert the isLocalTrustedClient and isCli changes in handshake-auth-helpers.ts, restoring the original isGatewayBackendClient check.
• Files/config to restore: src/gateway/server/ws-connection/handshake-auth-helpers.ts
• Known bad symptoms reviewers should watch for: Unauthorized CLI connections bypassing pairing from non-localhost origins (would require a valid gateway token, so low risk).

Risks and Mitigations

• Risk: A process on a remote host with a stolen gateway token could impersonate a CLI client and bypass pairing.
  • Mitigation: The token already grants full operator access. An attacker with the token can use the Web UI (which already bypasses pairing via dangerouslyDisableDeviceAuth). Skipping pairing for CLI does not expand the attack surface.
• Risk: isLocalDirectRequest false negative in Docker may indicate a deeper networking issue worth a separate fix.
  • Mitigation: Filed as a note in the issue. This PR works around it for CLI; a separate investigation into isLocalDirectRequest Docker behavior is recommended.

Changed files

• CHANGELOG.md (modified, +3/-0)
• src/gateway/server.auth.control-ui.suite.ts (modified, +79/-0)
• src/gateway/server/ws-connection/handshake-auth-helpers.test.ts (modified, +167/-1)
• src/gateway/server/ws-connection/handshake-auth-helpers.ts (modified, +48/-1)
• src/gateway/server/ws-connection/message-handler.ts (modified, +28/-7)