Summary

Stabilize remote Codex app-server connections by adding a command-backed transport that OpenClaw can recreate after a disconnect.

Problem to solve

OpenClaw currently reaches a remote Codex app-server through a configured WebSocket URL. That topology requires operators to manage a network listener, routing or ingress, and WebSocket credentials separately from the host access they already use to operate the remote machine.

Each extra component becomes part of the connection's failure boundary. Listener restarts, routing changes, and stale ingress state can leave the Gateway unable to reconnect even when the remote host and app-server are otherwise healthy. OpenClaw also has no way to recreate the underlying connection from a durable command configuration.

Proposed solution

Add appServer.transport: "ssh" as a command-backed remote transport:

• Require an explicit executable, non-empty argument array, and remoteWorkspaceRoot.
• Spawn one child command per app-server connection without a shell.
• Carry the standard HTTP WebSocket Upgrade and frames over the child's stdin and stdout.
• Treat child exit as the transport exit so the existing app-server client lifecycle can reconnect by running the same stored command again.
• Keep remote app-server startup and listener ownership outside this transport.
• Reject URL, bearer-token, header, user-home, and environment-clearing settings that belong to other transport modes.

The intended first command is SSH to a protocol-clean remote wrapper. Upstream Codex already provides codex app-server proxy --sock PATH, which connects one byte stream to a Unix-socket app-server and keeps diagnostics on stderr.

Alternatives considered

1. Continue using only the remote WebSocket URL. This remains useful when a stable network endpoint already exists, but it retains the separate listener, routing, and credential failure boundary.
2. Keep the app-server beside the Gateway and move only execution to a remote environment, as proposed in [Feature]: Keep Codex app-server with Gateway for remote execution #101282. That can provide a stronger ownership model for new deployments, while a command-backed transport addresses existing deployments that intentionally keep the app-server remote.
3. Run a separately supervised SSH port-forward. This can make the WebSocket URL local, but adds another persistent process and local port for operators to own outside OpenClaw.

Impact

• Affected: operators using a Codex app-server on another host.
• Severity: medium; connection recovery depends on several independently managed components.
• Frequency: most visible during app-server restarts, host reconnects, or routing changes.
• Consequence: longer outages and manual recovery even when SSH access and the remote app-server are healthy.

Evidence/examples

• Upstream Codex documents Unix-socket app-server connections and the stdin/stdout proxy: https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md#protocol
• OpenClaw already has a shared remote app-server client lifecycle; the missing piece is a process-backed byte stream for a remote endpoint.

Additional information

This proposal is additive. Existing stdio and URL-based WebSocket configurations keep their current behavior. The implementation and issue text are AI-assisted; the proposed protocol path was checked against the current upstream Codex source.