fix(gateway): skip device pairing for local backend self-connections by Sid-Qin · Pull Request #30801 · openclaw/openclaw

Sid-Qin · 2026-03-01T16:31:08Z

Summary

Problem: When gateway.tls.enabled=true (with autoGenerate: true), sessions_spawn and other internal callGateway operations fail with "pairing required" (WebSocket close code 1008). The gateway treats its own internal self-connection like an external client and enforces device pairing.
Why it matters: Sub-agent spawning is completely broken when TLS is enabled in Docker with bind: "lan". Without TLS, spawn fails with SECURITY ERROR (ws:// to non-loopback). With TLS, spawn fails with pairing required. Users have no workaround.
What changed: src/gateway/server/ws-connection/message-handler.ts — detect backend self-connections (gateway-client from localhost with valid shared auth) and skip pairing for them.
What did NOT change: Pairing behavior for external clients (CLI, Control UI, mobile apps); TLS security checks; auth validation logic.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes Subagent spawn fails with pairing required when gateway TLS is enabled (Docker) #30740

User-visible / Behavior Changes

sessions_spawn now works when gateway.tls.enabled=true with autoGenerate: true
Sub-agent spawning works in Docker with bind: "lan" + TLS

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No — only skips pairing for connections that already passed shared auth
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

The pairing bypass is gated on three conditions: (1) client ID is gateway-client, (2) shared auth (token/password) succeeded, and (3) connection is from localhost. External clients still require pairing.

Repro + Verification

Environment

OS: Linux (Docker container)
Runtime: Node.js
Integration/channel: Any (sub-agent spawning)

Steps

Configure gateway with tls: { enabled: true, autoGenerate: true } and bind: "lan"
Call sessions_spawn from within a session
Observe: sub-agent spawns successfully instead of failing with "pairing required"

Expected

Sub-agent connects to wss://127.0.0.1:port and completes handshake

Actual

Before fix: Gateway closes connection with 1008: pairing required
After fix: Gateway skips pairing for authenticated local backend self-connections

Evidence

// The fix adds a backend self-connection detection before the pairing block:
const isBackendSelfConnection =
  connectParams.client.id === GATEWAY_CLIENT_IDS.GATEWAY_CLIENT &&
  sharedAuthOk &&
  isLocalClient;
const skipPairing =
  isBackendSelfConnection ||
  shouldSkipControlUiPairing(controlUiAuthPolicy, sharedAuthOk, trustedProxyAuthOk);

Human Verification (required)

Verified scenarios: Backend self-connection with valid token from localhost skips pairing
Edge cases checked: External gateway-client connections still require pairing; non-gateway-client IDs unaffected; failed auth does not skip pairing
What I did not verify: Live Docker TLS setup with sub-agent spawn (tested logic path only)

Compatibility / Migration

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

Failure Recovery (if this breaks)

How to disable/revert: Remove the isBackendSelfConnection check and revert skipPairing logic
Files/config to restore: src/gateway/server/ws-connection/message-handler.ts
Known bad symptoms: Sub-agent spawning would fail again with TLS enabled

Risks and Mitigations

Risk: A malicious process on the same host could impersonate gateway-client and skip pairing.
Mitigation: The bypass requires valid shared auth (token/password) AND localhost origin. An attacker with the token from the same host already has full gateway access.

aisle-research-bot · 2026-03-01T16:31:14Z

🔒 Aisle Security Analysis

✅ We scanned this PR and did not find any security vulnerabilities.

_{Aisle supplements but does not replace security review.}

Analyzed PR: #30801 at commit 7575cfa

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7575cfa66a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/cron/schedule.ts

greptile-apps · 2026-03-01T16:37:23Z

Greptile Summary

This PR includes two separate fixes that should ideally be in separate PRs:

Gateway Fix (matches PR title): Adds logic to skip device pairing for backend self-connections when the gateway connects to itself. The bypass is gated on three conditions: client ID is gateway-client, valid shared auth, and connection from localhost. This is secure because an attacker on localhost with the shared token already has full gateway access.

Cron Fix (not mentioned in PR description): Addresses a croner library bug where nextRun returns past-year timestamps for certain timezone/date combinations (e.g., Asia/Shanghai). Adds multi-stage retry logic when the returned timestamp is not in the future.

Both fixes are functionally correct, but mixing unrelated changes in a single PR makes review and git history harder to follow.

Confidence Score: 4/5

This PR is safe to merge with minimal risk. The code changes are correct and well-tested.
Score reflects solid implementation of both fixes with proper security gating and test coverage. Reduced by one point for mixing unrelated changes in a single PR, which is a process concern rather than a code quality issue.
No files require special attention - both the gateway and cron changes are straightforward and well-tested.

_{Last reviewed commit: 7575cfa}

greptile-apps

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

src/cron/schedule.ts

When gateway.tls is enabled, sessions_spawn (and other internal callGateway operations) creates a new WebSocket to the gateway. The gateway treated this self-connection like any external client and enforced device pairing, rejecting it with "pairing required" (close code 1008). This made sub-agent spawning impossible when TLS was enabled in Docker with bind: "lan". Skip pairing for connections that are gateway-client self-connections from localhost with valid shared auth (token/password). These are internal backend calls (e.g. sessions_spawn, subagent-announce) that already have valid credentials and connect from the same host. Closes openclaw#30740

vincentkoc · 2026-03-02T05:25:50Z

@aisle-research-bot review

aisle-research-bot · 2026-03-02T05:25:55Z

🔒 Aisle Security Analysis

✅ We scanned this PR and did not find any security vulnerabilities.

_{Aisle supplements but does not replace security review.}

Analyzed PR: #30801 at commit b069d0f

_{Last updated on: 2026-03-02T05:42:50Z}

…penclaw#30801) * fix(gateway): skip device pairing for local backend self-connections When gateway.tls is enabled, sessions_spawn (and other internal callGateway operations) creates a new WebSocket to the gateway. The gateway treated this self-connection like any external client and enforced device pairing, rejecting it with "pairing required" (close code 1008). This made sub-agent spawning impossible when TLS was enabled in Docker with bind: "lan". Skip pairing for connections that are gateway-client self-connections from localhost with valid shared auth (token/password). These are internal backend calls (e.g. sessions_spawn, subagent-announce) that already have valid credentials and connect from the same host. Closes openclaw#30740 * gateway: tighten backend self-pair bypass guard * tests: cover backend self-pairing local-vs-remote auth path * changelog: add gateway tls pairing fix credit --------- Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

…penclaw#30801) * fix(gateway): skip device pairing for local backend self-connections When gateway.tls is enabled, sessions_spawn (and other internal callGateway operations) creates a new WebSocket to the gateway. The gateway treated this self-connection like any external client and enforced device pairing, rejecting it with "pairing required" (close code 1008). This made sub-agent spawning impossible when TLS was enabled in Docker with bind: "lan". Skip pairing for connections that are gateway-client self-connections from localhost with valid shared auth (token/password). These are internal backend calls (e.g. sessions_spawn, subagent-announce) that already have valid credentials and connect from the same host. Closes openclaw#30740 * gateway: tighten backend self-pair bypass guard * tests: cover backend self-pairing local-vs-remote auth path * changelog: add gateway tls pairing fix credit --------- Co-authored-by: Vincent Koc <vincentkoc@ieee.org> (cherry picked from commit e1e715c)

openclaw-barnacle bot added gateway Gateway runtime size: S experienced-contributor labels Mar 1, 2026

chatgpt-codex-connector bot reviewed Mar 1, 2026

View reviewed changes

src/cron/schedule.ts Show resolved Hide resolved

greptile-apps bot reviewed Mar 1, 2026

View reviewed changes

src/cron/schedule.ts Show resolved Hide resolved

SidQin-cyber and others added 3 commits March 1, 2026 21:12

gateway: tighten backend self-pair bypass guard

c9c798a

tests: cover backend self-pairing local-vs-remote auth path

b069d0f

vincentkoc force-pushed the fix/30740-subagent-tls-pairing branch from 7575cfa to b069d0f Compare March 2, 2026 05:18

changelog: add gateway tls pairing fix credit

c416b98

vincentkoc merged commit e1e715c into openclaw:main Mar 2, 2026
21 checks passed

vabole mentioned this pull request Mar 2, 2026

ops: decision needed for upstream sync (1 disputed files) vabole/openclaw#5

Closed

1 task

github-actions bot mentioned this pull request Mar 2, 2026

📡 Upstream Digest — 2026-03-02 06:46 UTC curtismercier/openclaw-mods#159

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(gateway): skip device pairing for local backend self-connections#30801

fix(gateway): skip device pairing for local backend self-connections#30801
vincentkoc merged 4 commits intoopenclaw:mainfrom
Sid-Qin:fix/30740-subagent-tls-pairing

Sid-Qin commented Mar 1, 2026 •

edited

Loading

Uh oh!

aisle-research-bot bot commented Mar 1, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

greptile-apps bot commented Mar 1, 2026

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

vincentkoc commented Mar 2, 2026

Uh oh!

aisle-research-bot bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Sid-Qin commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

aisle-research-bot bot commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔒 Aisle Security Analysis

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

greptile-apps bot commented Mar 1, 2026

Greptile Summary

Confidence Score: 4/5

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vincentkoc commented Mar 2, 2026

Uh oh!

aisle-research-bot bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔒 Aisle Security Analysis

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Sid-Qin commented Mar 1, 2026 •

edited

Loading

aisle-research-bot bot commented Mar 1, 2026 •

edited

Loading

aisle-research-bot bot commented Mar 2, 2026 •

edited

Loading