PR #64393: fix(cli): exclude loopback overlay from mcpConfigHash

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

Description (problem / solution / changelog)

Summary

• Snapshots user-authored MCP state in prepareCliBundleMcpConfig before merging the loopback overlay (additionalConfig) and passes it to prepareModeSpecificBundleMcpConfig as hashSource.
• mcpConfigHash is now computed from that snapshot instead of the loopback-merged config. Session identity is therefore port-agnostic.
• Actual mcp.json / CLI args still embed the current loopback port so the CLI process can reach the bridge — only the hash changes.

Fixes #64386.

Why

The loopback MCP bridge binds to an OS-assigned ephemeral port on every gateway start (startMcpLoopbackServer(port = 0) in src/gateway/mcp-http.ts). createMcpLoopbackServerConfig embeds that port as a literal in the server URL, which was then merged into mergedConfig in prepareCliBundleMcpConfig and hashed in prepareModeSpecificBundleMcpConfig. Result: mcpConfigHash changed on every gateway restart, so resolveCliSessionReuse returned { invalidatedReason: "mcp" } on the first turn of every previously-persisted Claude CLI session after every restart, and the agent resumed with a fresh claude -p instead of claude --resume — losing all conversation memory.

The OpenClaw auth token is referenced as ${OPENCLAW_MCP_TOKEN} and resolved via env, so it never entered the hashed bytes. The port was the sole offender because it is a literal in the URL.

This was the result of two otherwise-correct commits interacting:

• 12100719b8 "fix: preserve cli sessions across model changes" introduced mcpConfigHash. At the time, the hashed config only contained user-authored MCP state — stable across restarts.
• 3de09fbe74 "fix: restore claude cli loopback mcp bridge (#35676)" started merging the loopback overlay into the same mergedConfig, silently turning a stable hash into a per-restart-random one.

The layering fix is to treat the loopback as gateway-internal runtime state that shouldn't contribute to session identity. Any other ephemeral value merged via additionalConfig in the future (PID, tempdir, per-start identifier) is now automatically safe for the same reason.

Test plan

New tests in src/agents/cli-runner/bundle-mcp.test.ts:

• Hash stability: run prepareCliBundleMcpConfig twice with identical user MCP state but two different loopback ports (62949, 51734); assert mcpConfigHash is identical. Also assert the two written mcp.json files contain the correct per-run port so the bridge is still reachable.
• Hash sensitivity (not over-corrective): same loopback URL both runs, but the second run adds a real plugin MCP server via createBundleProbePlugin; assert the hash changes.
• Existing bundle-mcp.test.ts and cli-session.test.ts tests still pass.
• oxlint clean on touched files.
• tsc -p tsconfig.json --noEmit clean.

Notes

• prepareModeSpecificBundleMcpConfig gained an optional hashSource param; when absent it falls back to hashing mergedConfig, so all existing callers are unaffected.
• The hash snapshot is a shallow { mcpServers: { ...mergedConfig.mcpServers } } — sufficient because applyMergePatch replaces entries by key and the snapshot is not mutated afterwards.

🤖 Generated with Claude Code

Changed files

• src/agents/cli-runner/bundle-mcp.test.ts (modified, +336/-0)
• src/agents/cli-runner/bundle-mcp.ts (modified, +86/-1)
• src/agents/cli-runner/prepare.ts (modified, +1/-0)
• src/agents/cli-session.test.ts (modified, +48/-0)
• src/agents/cli-session.ts (modified, +15/-1)

PR #64557: fix: exclude ephemeral loopback port from CLI session mcpConfigHash (closes #64386)

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

Description (problem / solution / changelog)

Summary

• Problem: Every gateway restart silently wipes all persisted Claude CLI session memory. The first turn after restart resets the session because mcpConfigHash changes.
• Why it matters: Users experience "the agent suddenly forgot everything" after every gateway restart. Affects all deployments using the claude-cli backend with the loopback MCP bridge (default since #35676).
• What changed: Compute mcpConfigHash from user-authored mergedConfig before additionalConfig (containing the ephemeral loopback server URL) is merged in. The loopback config is still merged for the actual mcp.json / CLI args, just excluded from the session identity hash.
• What did NOT change: The actual MCP config written to disk still includes the loopback server. User-authored MCP config changes still correctly invalidate sessions.

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

Root Cause (if applicable)

• Root cause: Two independently-correct commits interact badly: (1) 12100719b8 introduced mcpConfigHash for CLI session reuse, (2) 3de09fbe74 merged the loopback MCP server (with OS-assigned ephemeral port) into the same mergedConfig that gets hashed. The ephemeral port changes on every gateway restart → hash changes → all sessions invalidated.
• Missing detection / guardrail: No test asserts hash stability across simulated gateway restarts with port churn.
• Contributing context: The loopback URL is constructed with port=0 (OS-assigned), so http://127.0.0.1:<random-port>/mcp produces a different hash every time.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/agents/cli-runner/bundle-mcp.test.ts
• Scenario the test should lock in: Hash computed at run N+1 equals hash at run N when only the loopback port differs
• If no new test is added, why not: Keeping PR minimal — happy to add if requested

User-visible / Behavior Changes

• CLI sessions now persist across gateway restarts (previously silently reset every restart)
• Session reuse is still correctly invalidated when user-authored MCP config changes

Diagram (if applicable)

Before:
gateway restart -> new ephemeral port -> hash(mergedConfig + loopback) changes -> session reset

After:
gateway restart -> new ephemeral port -> hash(mergedConfig only, no loopback) unchanged -> session preserved

Security Impact (required)

• New permissions/capabilities? No
• Auth boundary changes? No
• Secrets/token exposure risk? No
• New external calls? No
• Sandbox/isolation changes? No

Evidence

• Code trace confirms ephemeral port is sole source of hash instability (auth token uses env var reference, not literal)
• pnpm check passes
• AI-assisted: fix authored by Claude Code, reviewed and verified manually

Human Verification (required)

• Verified scenarios: Traced hash computation path, confirmed additionalConfig merge happens after hash
• Edge cases checked: No additionalConfig (hash unchanged), only additionalConfig changes (hash unchanged, correct), user MCP config changes (hash changes, correct)
• What you did not verify: Live gateway restart test

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

Risks and Mitigations

• Risk: If additionalConfig contains user-meaningful config that should affect session identity
  • Mitigation: Currently additionalConfig only contains the loopback server (gateway-internal runtime state). The function signature documents this separation clearly.

Changed files

• src/agents/cli-runner/bundle-mcp.ts (modified, +8/-1)