Summary

• Problem: openclaw doctor --fix can rewrite openai-codex/* routes to canonical openai/* while replacing an explicit non-default agentRuntime pin, such as pi, with codex.
• Solution: carry the pre-repair runtime pin through the route migration and write a narrow canonical model-scoped runtime policy when needed.
• What changed: preserve explicit runtime pins from legacy agent model maps, provider-level runtime policy, and provider catalog model policy; add regression coverage for those cases and for listed-agent shielding.
• What did NOT change (scope boundary): this does not investigate or claim to fix the separate gpt-5.5 token-usage behavior discussed on [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038, and it does not edit CHANGELOG.md.

Motivation

#84362 is the ClawSweeper replacement for #84142, but that bot-owned branch is currently blocked by a CHANGELOG.md conflict. This PR provides the same fix path on current upstream/main, deliberately avoiding the contributor-forbidden changelog edit, and includes the tested follow-up runtime-pin cases.

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 #
• Related [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 explicit agentRuntime pin during codex model migration [AI-assisted] #84142
• Related fix(doctor): preserve explicit agentRuntime pin during codex model migration [AI-assisted] #84362
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: openclaw doctor --fix route repair preserves explicit non-default runtime pins when migrating openai-codex/gpt-5.4 to openai/gpt-5.4.
• Real environment tested: local OpenClaw source checkout on Linux, Node v22.22.1, current upstream/main branch with this patch applied.
• Exact steps or command run after this patch:

OPENCLAW_REPO=/tmp/openclaw-84038-clean-20260521 pnpm exec tsx /tmp/repro-openclaw-84038-runtime-pin-matrix.mjs

• Evidence after fix:

Terminal output from the runtime resolver / doctor repair matrix:

scenario: model-map PI pin survives legacy openai-codex model map rewrite
beforeRuntime: pi
defaultPolicy: { id: pi }
afterRuntime: pi
pass: true

scenario: provider-level PI pin survives route repair
beforeRuntime: pi
defaultPolicy: { id: pi }
afterRuntime: pi
pass: true

scenario: provider-catalog model PI pin survives route repair
beforeRuntime: pi
defaultPolicy: { id: pi }
afterRuntime: pi
pass: true

scenario: defaults PI repair does not leak into listed canonical Codex agent
beforeRuntime: { defaults: pi, regular: codex }
defaultPolicy: { id: pi }
listedPolicy: { id: codex }
afterRuntime: { defaults: pi, regular: codex }
pass: true

GREEN: all runtime pin repair scenarios preserved expected runtimes

• Observed result after fix: legacy openai-codex/* routes are rewritten to canonical openai/*, while explicit pi runtime pins remain effective for the repaired route. A listed agent that already explicitly uses canonical OpenAI with Codex routing keeps codex instead of inheriting the repaired defaults-level pi policy.
• What was not tested: full CI, a live PI OAuth login, and the separate gpt-5.5 token-usage behavior discussed in [Bug]: doctor --fix silently migrates intentional openai-codex/ config to openai/, breaking PI+OAuth runtime and causing 3-4x token inflation #84038.
• Before evidence (optional but encouraged): the same matrix on current upstream/main repaired all four scenarios to agentRuntime.id = "codex" and ended with RED: one or more runtime pins were not preserved across doctor route repair.

Root Cause (if applicable)

• Root cause: route repair synthesized a canonical openai/* Codex runtime policy before considering explicit pre-repair non-default runtime pins from legacy openai-codex/* model-map entries, provider-level policy, or provider catalog model policy.
• Missing detection / guardrail: existing tests covered the default Codex repair path, but not the explicit non-Codex runtime-pin carriers or the listed-agent shield when defaults repair introduces a non-Codex runtime policy.
• Contributing context (if known): older route-repair behavior needed to preserve Codex auth routing after canonicalization, but that default should not override an explicit user runtime choice.

Regression Test Plan (if applicable)

• 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: model-map, provider-level, and provider-catalog runtime pins survive route repair; defaults-level preservation does not leak into listed canonical Codex agents.
• Why this is the smallest reliable guardrail: maybeRepairCodexRoutes plus the runtime resolver exercises the doctor repair output and the effective runtime selection without needing a live provider credential.
• Existing test that already covers this (if any): existing Codex route-repair tests covered canonical Codex behavior, not these explicit runtime-pin preservation cases.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

openclaw doctor --fix still canonicalizes legacy openai-codex/* route refs, but now preserves explicit non-default runtime pins instead of silently moving those repaired routes onto Codex runtime.

Diagram (if applicable)

Before:
openai-codex/gpt-5.4 + explicit pi runtime -> doctor --fix -> openai/gpt-5.4 + codex runtime

After:
openai-codex/gpt-5.4 + explicit pi runtime -> doctor --fix -> openai/gpt-5.4 + pi runtime

Security Impact (required)

• 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
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node v22.22.1 local source checkout
• Model/provider: openai-codex/gpt-5.4 repaired to openai/gpt-5.4
• Integration/channel (if any): N/A
• Relevant config (redacted): synthetic doctor config with explicit agentRuntime.id = "pi" in model-map, provider-level, and provider-catalog shapes

Steps

1. Run the runtime-pin matrix against current upstream/main and observe RED.
2. Apply this patch.
3. Rerun the runtime-pin matrix and targeted doctor tests.

Expected

• Repaired canonical openai/gpt-5.4 routes preserve explicit pi runtime pins.
• Existing Codex route repair behavior remains green.

Actual

• Matrix proof is GREEN after this patch.
• Targeted tests pass.

Evidence

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

Verification commands run locally:

OPENCLAW_REPO=/tmp/openclaw-84038-clean-20260521 pnpm exec tsx /tmp/repro-openclaw-84038-runtime-pin-matrix.mjs
node scripts/run-vitest.mjs src/commands/doctor/shared/codex-route-warnings.test.ts
node scripts/run-vitest.mjs src/commands/doctor/repair-sequencing.test.ts
node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo
pnpm exec oxfmt --check --threads=1 src/commands/doctor/shared/codex-route-warnings.ts src/commands/doctor/shared/codex-route-warnings.test.ts
git diff --check upstream/main..HEAD

Results:

runtime-pin matrix: GREEN
codex-route-warnings.test.ts: 103 passed
repair-sequencing.test.ts: 10 passed
tsgo core: exit 0
oxfmt touched files: All matched files use the correct format.
git diff --check: passed

Human Verification (required)

• Verified scenarios: model-map runtime pin, provider-level runtime pin, provider-catalog model runtime pin, listed-agent shielding, existing Codex repair tests, repair sequencing tests, typecheck, formatting, and whitespace checks.
• Edge cases checked: auto / default runtime policy is not treated as an explicit pin; listed canonical agents keep Codex when defaults repair preserves PI; contributor PR avoids CHANGELOG.md.
• What you did not verify: full CI, live OAuth login, runtime token consumption, and maintainer-side ClawSweeper automerge.

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.

No bot review conversations exist on this new PR at creation time.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: preserving a non-Codex runtime pin during defaults repair could accidentally affect listed agents that explicitly use canonical OpenAI/Codex routing.
  • Mitigation: the patch shields explicitly listed canonical agents and adds a regression test/proof where defaults remain pi while the listed agent remains codex.
• Risk: provider-level and provider-catalog policy lookup could be broader than intended.
  • Mitigation: tests cover model-map precedence, provider-level pins, provider-catalog model pins, and existing repair sequencing remains green.

AI assistance disclosure

This PR is AI-assisted. I reviewed the diff and ran the verification listed above.