openclaw - 💡(How to fix) Fix Codex harness runs recreate legacy openai-codex session route state after doctor --fix

Summary

OpenClaw 2026.5.26 can recreate legacy openai-codex session-route state after openclaw doctor --fix has repaired it, even when durable config has already migrated to the newer user-facing route form:

"openai/gpt-5.5": {
  "agentRuntime": {
    "id": "codex"
  }
}

The Codex harness execution metadata correctly reports the internal harness provider as openai-codex, but session-store writers persist that internal provider into the user-facing session route as modelProvider: "openai-codex". That makes openclaw doctor --non-interactive warn again:

Legacy `openai-codex/*` session route state detected.
Affected sessions: N.
Run `openclaw doctor --fix` to rewrite stale session model/provider pins across all agent session stores.

Running doctor --fix clears the warning temporarily, but the next Codex-backed agent run can recreate it.

Environment

• OpenClaw version: 2026.5.26
• Install method: Homebrew/global npm install
• Runtime: gateway LaunchAgent using the Codex harness
• Agent model route: openai/gpt-5.5
• Model entry uses agentRuntime.id = "codex"
• Config no longer contains openai-codex/* model strings

Impact

• openclaw doctor reports stale Codex session routes repeatedly after they have been repaired.
• The warning is noisy and misleading because durable configuration has already been migrated.
• It can obscure real migration regressions during a stability soak.
• It may prompt operators to keep running doctor --fix, even though the next Codex run can recreate the warning.

Actual behavior

After doctor --fix, a new Codex-backed agent run writes a session row like:

{
  "modelProvider": "openai-codex",
  "model": "gpt-5.5"
}

The run metadata still has useful internal execution details:

{
  "agentMeta": {
    "provider": "openai-codex",
    "model": "gpt-5.5",
    "agentHarnessId": "codex"
  }
}

But that internal provider leaks into the persisted user-facing route, so doctor flags it as legacy state.

Expected behavior

When the configured route is openai/<model> with agentRuntime.id = "codex", OpenClaw should preserve the user-facing session route as:

{
  "modelProvider": "openai",
  "model": "gpt-5.5"
}

Execution metadata can still report the internal Codex harness provider as openai-codex.

In other words:

• Session route state should reflect the configured/public model route.
• Runtime metadata may reflect the internal execution harness.
• doctor --fix should stay fixed after subsequent Codex-backed runs.

Reproduction outline

1. Configure an agent to use an openai/* model with Codex runtime policy:

   {
     "agents": {
       "defaults": {
         "model": {
           "primary": "openai/gpt-5.5"
         },
         "models": {
           "openai/gpt-5.5": {
             "agentRuntime": {
               "id": "codex"
             }
           }
         }
       }
     }
   }

2. Ensure config has no openai-codex/* model strings.

3. Run:

   openclaw doctor --fix --non-interactive
   openclaw doctor --non-interactive

   Confirm no Legacy openai-codex session-route warning remains.

4. Run any Codex-backed agent turn that executes successfully.

5. Inspect the session store or rerun:

   openclaw doctor --non-interactive

6. Observe that modelProvider: "openai-codex" has been persisted again and doctor warns again.

Local patch shape

A local installed-runtime patch normalizes the persisted provider when the internal Codex harness provider is openai-codex but the configured/default route provider is openai.

Conceptually:

const rawProviderUsed =
  runResult.meta?.agentMeta?.provider ?? fallbackProvider ?? configuredProvider;

const providerUsed =
  rawProviderUsed === "openai-codex" &&
  (configuredProvider === "openai" ||
    config.agents.defaults.models[`openai/${modelUsed}`]?.agentRuntime?.id === "codex")
    ? "openai"
    : rawProviderUsed;

The second condition matters because recurring cron sessions reproduced the warning when their configured run provider was no longer available as a simple openai string by the time persistence ran. The durable model table still identified openai/<model> as the Codex-harness route, so that should be sufficient evidence to persist the user-facing provider as openai.

Likely source files

The corresponding source locations appear to be:

• src/auto-reply/reply/agent-runner.ts
• src/auto-reply/reply/followup-runner.ts
• src/agents/command/session-store.ts

Relevant source patterns:

const providerUsed =
  runResult.meta?.agentMeta?.provider ?? fallbackProvider ?? followupRun.run.provider;

const providerUsed =
  runResult.meta?.agentMeta?.provider ?? fallbackProvider ?? queued.run.provider;

const providerUsed =
  result.meta.agentMeta?.provider ?? fallbackProvider ?? defaultProvider;

Verification after local patch

After applying the local installed-runtime patch, restarting the gateway, and running a fresh Codex-backed no-delivery probe:

• Probe completed successfully.
• The probe ran one local shell command successfully.
• Final assistant text was PROBE_OK.
• Execution metadata still reported agentMeta.provider = "openai-codex".
• Persisted session row reported modelProvider = "openai".
• Session-store scan found zero stale route entries containing openai-codex.
• openclaw secrets audit --json remained clean for plaintext/unresolved/shadowed findings.
• Gateway health was OK and Telegram polling reconnected.

A later cron-backed reproduction required widening the local normalization to also recognize agents.defaults.models["openai/<model>"].agentRuntime.id === "codex" when deciding whether an internal openai-codex runtime provider should persist as the user-facing openai route.

Suggested regression tests

Add tests that cover both user-facing route persistence paths:

1. src/agents/command/session-store.test.ts

   Scenario:

   • defaultProvider = "openai"
   • defaultModel = "gpt-5.5"
   • result.meta.agentMeta.provider = "openai-codex"
   • result.meta.agentMeta.model = "gpt-5.5"

   Expected:

   • Stored modelProvider is openai
   • Stored model is gpt-5.5
   • Runtime metadata remains otherwise intact where applicable

2. Auto-reply/follow-up runner persistence test

   Scenario:

   • followupRun.run.provider = "openai" or queued.run.provider = "openai"
   • Agent metadata reports provider = "openai-codex"

   Expected:

   • Persisted session route is openai/gpt-5.5
   • Doctor route scan does not flag the new session

3. Doctor integration-style test

   Scenario:

   • Run doctor --fix on a stale session store
   • Simulate a successful Codex-backed turn
   • Run the Codex session route scanner

   Expected:

   • No Legacy openai-codex session route warning returns

Related observation, probably separate issue

Repeated openclaw doctor --fix --non-interactive runs also rewrote a local generated provider cache in a way that reintroduced a plaintext providers.codex.apiKey value, even though the active auth profile was backed by a file SecretRef.

That was locally normalized back to a secret-managed marker after each doctor repair. This may deserve a separate upstream issue if it is reproducible in a clean environment.