Bug: upgrade/doctor can leave codex harness unregistered, causing live Telegram sessions to silently fall back from GPT-5.5 to Sonnet

Summary

After upgrading OpenClaw on May 17, 2026, a live Telegram agent that had been running on GPT-5.5 via the Codex/OpenAI-Codex route started failing with:

Requested agent harness "codex" is not registered.

OpenClaw then silently fell back to Sonnet for the live Telegram session instead of failing closed.

The main user-visible symptom was: "the bot was working perfectly before the upgrade, then it suddenly started answering from Sonnet / erroring on Telegram."

Why this is a bug

This is not just a missing-plugin issue. It creates silent model drift for a live production bot:

• the configured/runtime-pinned model remained Codex/GPT-5.5
• the required codex harness disappeared after upgrade / doctor / plugin state changes
• existing sessions still tried to use that harness
• the platform then fell back to Sonnet instead of loudly failing

For users who depend on a specific runtime/model, this is a trust and correctness issue, not just a reliability issue.

Environment

• OpenClaw: 2026.5.12
• macOS: 15.7.4 (arm64)
• Channel: Telegram
• Intended runtime before/after fix: gpt-5.5 with thinking=high on the codex harness

Timeline

All times below are America/Los_Angeles on May 17, 2026.

1. Upgrade / doctor rewrites config

Around 1:05:51 PM PT, the local logs show openclaw doctor overwriting the main config:

Config overwrite: /Users/.../.openclaw/openclaw.json

Immediately after that, the gateway logged an invalid config reload:

config reload skipped (invalid config): ... Cannot find module '/opt/homebrew/lib/node_modules/openclaw/dist/legacy-config-issues-DgaYUYns.js'

This suggests the upgrade / doctor flow destabilized config/plugin/runtime state before the later Telegram failure.

2. Existing Telegram session remains active on Codex/GPT-5.5

The Telegram direct session remained live and was still tied to the Codex route.

3. First hard break

At 2:33:25 PM PT, the session hit compaction/context pressure while still on the Codex path.

At 2:33:44 PM PT, the gateway started throwing:

Requested agent harness "codex" is not registered.

4. Silent fallback to Sonnet

Immediately after the harness-resolution failure, the gateway logged model fallback to Sonnet instead of failing closed.

Representative log line:

[model-fallback/decision] model fallback decision: decision=candidate_failed requested=openai/gpt-5.5 candidate=openai/gpt-5.5 reason=unknown next=anthropic/claude-sonnet-4-20250514 detail=Requested agent harness "codex" is not registered.

Then:

[model-fallback/decision] model fallback decision: decision=candidate_succeeded requested=openai/gpt-5.5 candidate=anthropic/claude-sonnet-4-20250514 reason=unknown next=none

What I found

After the break:

• the active config/session state still referenced the codex harness
• but the actual codex plugin/harness was no longer registered in the runtime
• openclaw plugins list did not initially show a loaded Codex harness
• Telegram session metadata had stale routing/auth state and continued trying to use the broken path

The key failure mode was:

1. session still wants codex
2. runtime no longer has codex
3. fallback policy silently routes to Sonnet

Manual recovery that fixed it

The bot was recovered only after all of the following:

1. install/reinstall the official Codex plugin:

openclaw plugins install clawhub:@openclaw/codex

1. restore the active config so the Telegram agent is pinned back to the intended route:

• openai/gpt-5.5@openai-codex:[email protected]
• agentRuntime.id = "codex"
• thinking = high
• fallbacks = []

1. repair the live session metadata so it no longer carried the wrong runtime/profile state

2. restart the gateway

After that, the same Telegram main session completed successfully on:

• provider = openai
• model = gpt-5.5
• agentHarnessId = codex
• fallbackUsed = false

and a live Telegram delivery succeeded.

Expected behavior

Any of these would be much safer than the current behavior:

Option A

If a configured harness disappears after upgrade, auto-install/re-enable the required plugin when the config/session references it.

Option B

If a configured harness cannot be resolved, fail closed and surface a prominent operator-visible error instead of falling back to another provider/model.

Option C

On upgrade/migration/plugin changes, invalidate or rebind existing sessions that still reference a now-missing harness.

Strong recommendation

At minimum, when the root failure is:

Requested agent harness "codex" is not registered.

OpenClaw should not silently model-fallback to Sonnet for a live user-facing bot.

That should be treated as a routing integrity failure, not a normal model availability failure.

Relevant local evidence

These were the most useful local signals:

• gateway.err.log
  • Requested agent harness "codex" is not registered.
  • fallback decision to Sonnet
• gateway.log
  • Telegram inbound messages were still arriving
  • the bot was failing in-session after the upgrade state change
• /tmp/openclaw/openclaw-2026-05-17.log
  • doctor overwrote config earlier that day
  • invalid config reload / missing internal module warning appeared before the later harness failure

Impact

This caused:

• production Telegram bot instability
• silent drift from intended model/runtime to another provider
• loss of trust because the assistant was no longer running on the requested stack

If useful, I can provide a redacted session/config diff, but the core bug seems to be:

upgrade/doctor/plugin-state change can orphan the codex harness while existing sessions still reference it, and fallback then masks the routing failure by switching models.