PR #63480: fix(gateway): start channels before WebSocket handlers (#63450)

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63480

Description (problem / solution / changelog)

Summary

• Problem: WebSocket RPC (chat.history, etc.) was enabled before startGatewaySidecars finished. chat.history performs large synchronous session-store and transcript reads on the main thread, which can block the event loop and delay Telegram, browser control, and plugin startup (see #63450).
• Why it matters: Operators saw multi-minute gaps after starting channels and sidecars... while a pending chat.history completed; channels stayed down until then.
• What changed: Run deferred channel-plugin reload (when applicable), then startGatewaySidecars, then attach WebSocket handlers. Gateway WebSocket upgrades already return 503 until wss connection listeners exist, so clients do not run heavy RPC during this window.
• What did NOT change: Handler implementations, chat.history semantics, and Tailscale/update-check ordering after WS attach.

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 #63450
• Related #63450
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Startup ordered WebSocket message handling before channels/sidecars. Synchronous file reads and JSON work in chat.history starved the event loop, so async channel startup did not complete until that work finished.
• Missing detection / guardrail: Ordering was not covered by an integration test asserting WS attach vs channel start.
• Contributing context (if known): Regression reported since v2026.4.8; consistent with sync loadSessionStore / readSessionMessages paths.

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.minimal-channel-pin.test.ts, src/gateway/server.shared-token-session-rotation.test.ts (gateway startup smoke).
• Scenario the test should lock in: Full gateway boot completes with channels and WS both healthy.
• Why this is the smallest reliable guardrail: Ordering fix is structural; dedicated timing tests are flaky; existing gateway server tests still pass after reorder.
• Existing test that already covers this (if any): Gateway tests above exercise startGatewayServer.
• If no new test is added, why not: Behavior is startup sequencing; no stable hook exposed for a small unit test without refactoring server.impl.ts for injection.

User-visible / Behavior Changes

• WebSocket clients may observe a slightly longer window where the gateway HTTP server is up but WebSocket upgrades return 503 (Gateway websocket handlers unavailable) until channels and sidecars have started; then RPC behaves as before.

Diagram (if applicable)

N/A

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: N/A

Repro + Verification

Environment

• OS: Linux/macOS dev (CI covers the rest)
• Runtime/container: Node 22+
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. pnpm check
2. pnpm test src/gateway/server.minimal-channel-pin.test.ts src/gateway/server.shared-token-session-rotation.test.ts

Expected

• Tests pass; gateway startup ordering no longer allows WS RPC before channel/sidecar start.

Actual

• pnpm check passed locally; scoped gateway tests passed.

Evidence

• Failing test/log before + passing after
• Trace/log snippets (repro described in #63450: chat.history duration matches channel startup delay)
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Typecheck/lint (pnpm check); gateway server smoke tests listed above.
• Edge cases checked: minimalTestGateway path unchanged (sidecars still skipped when that env is set).
• What you did not verify: Full pnpm test suite and pnpm build (local pnpm build failed on unrelated acpx/runtime resolution in this workspace).

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
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Slightly longer period where HTTP is listening but WebSocket upgrades return 503 until sidecars finish.
  • Mitigation: Same 503 behavior existed before attachGatewayWsHandlers; this only extends that window to cover channel startup, which is typically short relative to a stuck chat.history.

Changed files

• CHANGELOG.md (modified, +2/-0)
• src/gateway/server-http.ts (modified, +7/-4)
• src/gateway/server.impl.ts (modified, +29/-25)
• src/gateway/server.preauth-hardening.test.ts (modified, +1/-1)