Summary

• Problem: openclaw doctor --fix silently overwrote an explicit agentRuntime: { id: "pi" } opt-out with { id: "codex" } while migrating legacy openai-codex/* model refs to canonical openai/* form, flipping the user from the PI runtime back onto the native Codex runtime (3-4× token inflation per request, per [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038).
• Solution: Skip the default-codex pin synthesis on the canonical model entry when a legacy openai-codex/* form of that model ref already has an explicit non-default agentRuntime.id (anything other than auto / default / missing). rewriteModelsMap then carries the legacy pin forward through its existing legacy-wins fallback branch.
• What changed: src/commands/doctor/shared/codex-route-warnings.ts (+24, -0). New helper legacyEntryHasExplicitNonDefaultRuntimePin(models, canonicalModelRef) plus one guard in ensureCodexRuntimePolicy before setModelRuntimePolicy.
• What did NOT change (scope boundary): Session-store stale-pin clearing (repairCodexSessionStoreRoutes, clearStaleSessionRuntimePins) is untouched. Top-level agents.defaults.agentRuntime clearing (clearLegacyAgentRuntimePolicy) is untouched. The migration of model refs themselves (openai-codex/X → openai/X) is unchanged. auto / default runtime pins remain overwritable.

Motivation

The native Codex runtime currently produces 3-4× the token usage of the PI runtime for the same GPT-5.x request (the upstream Codex issue OpenClaw cannot fix at the provider layer). Users who explicitly pin agentRuntime: { id: "pi" } to opt out of this need that opt-out to survive doctor --fix. Every doctor run today silently puts them back on the broken runtime.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038
• Related fix(doctor): preserve unknown web search records #83315 (same "preserve user fields during legacy migration" pattern in tools.web.search; cited as design precedent below)
• This PR fixes a bug or regression

Real behavior proof

• Behavior or issue addressed: doctor --fix overwrites agents.defaults.models["openai-codex/gpt-5.4"].agentRuntime = { id: "pi" } with { id: "codex" } while migrating the legacy openai-codex/* model ref to openai/*, silently re-enrolling the user into the native Codex runtime they explicitly opted out of.

• Real environment tested: Local fresh worktree off upstream/main f07c87405c on Linux 6.17.0 (Node 22.22.1, pnpm 11.1.0). Two sibling worktrees: baseline (upstream/main, no fix) at /tmp/openclaw-84038-baseline and fix branch at /tmp/openclaw-84038. Production maybeRepairCodexRoutes (the same function src/commands/doctor/repair-sequencing.ts:82 calls during openclaw doctor --fix) invoked directly against the exact 4-key user config from [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038.

• Exact steps or command run after this patch:

  # In each worktree (baseline and fix branch):
  node --import tsx ./_proof-trace.mjs
  #   _proof-trace.mjs imports { maybeRepairCodexRoutes }
  #   from src/commands/doctor/shared/codex-route-warnings.ts and calls it
  #   with shouldRepair: true on the issue body's exact config.

• Evidence after fix:

Terminal capture from this branch, copied live output:

=== INPUT CONFIG (user's #84038 setup) ===
  {
    "agents": {
      "defaults": {
        "model": { "primary": "openai-codex/gpt-5.4" },
        "models": {
          "openai-codex/gpt-5.4": { "agentRuntime": { "id": "pi" } }
        }
      }
    },
    "auth": { "order": { "openai-codex": ["openai-codex:user@example.com"] } },
    "plugins": { "entries": { "codex": { "enabled": false } } }
  }

  === DOCTOR CHANGES ===
  Repaired Codex model routes:
  - agents.defaults.model.primary: openai-codex/gpt-5.4 -> openai/gpt-5.4.
  - agents.defaults.models.openai-codex/gpt-5.4: openai-codex/gpt-5.4 -> openai/gpt-5.4.

  === POST-MIGRATION CONFIG (agents block) ===
  {
    "defaults": {
      "model": { "primary": "openai/gpt-5.4" },
      "models": {
        "openai/gpt-5.4": { "agentRuntime": { "id": "pi" } }
      }
    }
  }

agentRuntime preserved as { id: pi }?: YES

• Observed result after fix: the legacy openai-codex/gpt-5.4 model ref is migrated to canonical openai/gpt-5.4, the corresponding map entry follows the rename, and the user's explicit agentRuntime: { id: "pi" } opt-out is preserved on the migrated entry. The previous "Set agents.defaults.models.openai/gpt-5.4.agentRuntime.id to 'codex'" line is correctly absent because no synthesized default needs setting, and plugins.entries.codex.enabled stays false as the user requested (no spurious auto-enable, because no route now claims the codex runtime).

• What was not tested: live gateway runtime / actual provider request emission (the runtime resolution side is exercised by existing resolveAgentHarnessPolicy tests in codex-route-warnings.test.ts at L3000-3006 and L3036-3042 covering both pi and codex shapes), and the macOS install path the original reporter is on (the migration code path is platform-agnostic, so the issue surface should reproduce / fix on macOS the same way).

• Before evidence (baseline, same script same input on upstream/main f07c87405c):

  === DOCTOR CHANGES (BEFORE FIX) ===
  Repaired Codex model routes:
  - agents.defaults.model.primary: openai-codex/gpt-5.4 -> openai/gpt-5.4.
  - agents.defaults.models.openai-codex/gpt-5.4: openai-codex/gpt-5.4 -> openai/gpt-5.4.
  Set agents.defaults.models.openai/gpt-5.4.agentRuntime.id to "codex" so repaired OpenAI refs keep Codex auth routing.
  Enabled plugins.entries.codex because configured agent routes use Codex runtime.
  
  === POST-MIGRATION CONFIG (agents block) ===
  {
    "defaults": {
      "model": { "primary": "openai/gpt-5.4" },
      "models": {
        "openai/gpt-5.4": { "agentRuntime": { "id": "codex" } }
      }
    }
  }
  
  agentRuntime preserved as { id: pi }?: NO (got {"id":"codex"})
  

Root Cause

• Root cause: in rewriteAgentModelRefs, the AGENT_MODEL_CONFIG_KEYS loop processes model first and calls preserveCodexRuntimePolicyForNewHits → ensureCodexRuntimePolicy(modelRef="openai/X") while the canonical entry models["openai/X"] does not yet exist. ensureCodexRuntimePolicy synthesizes { agentRuntime: { id: "codex" } } on a fresh empty entry. rewriteModelsMap then renames openai-codex/X → openai/X, and its { ...legacyRecord, ...canonicalRecord } spread places the just-synthesized codex pin last, silently dropping the user's { id: "pi" }.
• Missing detection / guardrail: ensureCodexRuntimePolicy only looked at the canonical entry's existing agentRuntime when deciding whether to synthesize. It did not consider that a legacy form of the same model ref in the same models map might carry an explicit non-default pin the user expected to keep through the migration.
• Contributing context (if known): two existing tests in codex-route-warnings.test.ts already encode the maintainer intent to preserve such pins — "preserves explicit model-scoped runtime pins when repairing legacy model map keys" (L2974) for the models-map-only case, and "overwrites non-concrete model-scoped runtime pins when preserving Codex route intent" (L3009) for the auto/default case. The combined-config path (legacy ref present in BOTH model.primary and models[...]) was the previously uncovered seam.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/commands/doctor/shared/codex-route-warnings.test.ts
• Scenario the test should lock in: user has agents.defaults.model.primary = "openai-codex/X" AND agents.defaults.models["openai-codex/X"].agentRuntime = { id: "pi" }. After maybeRepairCodexRoutes({ shouldRepair: true }), the migrated entry models["openai/X"] must have agentRuntime = { id: "pi" }, and models["openai-codex/X"] must be gone.
• Why this is the smallest reliable guardrail: the bug is purely in the rewrite sequence inside rewriteAgentModelRefs; a unit-level config-in/config-out assertion against maybeRepairCodexRoutes exercises the full repair pipeline (model-slot rewrite, ensureCodexRuntimePolicy decision, rewriteModelsMap rename + merge) without needing a real gateway or provider auth wiring.
• Existing test that already covers this (if any): No. L2974 is similar but covers the model.primary-absent variant which already passes today; the combined-config variant from [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038 was uncovered.
• If no new test is added, why not: N/A — added as a new it(...) block (RED on the prior commit cd0f8f800e, GREEN on the fix commit 9d932635ae).

User-visible / Behavior Changes

• openclaw doctor --fix no longer rewrites agentRuntime.id to "codex" on a canonical openai/X entry when a legacy openai-codex/X form of the same model ref carries an explicit non-default pin (e.g. { id: "pi" }). The legacy pin survives the rename.
• As a direct downstream consequence, plugins.entries.codex is no longer auto-enabled in that scenario (the migrated route now claims the pi runtime, not codex, so enableCodexPluginForRequiredRoutes does not need to touch the plugin entry). This matches the user's stated intent in [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038 ("explicitly disabled the codex plugin"). Users who left agentRuntime unset, or set it to auto / default / codex, see no behavior change.

Diagram

Before fix:
[user config]
  model.primary = "openai-codex/X"
  models["openai-codex/X"].agentRuntime = { id: "pi" }
        |
        v
[AGENT_MODEL_CONFIG_KEYS loop processes "model"]
  -> rewrite model.primary to "openai/X" (hit added)
  -> preserveCodexRuntimePolicyForNewHits -> ensureCodexRuntimePolicy("openai/X")
     -> models["openai/X"] does not exist yet
     -> SYNTHESIZE models["openai/X"] = { agentRuntime: { id: "codex" } }
        |
        v
[rewriteModelsMap renames legacy key]
  -> legacyRecord  = { agentRuntime: { id: "pi" } }     # user's pin
  -> canonicalRecord = { agentRuntime: { id: "codex" } } # synthesized above
  -> merge spread { ...legacy, ...canonical }
     -> canonical wins -> { agentRuntime: { id: "codex" } }   # USER'S PIN LOST

After fix:
[same user config]
        |
        v
[AGENT_MODEL_CONFIG_KEYS loop processes "model"]
  -> rewrite model.primary to "openai/X" (hit added)
  -> preserveCodexRuntimePolicyForNewHits -> ensureCodexRuntimePolicy("openai/X")
     -> models["openai/X"] does not exist yet
     -> legacyEntryHasExplicitNonDefaultRuntimePin(models, "openai/X") = true
        (legacy form "openai-codex/X" has agentRuntime.id = "pi")
     -> EARLY RETURN, no synthesis
        |
        v
[rewriteModelsMap renames legacy key]
  -> legacyRecord  = { agentRuntime: { id: "pi" } }
  -> canonicalRecord = undefined   (nothing synthesized)
  -> falsy branch -> canonicalEntry ?? legacyEntry -> legacyEntry
     -> models["openai/X"] = { agentRuntime: { id: "pi" } }   # PIN PRESERVED

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

The patch is a local config-rewrite decision change. No auth, secret, capability, network, or filesystem surface changes.

Repro + Verification

Environment

• OS: Linux 6.17.0-14-generic
• Runtime/container: Node 22.22.1, pnpm 11.1.0
• Model/provider: N/A (config-mutation path, no provider request emitted during the migration)
• Integration/channel (if any): N/A
• Relevant config (redacted): the four top-level keys from the issue body — agents, auth, plugins — verbatim as posted in [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038.

Steps

1. Check out upstream/main f07c87405c in worktree A and fix/84038-preserve-pi-runtime in worktree B.
2. In each worktree, run pnpm install --prefer-offline.
3. Drop the same _proof-trace.mjs into each worktree. The script imports maybeRepairCodexRoutes from src/commands/doctor/shared/codex-route-warnings.ts and calls it with shouldRepair: true on the issue's exact config.
4. In each worktree, run node --import tsx ./_proof-trace.mjs and compare stdout.

Expected

• After fix: models["openai/gpt-5.4"].agentRuntime = { id: "pi" }. No Set agents.defaults.models.openai/gpt-5.4.agentRuntime.id to "codex" line in changes. No Enabled plugins.entries.codex line.

Actual

• After fix: matches expected (see Evidence above).
• Before fix (baseline): models["openai/gpt-5.4"].agentRuntime = { id: "codex" }, with both the Set ... and Enabled ... lines present in changes.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Live-output evidence captured in the Real behavior proof section above. Repro test landed in src/commands/doctor/shared/codex-route-warnings.test.ts (it("preserves an explicit non-default agentRuntime pin on the legacy model entry during migration (#84038)", ...)). Lint, typecheck, and the full codex-route-warnings.test.ts + repair-sequencing.test.ts sweep all pass; these are supplemental to the live-output evidence.

Human Verification

• Verified scenarios:
  • User's exact 4-key config from [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038 → migration runs, pin preserved (live node --import tsx output captured both directions).
  • Same config on upstream/main baseline → migration runs, pin overwritten (matches the user's reported regression).
  • Existing scenarios kept locked in: 92/92 in codex-route-warnings.test.ts, 10/10 in repair-sequencing.test.ts. Specifically L2974 ("preserves explicit model-scoped runtime pins when repairing legacy model map keys" — pi pin preserved when only models map is set, no model.primary) and L3009 ("overwrites non-concrete model-scoped runtime pins when preserving Codex route intent" — auto pin still gets overwritten by codex).
• Edge cases checked:
  • agentRuntime: { id: "auto" } legacy pin → not preserved (still overwritten by codex synthesis; matches existing maintainer intent).
  • agentRuntime: { id: "default" } legacy pin → not preserved (same as auto).
  • No legacy agentRuntime at all → unchanged (codex synthesis still happens).
  • User has both legacy and canonical entries with explicit pins → canonical entry's pin already has explicit value, ensureCodexRuntimePolicy's existing pre-check returns early, no synthesis happens, rewriteModelsMap keeps canonical via its current spread order.
• What you did not verify: live gateway / provider request emission (the runtime resolution is exercised by existing resolveAgentHarnessPolicy tests in the same file); the macOS install path the original reporter is on (the migration logic is platform-agnostic).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A. Users with no agentRuntime pin (the vast majority) see identical doctor behavior. Users on a non-default explicit pin keep it after upgrade — no manual reapply needed anymore.

Risks and Mitigations

• Risk: a user who genuinely WANTED their agentRuntime: { id: "pi" } (or similar non-codex pin) on a legacy openai-codex/X ref to be REPLACED by { id: "codex" } during migration no longer gets that automatic replacement.
  • Mitigation: this is the bug, not a new risk. The previous behavior was silently incorrect — an explicit pin meant the user did not want default codex. Existing test "overwrites non-concrete model-scoped runtime pins when preserving Codex route intent" (L3009) keeps auto / default overwritable for users who want default-policy behavior. A user who actually wants codex can set { id: "codex" } explicitly, which the fix also leaves alone (existing ensureCodexRuntimePolicy early-exit on concrete non-default pin handles this case).
• Risk: behavior change to plugins.entries.codex auto-enable. When the user's preserved pin is non-codex, the migrated route no longer claims the codex runtime, so the codex plugin is no longer auto-enabled.
  • Mitigation: this matches stated user intent in [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038 ("explicitly disabled the codex plugin"). Auto-enable still fires for users without an explicit non-default pin.

AI-assisted disclosure

• AI-assisted — diagnosis and fix authored with Claude Opus 4.7 in a NexCore agent session. Real-behavior proof above was captured by directly invoking the production maybeRepairCodexRoutes function from a Node script on the human-operator's machine using the exact user config from the issue body. Co-author trailer: Co-Authored-By: Nex <nex@dbitstec.com>.
• I understand what the code does, the trigger sequence inside rewriteAgentModelRefs, why ensureCodexRuntimePolicy is the right place for the early-return, and the trade-off vs reordering rewriteModelsMap (a second considered approach, rejected because it shifts an existing snapshot test's expected changes[] ordering for no semantic gain).
• Session log available on request; not attached to keep PR body focused.
• codex review --base origin/main was not run because Codex CLI is not installed on the human-operator's local machine. Equivalent diff-review steps performed: typecheck (pnpm check:changed --base upstream/main, lane check-prod-types + check-test-types), lint (oxlint 0 warnings 0 errors on 8650 files / 217 rules), oxfmt --check clean, repro test exercises the exact behavior.
• Will resolve bot review conversations after addressing them; will not leave bot threads dangling for maintainers.