openclaw - 💡(How to fix) Fix [Bug]: Codex ACP native route fails with "Authentication required" when host Codex uses OAuth (ChatGPT login)

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

The native Codex ACP route (sessions_spawn(runtime: "acp", agentId: "codex")) returns Authentication required when the host Codex install is authenticated via OAuth (ChatGPT login) rather than an API key, even though the same OAuth credential works when acpx is invoked directly with CODEX_HOME set.

Steps to reproduce

1. Host Codex authenticated via OAuth/ChatGPT login (~/.codex/auth.json), no API key.
2. Enable native ACP: bash openclaw config set acp.enabled true openclaw config set acp.backend '"acpx"' openclaw config set acp.defaultAgent '"codex"' openclaw config set acp.allowedAgents '["codex"]' openclaw config set plugins.entries.acpx.config.permissionMode '"approve-all"' # restart gateway
3. Spawn the native ACP Codex agent: sessions_spawn({ runtime: "acp", agentId: "codex", task: "Reply with exactly: Codex ACP OK" })
4. Observe the error returned.

Expected behavior

The native ACP Codex session starts and runs, using the host OAuth credential. Grounded in two references:

1. docs/tools/acp-agents.md (First-run gotchas): *"Codex ACP runs with an isolated CODEX_HOME; OpenClaw copies trusted project entries plus safe model/provider routing config from the host Codex config, while auth, notifications, and hooks *stay on the host config.", i.e. host auth is supposed to be preserved.
2. Known-good control: the same OAuth credential succeeds when acpx is run directly (see Logs below).

Actual behavior

sessions_spawn returns:

{ "status": "error", "errorCode": "spawn_failed", "error": "Authentication required", "role": "codex" }

OpenClaw version

2026.5.28 (e932160)

Operating system

macOS — Darwin 25.4.0 (arm64)

Install method

Global npm install (npm install -g openclaw); gateway run via macOS LaunchAgent. @openclaw/acpx plugin installed and enabled (v2026.5.28).

Model

Codex gpt-5.5/high (effective model under the acpx control test). The native spawn fails at authentication before model selection.

Provider / routing chain

OpenClaw gateway → @openclaw/acpx runtime plugin → Codex ACP harness (isolated CODEX_HOME) → OpenAI (Codex), authenticated via OAuth/ChatGPT login on the host (~/.codex/auth.json).

Additional provider/model setup details

Host Codex auth is OAuth, not API key, ~/.codex/ contains a current auth.json plus an older auth.json.bak-apikey-* from a prior API-key→OAuth migration, so the host was deliberately moved onto OAuth. The native ACP route runs Codex in an isolated CODEX_HOME; the CLI control test (below) sets CODEX_HOME="$HOME/.codex" explicitly into the subprocess env. No API keys/tokens included.

Logs, screenshots, and evidence

Known-good control — same OAuth credential, acpx invoked directly with CODEX_HOME set, succeeds:

CODEX_HOME="$HOME/.codex" acpx --approve-all --model gpt-5.5/high --cwd /tmp --timeout 40 \
  codex exec "Reply with exactly: WRAPPER OAUTH OK"
[client] initialize (running)
[client] session/new (running)
[client] session/set_model (running)
WRAPPER OAUTH OK
[done] end_turn
Failing native route (same config session, same credential):

{ "status": "error", "errorCode": "spawn_failed", "error": "Authentication required", "role": "codex" }

Impact and severity

Low severity, not a blocker. Affects hosts running Codex via OAuth/ChatGPT login who want to use the native sessions_spawn(runtime:"acp", agentId:"codex") path. A clean workaround exists: drive Codex via the acpx CLI directly with CODEX_HOME="$HOME/.codex" exported into the subprocess env, which works reliably. Frequency: deterministic, fails every time on the native route with this auth setup.

Additional information

Hypothesis for triage: the isolated-CODEX_HOME provisioning likely handles API-key auth but not the OAuth token + refresh flow, OAuth needs the live auth.json (and its refresh machinery) reachable from the harness's effective CODEX_HOME. If the isolation copy only covers the static API-key case, an OAuth-only host would surface exactly this Authentication required. Suggested fix direction: make the host OAuth credential resolvable by the spawned Codex harness, either by referencing the host auth.json the way the CLI does when CODEX_HOME points at ~/.codex, or by copying the OAuth token alongside the existing API-key path. Happy to provide more logs or test a patch against an OAuth setup if useful.