Gitpulse
Merged
Size
M
Change Breakdown
Bug Fix65%
Testing20%
Docs15%
#40143fix(doctor): warn when stale Codex overrides shadow OAuth

Codex OAuth shadowing detected by doctor

BR
briandevans
·Apr 8, 2026

The openclaw doctor command now warns when legacy manual transport overrides for models.providers.openai-codex are detected alongside active Codex OAuth profiles, helping users recover from a silent configuration conflict that can persist across upgrades.

Users who manually configured Codex transport settings before recent OAuth fixes can remain stuck even after upgrading to versions with the corrected built-in provider. Their legacy models.providers.openai-codex override silently shadows the built-in Codex OAuth path, causing 401 errors or fallback behavior that looks like an OAuth bug rather than a stale config problem.

The openclaw doctor command now detects this conflict. When a legacy transport override exists alongside a configured or stored Codex OAuth profile, doctor emits a targeted warning explaining the issue and pointing users to remove the stale override. The warning distinguishes between legacy OpenAI transport settings and supported custom proxy or header-only overrides, so it only fires when the shadowing problem is actually present.

This change lives in the gateway and auth tooling area, specifically the doctor command and health-check flow. It addresses a specific configuration shadowing issue documented across issues #40066, #37558, and #38026.

View Original GitHub Description

Summary

Describe the problem and fix in 2–5 bullets:

  • Problem: legacy models.providers.openai-codex overrides can keep shadowing the built-in Codex OAuth provider path after users upgrade.
  • Why it matters: affected users can keep seeing Codex OAuth failures or fallback behavior even after the underlying runtime fixes landed.
  • What changed: openclaw doctor now warns when it finds a legacy models.providers.openai-codex transport override alongside a configured or stored Codex OAuth profile; docs and regression coverage were added.
  • What did NOT change (scope boundary): this PR does not rewrite runtime provider selection and does not auto-remove config.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor
  • 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

  • Related #40066
  • Related #37558
  • Related #38026

User-visible / Behavior Changes

openclaw doctor now warns when a legacy models.providers.openai-codex transport override is present at the same time as Codex OAuth, and points users to remove the stale override if they want the built-in Codex OAuth path back.

Security Impact (required)

  • New permissions/capabilities? (Yes/No) No
  • Secrets/tokens handling changed? (Yes/No) No
  • New/changed network calls? (Yes/No) No
  • Command/tool execution surface changed? (Yes/No) No
  • Data access scope changed? (Yes/No) No
  • If any Yes, explain risk + mitigation:

Repro + Verification

Environment

  • OS: macOS
  • Runtime/container: local checkout via pnpm / Node
  • Model/provider: Codex OAuth (openai-codex)
  • Integration/channel (if any): none
  • Relevant config (redacted): models.providers.openai-codex override plus auth.profiles["openai-codex:<email>"] = { provider: "openai-codex", mode: "oauth" }

Steps

  1. Configure a legacy models.providers.openai-codex transport override.
  2. Configure or store a Codex OAuth profile.
  3. Run openclaw doctor.

Expected

  • Doctor warns that the legacy models.providers.openai-codex transport override can shadow the built-in Codex OAuth path.

Actual

  • Before this PR, doctor emitted no targeted warning for that stale override.
  • After this PR, doctor emits the warning only when Codex OAuth is actually configured/stored.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

  • Verified scenarios: added a failing doctor e2e regression first, then confirmed it passes once the warning is wired in; verified the warning does not appear for supported custom proxy/header-only overrides or when no Codex OAuth exists.
  • Edge cases checked: configured OAuth profile, stored OAuth profile, and no-OAuth false-positive case.
  • What you did not verify: I did not perform a live Codex OAuth login against a real account; verification here is config/store + doctor-flow based.

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/No) Yes
  • Config/env changes? (Yes/No) No
  • Migration needed? (Yes/No) No
  • If yes, exact upgrade steps:

Failure Recovery (if this breaks)

  • How to disable/revert this change quickly: revert this commit or remove the new doctor warning call.
  • Files/config to restore: src/commands/doctor-auth.ts, src/commands/doctor.ts, docs/gateway/doctor.md, and the added regression cases.
  • Known bad symptoms reviewers should watch for: unexpected Codex OAuth warnings when no Codex OAuth profile exists.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

  • Risk: false-positive warning for users who intentionally keep a legacy openai-codex transport override.
    • Mitigation: the warning is gated on an actual configured or stored Codex OAuth profile, states that the override may be intentional, and does not auto-mutate config.

AI Assistance

  • AI-assisted: Yes (Codex)
  • Testing degree: Fully tested
  • Prompt/session summary: triaged current open issues for overlap and freshness, rejected stale/overlapping candidates, selected #40066 as the strongest unclaimed fix, wrote failing doctor regression tests first, implemented the smallest warning-only fix, then ran targeted tests, docs checks, pnpm build, and the full pnpm test suite.
  • Understanding confirmation: I understand this change only adds a doctor warning/docs/tests for stale Codex overrides; it does not change runtime auth resolution or provider behavior.

Verification Commands

  • pnpm exec vitest run src/commands/doctor-auth.deprecated-cli-profiles.test.ts
  • pnpm exec vitest run --config vitest.e2e.config.ts src/commands/doctor.warns-state-directory-is-missing.e2e.test.ts
  • pnpm check:docs
  • git diff --check
  • pnpm build
  • pnpm test
© 2026 · via Gitpulse