openclaw - 💡(How to fix) Fix [Bug]: Codex harness treats local agent auth-profiles (populated + empty) as unusable and bootstraps from binary, breaking documented main-to-agent auth inheritance [2 comments, 2 participants]

Summary

OpenClaw's documented multi-agent auth-profile inheritance mechanism does not function for the Codex harness. Per docs (Multi-agent routing), "agents can read through to the default/main agent's auth profiles when they do not have a local profile." Empirically, the Codex harness:

1. Treats an empty agent/auth-profiles.json as "missing or unusable" and bootstraps from the Codex binary's ~/.codex/auth.json (single-account) instead of inheriting from main agent's profiles
2. Treats a populated agent/auth-profiles.json (with valid named profiles copied from main) as "missing or unusable" identically — the harness reads the file but rejects the profiles
3. Gateway auto-recreates an empty auth-profiles.json on restart when the file is absent, making the documented absent-file inheritance path architecturally unreachable

Result: when the bootstrap-source (~/.codex/auth.json) hits a rate-limit/exhaustion, the harness cannot rotate to other profiles even when auth.order is correctly configured and named profiles exist in main's auth store. The OAuth rotation chain documented in the multi-agent guide does not fire for the Codex provider.

Environment

• OS: Windows 11 Pro (build 26200, x64)
• Node: 24.15.0
• OpenClaw: 2026.5.19-beta.1 (fresh upgrade from 2026.5.16-beta.7; same behavior observed in both)
• Gateway: loopback 127.0.0.1:18789, service-managed via Scheduled Task
• Codex binary: spawned by harness; per-agent codex-home at ~/.openclaw/agents/<agent>/agent/codex-home/ (config.toml, state DB) — note the per-agent isolation reinforces the cross-agent inheritance failure-shape
• Agents: 2 (main and solenne); both routed through openai-codex provider for GPT-5.x

Repro steps

1. Configure two OpenAI-Codex OAuth profiles in main agent's auth-profiles.json (e.g., outlook@… + xxx@…)
2. Set auth.order.openai in openclaw.json to list both profiles in rotation order
3. Configure secondary agent (solenne) to use openai-codex provider; ensure secondary's agent/auth-profiles.json is either absent, empty ({"version": 1, "profiles": {}}), or contains copied profiles from main
4. Restart gateway with the primary OAuth profile rate-limited (e.g., subscription-cap hit)
5. Trigger an inference call from the secondary agent (or observe boot-time auth resolution)

Expected behavior

Per Multi-agent routing docs:

• When secondary agent's auth-profiles.json is absent or empty → harness inherits main agent's profiles
• When primary profile is rate-limited → harness rotates per auth.order to next profile
• Rotation honors auth-state.json cooldownUntil + lastGood signals

Actual behavior

Gateway logs (verbatim from two restart cycles 2026-05-19 ~12:08 BST and ~12:28 BST):

Restart cycle 1 — secondary's auth-profiles.json renamed to absent:

12:08:25 [agent/embedded] embedded run failover decision: runId=boot-… stage=prompt decision=rotate_profile reason=rate_limit from=openai-codex/gpt-5.4-mini profile=sha256:a9ea55ebcea8 rawError=You've reached your Codex subscription usage limit. Next reset in 5 days, May 23 at 10:43 PM GMT+1.
12:08:27 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:08:28 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:08:51 [agent/embedded] codex app-server stderr: error Exit code: 1

Gateway auto-recreated empty auth-profiles.json (39 bytes, {"version": 1, "profiles": {}}) during restart-1.

Restart cycle 2 — secondary's auth-profiles.json populated with copy of main's (both Outlook + XXX profiles, 4839 bytes, file-mtime preserved across restart):

12:27:59 [agent/embedded] embedded run failover decision: … decision=rotate_profile reason=rate_limit from=openai-codex/gpt-5.4-mini
12:27:59 [agents/harness] agent harness selected
12:28:01 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:28:02 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:28:06 [agent/embedded] auth profile failure state updated: … profile=sha256:a9ea55ebcea8 provider=openai-codex reason=rate_limit window=cooldown reused=false
12:28:06 [agent/embedded] codex app-server context-engine projection decision
12:28:08 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:28:09 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:28:11 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable
12:28:12 [agents/auth-profiles] used external cli oauth bootstrap because local oauth was missing or unusable

