Summary

Show Codex App Server sessions from the Gateway host and every paired OpenClaw node in one read-only CLI and Control UI catalog.

Problem to solve

Codex sessions are host-local. OpenClaw can supervise Codex on the Gateway and can pair remote computers as nodes, but an operator cannot discover all of those sessions from one place. The existing Codex CLI-session scan only sees one filesystem and does not use the canonical Codex App Server API. Native macOS nodes also advertise a fixed command set, so plugin node-host commands alone do not provide Mac parity.

This makes it difficult to find, compare, or resume work spread across a Mac, a development box, and the Gateway host. Operators must connect to each machine and inspect Codex separately.

Proposed solution

Extend the opt-in codex-supervisor plugin with a federated, metadata-only session catalog:

• Each enabled node exposes a versioned read-only command backed by its local codex app-server --listen stdio:// and stable thread/list API.
• The Gateway queries its own App Server plus connected nodes and returns per-host results, cursors, connection state, and isolated errors.
• The plugin registers an openclaw codex sessions command with human-readable and JSON output.
• Control UI gains a Codex Sessions view grouped by host, with search, archived-session filtering, refresh, and pagination.
• The native Mac app implements the same node command as the TypeScript node host so macOS and CLI nodes behave identically.
• Enabling remains explicit through the existing plugin configuration on the Gateway and participating nodes. Transcript contents and write controls remain outside this surface.

The node boundary owns local Codex access. The Gateway owns federation, authorization, and presentation. A newly advertised command follows the existing node pairing/reapproval flow.

Alternatives considered

1. Scan Codex rollout files over SSH or shared storage. This bypasses the App Server contract, creates platform-specific parsing and compression support, and couples the Gateway to remote filesystem layout.
2. Expose each App Server directly over the network. That broadens the trust boundary and relies on a transport that is unnecessary for metadata discovery.
3. Merge foreign Codex threads into OpenClaw's core session list. Those records have different lifecycle and mutation semantics, so a separate plugin-owned catalog is safer and clearer.
4. Put a node list in Gateway config. Node capabilities are discovered dynamically; duplicating per-node feature policy in the Gateway would drift from the machine that actually owns the Codex process and data.

Impact

• Affected: operators using Codex on multiple computers connected to one OpenClaw Gateway.
• Severity: medium; this does not block Codex, but it blocks a coherent multi-host workflow.
• Frequency: every time work is split between a local Mac, Gateway host, or remote development node.
• Consequence: repeated SSH/manual inspection, lost context about where a thread lives, and no single operational view of active or archived Codex work.

Evidence/examples

• Codex App Server provides stable thread/list pagination and filtering: https://github.com/openai/codex/tree/main/codex-rs/app-server
• OpenClaw already ships the opt-in Codex supervisor plugin and generic plugin node-command transport: https://github.com/openclaw/openclaw/tree/main/extensions/codex-supervisor
• Related but distinct remote-execution ownership discussion: [Feature]: Keep Codex app-server with Gateway for remote execution #101282
• Related but distinct command-backed remote transport discussion: [Feature]: Stabilize remote Codex app-server connections with a command-backed transport #101416

Additional information

The implementation and issue text are AI-assisted. The design was checked against current upstream Codex source. A sanitized agent transcript was intentionally omitted at the operator's request.