[Design] Fixed-endpoint native credential routing for Codex and OpenClaw

[dmdfami]

Problem

Codex App/CLI and OpenClaw can already use the native Codex backend at /backend-api/codex, but changing between the client's signed-in OAuth account and the codex-lb account pool normally means changing provider configuration or restarting a client/app-server. Generic /v1 integrations also replace part of the native harness rather than preserving it.

I propose an opt-in, fixed-endpoint routing policy inside codex-lb:

Codex App/CLI or OpenClaw native harness
  -> fixed http://127.0.0.1:2455/backend-api/codex
  -> persisted credential source: client_oauth | pool
  -> ChatGPT Codex backend

The client remains signed in normally, keeps its native Responses harness, and continues selecting its own model, reasoning effort, tools, plugins/MCP, and requested service tier. The routine switch changes only which OAuth identity owns the next native request and its quota.

Proposed behavior

• pool: strip the inbound client OAuth identity before normal account selection; one eligible pooled account owns the request.
• client_oauth: relay the request-local client OAuth identity directly; do not enter the pool or create a pooled request-log row.
• keep the same /backend-api/codex endpoint in both modes; /v1 remains unchanged.
• do not restart Codex, OpenClaw, or codex-lb for the routine switch.
• let an in-flight turn finish on its original credential source; reject/quarantine a new stale WebSocket create, drain the terminal event, then close with 1012 so the existing client reconnects under the new policy.
• do not hardcode or rewrite model, reasoning, or Fast selection in the controller/UI. Compatibility normalization remains explicit; this is not claimed as byte-for-byte passthrough.

Security boundary

• disabled unless an explicit server capability flag is enabled;
• native namespace plus trusted loopback admission only, fail closed otherwise;
• client OAuth remains request-local and is never stored, copied into the pool, exposed to browser JavaScript, or written to request logs;
• generic API-key and /v1 behavior stays isolated;
• unsupported pool reset-credit behavior fails explicitly instead of charging an ambiguous identity.

Dashboard UX

A dedicated capability-gated /native-routing page would make the policy switch the primary one-click action and explain both data paths. One-time client attachment/repair can remain a secondary, optional host-local companion operation over a user-private Unix socket. There would be no menu-bar app, model selector, reasoning selector, routine live inference button, or automatic service restart.

The proposed page includes stable authorship attribution DOMANHDUC · dmdfami. I am calling this out here rather than hiding it in implementation so maintainers can decide the project policy explicitly.

Prototype evidence

An isolated candidate completed a real OAuth -> pool -> OAuth run with one persistent Codex CLI process and one persistent OpenClaw TUI:

• all three visible policy changes were performed through the page using Computer Use;
• every policy response reported app_restart_required=false;
• direct-mode windows created zero pool request rows;
• pool-mode windows selected one pooled account and completed over websocket -> websocket;
• model and requested tier were supplied by the clients, not the page;
• desktop/mobile UI checks and console checks passed;
• the live production listener was not restarted or reconfigured.

Displayed quota percentages did not move at their rounding precision and no fresh usage-history row landed in the bounded window, so the evidence is intentionally phrased as route-proven / displayed-quota-delta-unresolved.

Decisions requested

1. Is an opt-in, loopback-only request-local client OAuth relay acceptable in core codex-lb?
2. Is a persisted pool | client_oauth policy the right steady-state switch?
3. Should the optional attachment/recovery Unix-socket bridge live in core, or remain entirely in a companion project?
4. Is a dedicated /native-routing page appropriate, and is the explicit attribution acceptable?
5. Is fail-closed 409 for unsupported pool reset-credit behavior an acceptable first-scope limitation?

If the direction is accepted, I will submit the OpenSpec proposal first and keep implementation PRs separated into policy, HTTP relay, WebSocket policy handoff, optional recovery bridge, frontend state, and the dedicated page.

[dmdfami]

Progress update

The OpenSpec-only design review is now open as PR #1311.

Its current head contains only the six files under openspec/changes/add-native-client-loopback-controls/; it does not include runtime code, a migration, frontend code, client configuration changes, or the optional recovery bridge. Strict OpenSpec validation and git diff --check pass, the current GitHub CI run is green, and the current-head Codex review found no major issues.

The larger locally validated implementation remains local while this ownership and security boundary is reviewed. If the direction is accepted, I will port it from current upstream into reviewable implementation PRs; the exact granularity can follow maintainer preference rather than publishing the raw local worktree. The recovery-only Unix-socket bridge remains deferred from the initial implementation scope.

The bounded E2E result remains intentionally narrow: one persistent Codex CLI process and one persistent OpenClaw TUI switched client_oauth -> pool -> client_oauth behind the fixed /backend-api/codex endpoint without restarting either client or codex-lb. Route selection was proven; displayed quota-percentage movement remained unresolved at its rounding precision.

[Soju06]

Design decision: the OpenSpec proposal (#1311) was declined — the core switch-without-restart use case is covered by existing per-key account scoping (assigned_account_ids) on the fixed /backend-api/codex endpoint, and the native harness already works via requires_openai_auth = true. Details and the suggested alternative recipe are in the PR comment. If a concrete gap remains after trying that recipe (e.g. a standalone logging opt-out), a narrowly-scoped follow-up proposal is welcome.