File-state empirically verified post-restart-2: agents/solenne/agent/auth-profiles.json retained 4839 bytes with both profile keys (openai-codex:[email protected] + openai-codex:[email protected]) — copy was NOT overwritten by gateway. The harness read the populated file and still treated it as missing-or-unusable.

Compound failures observed (four-axis)

1. Empty-file inheritance failure — empty auth-profiles.json treated as "missing or unusable" → harness bootstraps from external CLI (Codex binary ~/.codex/auth.json, single-account) instead of inheriting documented main-agent profiles.

2. Gateway auto-create-empty on absent — when auth-profiles.json is renamed/deleted, gateway auto-creates a 39-byte empty file ({"version": 1, "profiles": {}}) on next restart, making the documented absent-file inheritance path architecturally unreachable.

3. Populated-but-unusable — even with auth-profiles.json populated with valid named profiles (including unexpired access tokens + refresh tokens, copied from main agent), the harness still emits "used external cli oauth bootstrap because local oauth was missing or unusable" and falls back to binary-bootstrap. Populated ≠ usable from cross-agent context.

4. Companion-file dependencies (suspected) — secondary agent lacks two companion files that main agent has:

   • models.json — contains openai-codex provider config (baseUrl, api: openai-codex-responses, model list)
   • auth-state.json with lastGood + per-profile cooldownUntil/cooldownReason — secondary's auth-state has only raw usageStats, no rotation-guidance fields

   The harness may treat profiles as unusable when companion-files for routing + rotation-state are missing, even when profiles themselves are valid. The documented "inherit auth-profiles" mechanism is insufficient because per-agent auth-rig is multi-file.

Recommended fix-direction (for maintainer)

Either:

• (A) Codex harness inherits the full auth-rig (auth-profiles + models + auth-state) from main agent when secondary's files are absent/empty/incomplete; OR
• (B) Documentation explicitly specifies the full per-agent auth-rig file-set required + provides a openclaw agents sync-auth <agent-id> CLI command to bootstrap secondary agents from main; OR
• (C) Harness reads auth.order configuration and rotates profiles independent of bootstrap-source.

Current state forces operators to either (a) accept that secondary agents can't rotate OpenAI-Codex profiles on rate-limit-exhaustion, or (b) manually maintain duplicate auth-state across agents (which carries OAuth-token-drift risk on refresh).

Cross-references

• Related upstream issues (titles gh-verified):
  • #83088 "Stale explicit auth.order can collapse profile rotation after update" — state: OPEN (different mechanism; provider-adapter-side; reference for the auth.order-consumption code-path)
  • #82864 "Fix OpenAI Codex runtime provider routing" — state: MERGED (touches the bootstrap-from-binary code-path; closed-resolved-adjacent)
  • #83312 "Keep legacy Codex OAuth sidecar profiles usable" — state: MERGED (touches the migration repair-mechanism for legacy profile IDs; closed-resolved-adjacent)
  • PR #18067 (OpenClaw Process/Windows non-PTY exec fix; orthogonal subsystem; included only as cross-ref because settled in this morning's chair-team-recall but not load-bearing for this bug-shape)
• Code-references (from openclaw/dist code-trace):
  • openai-codex-provider-a0vn-mkC.js contains oauthProfileIdRepairs registry that flags openai-codex:default as legacy and should repair to named profiles
  • codex-route-warnings-mCfMWhB6.js has session-route repair mechanism but doesn't apply to empty auth-profiles

Open Qs for maintainer

1. Is the documented inheritance ("agents read through to main when they don't have a local profile") an aspirational design that hasn't been implemented for the Codex harness path specifically? If so, what is the intended scope?
2. Are auth-profiles cryptographically bound to the originating agent's session-state, blocking cross-agent reuse even when files are copied?
3. Is models.json provider-config required for the harness to recognize profiles as usable, or are profiles meant to be self-describing?