Summary

Keep the Codex app-server co-located with the OpenClaw Gateway over managed stdio, while routing filesystem and process execution to an authenticated remote Codex execution environment.

Problem to solve

OpenClaw can connect to a separately hosted Codex app-server over WebSocket, but that splits one logical runtime across hosts. Gateway-owned lifecycle, hooks, local MCP servers, workspace projection, authentication state, thread recovery, and app-server state then have different failure and filesystem boundaries.

Upstream Codex documents stdio as the supported app-server transport and TCP WebSocket as experimental and unsuitable for production use. A production remote-workspace topology therefore needs a supported way to keep Gateway and app-server together without forcing command execution onto the Gateway host.

Proposed solution

Add an explicit experimental Codex plugin configuration for registry-backed remote execution:

• Gateway continues to own and supervise a local codex app-server --listen stdio:// child.
• Codex app-server receives authenticated Noise registry settings for a selected codex exec-server environment.
• OpenClaw projects local workspace paths into a configured remote workspace root.
• Runtime identity includes the remote environment, so changing environments rotates thread bindings instead of resuming against the wrong filesystem.
• Configuration fails closed for unsupported combinations: remote app-server transport, local stdio MCP servers, Computer Use, OpenClaw sandboxing, sandbox exec-server, and the app-server loopback network proxy.
• Registry credentials use SecretRefs and never appear in durable runtime fingerprints.
• Codex app-server 0.142.0 or newer is required, matching the first release with authenticated registry-backed execution environments.

Alternatives considered

1. Keep app-server remote over WebSocket. This preserves the split lifecycle and relies on an upstream experimental transport.
2. Mirror Gateway/app-server state and session files between hosts. This adds multi-writer consistency and recovery problems without fixing hook, MCP, or process ownership.
3. Run Gateway inside every remote workspace. This restores locality but duplicates the control plane and complicates routing, upgrades, and operator ownership.
4. Use OpenClaw's sandbox exec-server. That is appropriate for Gateway-owned sandboxes, but it is not an authenticated remote environment registry and does not select independently managed workspaces.

Impact

• Affected: operators running OpenClaw against remote development or execution environments.
• Severity: high for production remote-workspace deployments; split-host failures can lose thread continuity, execute hooks on the wrong host, or expose host-local paths to the other runtime.
• Frequency: inherent to every split Gateway/app-server deployment, with user-visible symptoms appearing during reconnects, restarts, recovery, hooks, and local-tool use.
• Consequence: fewer unsupported transport failures and one canonical owner for app-server lifecycle, auth, thread state, hooks, and local plugin integration.

Evidence/examples

• Upstream Codex app-server transport guidance: https://github.com/openai/codex/blob/rust-v0.142.5/codex-rs/app-server/README.md
• OpenClaw remote WebSocket app-server support: feat(codex): support remote app-server plugins #94203
• OpenClaw app-server supervision: feat: add codex supervisor plugin #87849
• Related app-server version/lifecycle cleanup that must be reconciled: refactor(codex): raise app-server floor to 0.142, drop range compat, fix deferred spawn_agent steering #101221

Additional information

The first implementation should remain explicitly experimental until a live registry-backed executor scenario is proven end to end. This issue and the proposed implementation are AI-assisted; the design and code were reviewed against the exact Codex 0.142.5 source contract. A sanitized agent transcript was intentionally omitted.