openclaw - 💡(How to fix) Fix codex (app-server) runtime drops openclaw.json mcp.servers — only codex-cli bridges them

Summary

When an OpenClaw agent runs under agentRuntime.id: codex (the app-server harness, not codex-cli), the user-defined mcp.servers block in ~/.openclaw/openclaw.json is never propagated into codex's own config.toml. Result:

• openclaw mcp list shows the server (because the CLI reads openclaw.json directly).
• The agent (which enumerates from its codex-home/config.toml + curated plugin cache) cannot see it.
• Plugin-marketplace MCP (gmail / figma / github) works fine because it goes through the apps configPatch.
• User-defined mcp.servers entries are silently dropped.

Reproduction (OpenClaw 2026.5.10-beta.5)

1. Define an agent with agentRuntime: {id: "codex"} in ~/.openclaw/openclaw.json.
2. Register a custom MCP server under mcp.servers.<name> in the same file.
3. Start a session against the agent. Ask it to list its tools.

Expected: tools from <name> are available. Actual: only curated-plugin tools are listed. The [mcp_servers.<name>] block in the agent's ~/.openclaw/agents/<id>/agent/codex-home/config.toml is empty.

Root cause (paths in 2026.5.10-beta.5)

/opt/homebrew/lib/node_modules/openclaw/dist/model-runtime-aliases-DiLBFUUs.js:5-11:

{ legacyProvider: "codex", provider: "openai", runtime: "codex", cli: false }

Because cli: false, this alias is not registered in CLI_RUNTIME_BY_PROVIDER (line 32) and never reaches prepareCliRunContext → prepareCliBundleMcpConfig → injectCodexMcpConfigArgs in prepare.runtime-CgcsZF42.js:421-428. That function is the only path in openclaw that injects cfg.mcp.servers into a codex invocation (via -c mcp_servers=…).

The @openclaw/codex plugin handles the codex (app-server) runtime via dist/harness.js → run-attempt-DZvighJE.js, spawning codex app-server --listen stdio://. Grep of @openclaw/codex/dist/* shows zero code paths that read cfg.mcp.servers and patch them into codex's config.toml or pass -c mcp_servers= overrides. The apps field gets a configPatch in thread-lifecycle-i42nWiSS.js:419 — mcp_servers is the missing sibling.

Proposed fix

Mirror the existing apps configPatch in @openclaw/codex/dist/thread-lifecycle-i42nWiSS.js (around line 419). When the harness assembles the codex config.toml patch from openclaw config, also project cfg.mcp.servers into the mcp_servers section of codex's config (or pass -c mcp_servers=… overrides). This puts the codex app-server runtime in lockstep with the codex-cli runtime's existing injectCodexMcpConfigArgs behavior.

Current workaround (sidecar)

A sidecar script in the consuming package writes the [mcp_servers.<name>] block directly into each codex-runtime agent's codex-home/config.toml, with HR8 timestamped backup + apps_tools cache clear. Idempotent. Codex-runtime only.

This works but creates a divergent maintenance surface — any change to the MCP server's launch command / env vars requires touching every agent's config.toml. Closing the upstream gap would let downstream packages delete the adapter.

Severity

Medium. Breaks any user-defined MCP server for app-server-runtime agents. Plugin-marketplace MCP is unaffected. Workaround exists but is per-agent.

Repro environment

• OpenClaw 2026.5.10-beta.5 (host)
• @openclaw/codex plugin version per ~/.openclaw/npm/node_modules/@openclaw/codex/package.json
• macOS 14+ (Darwin 25.4)