openclaw - 💡(How to fix) Fix [Bug]: Codex runtime/harness is too easy to confuse with gpt-*-codex model fallbacks [1 pull requests]

Summary

OpenClaw currently makes it too easy for agents/operators to conflate Codex runtime / harness routing with Codex-named model IDs such as openai/gpt-5.3-codex.

This has now caused repeated production config churn in one deployment: an agent was instructed to remove Codex runtime from normal sessions and keep them on Pi runtime, but repeatedly interpreted the string codex in the fallback model ID as runtime evidence and removed openai/gpt-5.3-codex from fallbacks. This happened three times total, twice in one morning.

The distinction that needs to be enforced by tooling/docs/doctor:

• agentRuntime.id = "codex" / Codex harness / Codex embedded runtime = runtime routing choice
• openai/gpt-5.3-codex = model ID; it can be valid when routed through Pi, e.g. agentRuntime.id = "pi"

Impact

This is causing chaos in normal operator workflows:

• Agents mutate fallback policy while trying to fix runtime policy.
• Removing openai/gpt-5.3-codex from fallbacks changes failure behavior and hides the original runtime/session issue rather than fixing it.
• Status/auth labels containing openai-codex or Codex-named models look like runtime evidence, even when persisted runtime/session route fields are Pi.
• The operator has to repeatedly catch and correct the same mistake.

Local repro / observed sequence

Environment:

• OpenClaw 2026.5.19-beta.2 / 947a070
• Normal lanes intended to use OpenClaw Pi runtime
• Default model: openai/gpt-5.5
• Intended fallback: openai/gpt-5.3-codex
• openai/gpt-5.3-codex model config has agentRuntime.id = "pi"

Operator instruction:

I don't want any of the sessions on codex runtime! move all sessions to pi runtime and add a rule never to use codex runtime

Agent actions/bug:

1. Correctly pinned OpenAI/provider/session runtime to Pi.
2. Incorrectly removed openai/gpt-5.3-codex from fallbacks because the model name contains codex.
3. Operator corrected this.
4. Agent repeated the same mistake again, despite already being corrected.

Final corrected local state:

defaultModel = openai/gpt-5.5
fallbacks = [openai/gpt-5.3-codex]
openai/gpt-5.3-codex agentRuntime.id = pi
models.providers.openai.agentRuntime.id = pi
nonPiSessionRows = 0
explicitCodexRuntimeRefs = 0
stale openai-codex provider labels = 0

Why this happens

There are multiple similarly named concepts visible to the agent/operator:

• provider key / auth label: sometimes openai-codex
• model ID: openai/gpt-5.3-codex
• Codex runtime / embedded harness
• agentHarnessId
• agentRuntime.id
• fallback model list
• stale systemPromptReport.provider labels in persisted session rows

A string search for codex across config/session state catches both runtime routing and model names. That is dangerous. The tooling does not currently provide a clear, canonical assertion like:

No normal sessions are using Codex runtime, while Codex-named model fallbacks are allowed if routed through Pi.

Requested fix

Please add one or more guardrails so this distinction is machine-checkable and hard to mess up:

1. openclaw doctor / openclaw models status should clearly separate:
   • runtime/harness route (pi, codex, etc.)
   • model ID (openai/gpt-5.3-codex)
   • fallback policy
2. Add a warning when a config/session audit appears to remove or flag a model solely because its ID contains codex while its agentRuntime.id is pi.
3. Add a route-policy check, e.g. openclaw doctor --runtime-policy normal=pi, that reports:
   • sessions using non-Pi runtime/harness
   • provider/session runtime refs equal to codex
   • stale provider labels separately from actual runtime refs
   • Codex-named models routed through Pi as OK, not failures
4. Documentation should explicitly say: Codex runtime/harness is not the same thing as gpt-*-codex model IDs.

Acceptance criteria

• A normal-lane deployment can verify “no Codex runtime” without removing openai/gpt-5.3-codex from fallbacks.
• Doctor/status output says something like:

Runtime policy: normal sessions on Pi: OK
Codex runtime refs: 0
Codex-named model fallbacks routed via Pi: OK
Fallbacks: openai/gpt-5.3-codex

• Stale labels such as systemPromptReport.provider=openai-codex are either refreshed or reported as labels, not treated as active runtime routing.