openclaw - 💡(How to fix) Fix [Bug]: "Requested agent harness 'codex' is not registered" on Codex-primary agents (regression from 5.7)

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

After upgrading from 2026.5.7 → 2026.5.12, every agent turn through openai-codex/* models fails in gateway.err.log with:

[diagnostic] lane task error: lane=main durationMs=331 
  error="Error: Requested agent harness \"codex\" is not registered."
[model-fallback/decision] model fallback decision: 
  decision=candidate_failed 
  requested=openai-codex/gpt-5.5 
  candidate=openai-codex/gpt-5.5 
  reason=unknown 
  next=google/gemini-3.1-flash-lite-preview 
  detail=Requested agent harness "codex" is not registered.

On the default agent (main), the failure is silently masked by the Gemini fallback — /status still shows openai-codex/gpt-5.5 as primary but the actual resolved model is the fallback. Secondary agents without working fallbacks surface a user-visible "Something went wrong while processing your request. Please try again, or use /new to start a fresh session."

Steps to reproduce

• Multi-agent setup: 3 agents (main, jim, clawson), all configured with agents.defaults.model.primary: openai-codex/gpt-5.5 and a 7-fallback chain starting with Gemini

1. Pre-state: Multi-agent setup on 2026.5.7, primary openai-codex/gpt-5.5 working via OAuth
2. sudo npm i -g [email protected]
3. sudo chown -R $(id -u):$(id -g) ~/.npm && sudo chown -R $(whoami) /usr/local/lib/node_modules/openclaw/dist/extensions/
4. launchctl kickstart -k "gui/$(id -u)/ai.openclaw.gateway"
5. Send message to any Codex-primary agent via Telegram
6. Observe: harness-not-registered error fires on every turn; main silently uses Gemini fallback

Expected behavior

After upgrading from 2026.5.7 to 2026.5.12, agents configured with agents.defaults.model.primary: openai-codex/gpt-5.5 should continue resolving to the openai-codex provider/harness and serve traffic via the existing OAuth profile at ~/.codex/auth.json, with no config changes required. The fallback chain should remain dormant under normal operation.

Actual behavior

Every agent turn through openai-codex/* fails with Error: Requested agent harness "codex" is not registered. The resolver maps openai-codex/* model refs to harness key "codex" (the pre-rename name), but only "openai-codex" is registered in the 5.12 runtime.

On the default agent (main), the failure is silently masked by the configured Gemini fallback — /status continues to display openai-codex/gpt-5.5 as the model line, but the actual resolved model is google/gemini-3.1-flash-lite-preview, indicated by the ↪️ Fallback: ... (selected model unavailable) line. Users only notice degraded behavior (different model voice, different latency, unexpected cost on paid fallback providers).

On secondary agents with shorter or unavailable fallback chains, every turn returns a user-visible "Something went wrong while processing your request. Please try again, or use /new to start a fresh session." The lane error and model-fallback decision both fire on every turn (visible in gateway.err.log).

openclaw models list post-upgrade shows BOTH openai-codex/* and codex/* entries side-by-side, suggesting catalog regen logic emits the deprecated namespace alongside the canonical one. Per-agent ~/.openclaw/agents/<id>/agent/models.json files regenerated on 5.12 startup contain both openai-codex and codex provider keys.

OpenClaw version

OpenClaw 2026.5.12 (f066dd2)

Operating system

macOS 14 (Mac mini, Intel)

Install method

npm global

Model

openai-codex/gpt-5.5

Provider / routing chain

openclaw -> gpt-5.5

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Impact and severity

High — Codex-primary agents are non-functional on 5.12 unless a working fallback exists. Default agent (main) appears to work but is actually running on fallback model, with degraded behavior and unexpected cost on paid fallback providers.

Additional information

Diagnostic findings

• openclaw models list shows BOTH openai-codex/* AND codex/* entries side-by-side
• Per-agent ~/.openclaw/agents/<id>/agent/models.json files regenerated on 5.12 first-start contain BOTH openai-codex AND codex as provider keys
• agents.defaults.model.primary in openclaw.json correctly references openai-codex/gpt-5.5 (the canonical name)
• The "codex" harness appears NOT to be registered in the 5.12 runtime, only "openai-codex" is
• The resolver, when handed openai-codex/gpt-5.5, internally dispatches to harness key "codex" (the pre-rename name) and fails

Hypothesis

Several 5.12 release notes describe Codex refactoring:

• "Codex runtime: allow the official installed @openclaw/codex package to use its private task-runtime..."
• "Codex harness: classify native app-server token-refresh logout..."
• "Codex/OpenAI: ...auth-profile-backed media tools, MCP server projection..."

Looks like Codex was substantially rewired in 5.12. The harness-name resolution layer appears to retain the deprecated "codex" lookup path while the registration side has moved to "openai-codex". Catalog regeneration also emits both keys, suggesting the rename wasn't completed across all code paths.

Workaround

Rolled back to 2026.5.7 via sudo npm i -g [email protected]. Codex resolves correctly on 5.7 (no harness key mismatch).

Notes

• Independent of this bug, ~/.codex/auth.json had also expired (5 days old, refresh token wedged). Recovery required codex logout && codex login from the Codex CLI — OpenClaw's openclaw models auth login --provider openai-codex writes a new auth profile bundle but does NOT refresh ~/.codex/auth.json, so tokens stay stale. This may be related to the 5.12 release note "Auth: reclaim dead-owner stale file locks before retrying locked writes" which was intended to fix it but didn't help in our case.
• ~/.codex/auth.json token store survives the OpenClaw upgrade cycle but is independent from OpenClaw's own auth-profiles.json store; the two need explicit refresh paths.