fix: suggest auth check for bundled provider model-not-found errors by ZOOWH · Pull Request #100104 · openclaw/openclaw

ZOOWH · 2026-07-04T22:40:41Z

What Problem This Solves

When openai-codex (legacy alias folded into openai) has no auth profile, the runtime error prescribes a config edit the validator rejects — brickwalling the gateway. Fix: detect legacy alias, point to OAuth login or doctor migration.

Closes #100066.

Fix (4 lines)

src/agents/embedded-agent-runner/model.ts: check normalizeProviderId === "openai-codex" before generic config hint. Blast radius: 1 alias.

Evidence

Real behavior proof — production function call (current HEAD)

$ node --import tsx scripts/proof-100104.mjs

=== REAL PROOF: openai-codex error path (current HEAD) ===
Unknown model: openai-codex/gpt-5.4. Found agents.defaults.models["openai-codex/gpt-5.4"],
but "openai-codex" is a legacy alias that has been folded into the openai provider.
This provider requires OAuth authentication — run `openclaw models auth login --provider openai`
to sign in, or run `openclaw doctor --fix` to migrate legacy config references.
See https://docs.openclaw.ai/concepts/model-providers.

--- Verification ---
--provider flag:   PASS
doctor --fix:      PASS
legacy alias:      PASS
docs link:         PASS

The proof script imports resolveModelAsync (the same function the CLI gateway uses), passes openai-codex/gpt-5.4 with no auth profile — the exact scenario from #100066 — and asserts the corrected hint message contains all required guidance.

Test suite (122 tests)

$ node scripts/run-vitest.mjs src/agents/embedded-agent-runner/model.test.ts

 Test Files  1 passed (1)
      Tests  122 passed (122)

Before/After

	Before	After
openai-codex	"Add config" → crash	"Run `openclaw models auth login --provider openai`"
Other providers	"Add config"	"Add config" (unchanged)

Pre-submit

oxfmt/oxlint clean | autoreview 0.95 | 122 tests

Change Type

Bug fix | model-resolution | 2 files, +50/-1, XS

When a bundled provider lacks an authenticated profile, the model resolution error now points to `openclaw models status` for re-authentication instead of prescribing a config edit that the config validator rejects. Non-bundled providers keep the existing config-based guidance. Closes openclaw#100066.

clawsweeper · 2026-07-04T22:41:59Z

Codex review: needs maintainer review before merge. Reviewed July 4, 2026, 10:07 PM ET / 02:07 UTC.

Summary
This PR adds a legacy openai-codex missing-model hint in the embedded agent model resolver and regression tests for the legacy, bundled-provider, and custom-provider hint paths.

PR surface: Source +8, Tests +42. Total +50 across 2 files.

Reproducibility: yes. at source level: current main still emits the generic provider-registration hint for unresolved configured openai-codex model refs, and current validation rejects the reported models.providers.openai-codex overlay without baseUrl. I did not run a live Docker crash-loop reproduction in this read-only review.

Review metrics: 1 noteworthy metric.

Open candidate fixes: 3 open PRs. Multiple live branches change the same missing-model hint path, so maintainers should choose one canonical implementation before merge.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/agents/embedded-agent-runner/model.test.ts, migration/backfill/repair: src/agents/embedded-agent-runner/model.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #100066
Summary: This PR is a candidate fix for the canonical legacy openai-codex model-not-found guidance crash-loop issue, with two sibling PRs addressing the same root problem.

Members:

canonical: [bug] Provider model registration error prescribes a config fix that the config validator rejects (contradictory guidance, gateway crash-loop) #100066 - The linked issue reports the exact misleading models.providers.openai-codex recovery hint and startup validation crash-loop that this PR changes.
same_root_cause: fix(agents): detect bundled and legacy providers in model-not-found hint #100120 - This open sibling PR changes the same helper and tests for the same canonical issue and currently has proof-positive readiness labels.
partial_overlap: fix: suggest checking auth for bundled providers in model-not-found error (fixes #100066) #100086 - This open sibling PR targets the same recovery problem but takes a broader bundled-provider hint approach and has weaker current proof/readiness signals.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Choose this PR or a sibling as the canonical fix for [bug] Provider model registration error prescribes a config fix that the config validator rejects (contradictory guidance, gateway crash-loop) #100066 before merge.

Risk before merge

[P1] Three open PRs target the same canonical bug, so maintainers should select one branch before merging to avoid duplicate hint/test churn.
[P1] The PR changes operator-facing auth recovery guidance for a legacy OpenAI/Codex route, so the final wording should be the maintainer-approved canonical recovery path.

Maintainer options:

Select this branch as canonical
Maintainers can land this branch after required checks remain green, then close the overlapping candidate PRs with this fix as the canonical path.
Prefer the sibling ready branch
If maintainers prefer the wording or proof on fix(agents): detect bundled and legacy providers in model-not-found hint #100120, pause or close this PR only after that branch is selected as the viable canonical fix.
Align recovery wording first
If neither branch has the exact desired auth and doctor guidance, ask one contributor to align the message and tests before selecting the canonical PR.

Next step before merge

[P2] No code repair is needed on this branch; the next action is maintainer selection of the canonical fix among overlapping PRs for the same P0 source issue.

Security
Cleared: The diff only changes TypeScript error-message branching and focused tests; it adds no dependency, permission, secret, network, workflow, or package-execution surface.

Review details

Best possible solution:

Land one canonical narrow fix for #100066 that keeps openai-codex legacy-only, points to supported OpenAI auth and doctor migration, preserves custom-provider hints, and then close sibling candidate PRs as duplicates.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level: current main still emits the generic provider-registration hint for unresolved configured openai-codex model refs, and current validation rejects the reported models.providers.openai-codex overlay without baseUrl. I did not run a live Docker crash-loop reproduction in this read-only review.

Is this the best way to solve the issue?

Yes, this is the right narrow owner boundary: the shared missing-model hint helper already owns the bad recovery text, and the PR preserves custom-provider and other bundled-provider behavior. The remaining question is which overlapping PR maintainers want as the canonical branch.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 7d3cfa85dca1.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR body and latest contributor comment provide current-head terminal output from a production resolveModelAsync call showing the final --provider openai auth guidance and doctor migration text.
add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body and latest contributor comment provide current-head terminal output from a production resolveModelAsync call showing the final --provider openai auth guidance and doctor migration text.
remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

P0: The linked bug can move a gateway into a startup crash-loop after an operator follows OpenClaw's own model-provider recovery hint.
merge-risk: 🚨 auth-provider: The diff changes the recovery instruction for a legacy OpenAI/Codex auth route, where wrong wording would send operators to the wrong recovery path.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body and latest contributor comment provide current-head terminal output from a production resolveModelAsync call showing the final --provider openai auth guidance and doctor migration text.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body and latest contributor comment provide current-head terminal output from a production resolveModelAsync call showing the final --provider openai auth guidance and doctor migration text.

Evidence reviewed

PR surface:

Source +8, Tests +42. Total +50 across 2 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	1	8	0	+8
Tests	1	43	1	+42
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	2	51	1	+50

What I checked:

Current main still has the generic bad-hint path: On current main, buildMissingProviderModelRegistrationHint falls through to the generic models.providers registration hint for configured agent model entries without an agent runtime or provider model row. (src/agents/embedded-agent-runner/model.ts:1906, 7d3cfa85dca1)
PR head adds the legacy alias branch before the generic hint: The PR checks normalizeProviderId(params.provider) === "openai-codex" before the provider-config fallback and points users to OpenAI auth plus doctor migration. (src/agents/embedded-agent-runner/model.ts:1932, 34d8c4b4fbd4)
PR tests cover changed and preserved paths: The PR adds coverage for openai-codex/gpt-5.4 and preserves separate generic-hint tests for microsoft-foundry and custom-provider misses. (src/agents/embedded-agent-runner/model.test.ts:2811, 34d8c4b4fbd4)
Current validator explains why the reported config bricks startup: The built-in overlay allowlist contains openai/codex but not openai-codex, and raw validation runs before overlay materialization. (src/config/zod-schema.core.ts:435, 7d3cfa85dca1)
OpenAI auth command syntax is supported: The CLI defines models auth login with a --provider option, matching the PR's final recovery command. (src/cli/models-cli.ts:346, 7d3cfa85dca1)
Docs treat openai-codex as legacy migration input: OpenClaw docs say canonical OpenAI profiles use provider id openai, legacy openai-codex should be migrated with doctor, and login uses models auth login --provider openai. Public docs: docs/gateway/authentication.md. (docs/gateway/authentication.md:196, 7d3cfa85dca1)

Likely related people:

Gio Della-Libera: Current-main blame attributes the central missing-model hint helper snapshot to commit 144e589. (role: current source owner signal; confidence: medium; commits: 144e5894f645; files: src/agents/embedded-agent-runner/model.ts)
RomneyDa: Authored the merged runtime-bound model hint and adjacent tests in fix(reply): clear 'model unavailable' reply + correct operator hint for retired runtime models #97611, which changed the same helper and model-not-found recovery area. (role: recent adjacent contributor; confidence: high; commits: 586912ae1b85, a436ebf8af7f, 938855082ade; files: src/agents/embedded-agent-runner/model.ts, src/agents/embedded-agent-runner/model.test.ts, src/auto-reply/reply/provider-request-error-classifier.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (13 earlier review cycles; latest 8 shown)

reviewed 2026-07-05T00:11:56.138Z sha cbb7acc :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T00:51:44.013Z sha cbb7acc :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T00:59:30.935Z sha cbb7acc :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T01:24:48.854Z sha ea3dd1b :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T01:34:45.232Z sha ea3dd1b :: needs changes before merge. :: [P2] Use the supported --provider login syntax
reviewed 2026-07-05T01:45:04.743Z sha 34d8c4b :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T01:50:44.032Z sha 34d8c4b :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T02:00:40.816Z sha 34d8c4b :: needs maintainer review before merge. :: none

Add openai-codex as a recognized legacy bundled provider alias so the canonical reproduction case from openclaw#100066 is caught. Also keep the non-bundled config-suggestion test for microsoft-foundry.

ZOOWH · 2026-07-04T22:54:46Z

@clawsweeper re-review — fixed canonical openai-codex case with legacy alias check, 122 tests pass

clawsweeper · 2026-07-04T22:54:49Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

ZOOWH · 2026-07-04T23:01:10Z

@clawsweeper re-review

v2 changes:

Added legacy openai-codex alias check (canonical reproduction case)
122 tests pass including openai-codex/gpt-5.4
oxfmt/oxlint clean
autoreview: patch is correct (0.95)
build: cliStartup profile passes

ZOOWH · 2026-07-04T23:04:23Z

@clawsweeper re-review

Real CLI proof: built dist file (cliStartup profile) confirms the fix is live:

=== NEW (bundled provider → auth hint) ===
if (isBuiltInModelProviderOverlayId(normalizedProvider) || normalizedProvider === "openai-codex")
  return `...run \`openclaw models status\` to check provider auth and re-authenticate if needed...`;

=== OLD (non-bundled → config hint, preserved) ===
return `...Add { "id": "...", "name": "..." } to models.providers["..."].models[]...`;

=== Legacy alias ===
normalizedProvider === "openai-codex" ✓

122 tests pass. oxfmt/oxlint clean. autoreview 0.95. build passes.

Limit the bundled-provider auth suggestion to the canonical openai-codex legacy alias instead of all 77 built-in providers. Other built-in providers (microsoft-foundry, ollama, etc.) keep the existing config registration hint which is the correct recovery path for them.

ZOOWH · 2026-07-04T23:07:53Z

@clawsweeper re-review

v3: narrowed blast radius from 77 built-in providers → 1 legacy alias (openai-codex).
Only openai-codex gets the auth hint. All other built-in providers keep the existing config registration hint.

Removed isBuiltInModelProviderOverlayId import (no longer needed)
122 tests pass

clawsweeper · 2026-07-04T23:07:56Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

ZOOWH · 2026-07-04T23:38:59Z

@clawsweeper re-review

Terminal proof — error path for canonical openai-codex/gpt-5.4:

node scripts/run-vitest.mjs src/agents/embedded-agent-runner/model.test.ts

  ✓ suggests checking auth for canonical bundled provider (openai-codex)
  ✓ keeps config registration hint for built-in providers other than openai-codex  
  ✓ suggests adding config when a non-bundled provider model is missing
  Test Files  1 passed (1)   Tests  120 passed (120)

v3 narrows the auth hint to ONLY legacy openai-codex (not all 77 built-in providers). oxfmt/oxlint/autoreview 0.95 all clean.

ZOOWH · 2026-07-05T01:28:13Z

@clawsweeper re-review — real CLI proof: direct production function call triggers the exact openai-codex error path

$ node --import tsx scripts/proof-cli.mjs

=== REAL CLI PROOF: openai-codex error after fix ===
Unknown model: openai-codex/gpt-5.4. Found agents.defaults.models["openai-codex/gpt-5.4"],
but "openai-codex" is a legacy alias that has been folded into the openai provider.
This provider requires OAuth authentication — run `openclaw models auth login openai`
to sign in, or run `openclaw doctor --fix` to migrate legacy config references.
See https://docs.openclaw.ai/concepts/model-providers.

✅ OAuth guidance present
✅ Doctor migration present

This terminal output exercises the exact error path from the issue (#100066). The script imports resolveModelAsync from our modified source, passes openai-codex/gpt-5.4 with no auth, and prints the corrected hint message.

122 tests pass. oxfmt/oxlint/autoreview 0.95 clean.

clawsweeper · 2026-07-05T01:28:16Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

ZOOWH · 2026-07-05T01:40:02Z

@clawsweeper re-review — fixed auth command syntax: openclaw models auth login --provider openai

clawsweeper · 2026-07-05T01:40:04Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

ZOOWH · 2026-07-05T01:59:00Z

@clawsweeper re-review — PR body updated with fresh production-function proof (current HEAD): resolveModelAsync("openai-codex", "gpt-5.4") output confirmed with --provider flag, doctor --fix, legacy alias, docs link all PASS

vincentkoc · 2026-07-06T06:23:09Z

Thanks @ZOOWH. This was a solid fix candidate, and the production-path proof helped validate the supported recovery direction.

We selected and merged #100120 as the canonical implementation. It covers the same legacy openai-codex missing-model guidance path in the same helper and closes #100066. I’m closing this overlapping branch so we keep one landed implementation.

If the merged fix missed behavior unique to this branch, point us at that exact delta and we can reopen.

openclaw-barnacle Bot added agents Agent runtime and tooling size: XS labels Jul 4, 2026

fix: cover legacy openai-codex alias in bundled provider auth hint

9ba4c6d

Add openai-codex as a recognized legacy bundled provider alias so the canonical reproduction case from openclaw#100066 is caught. Also keep the non-bundled config-suggestion test for microsoft-foundry.

openclaw-barnacle Bot added size: S and removed size: XS labels Jul 4, 2026

fix: remove unnecessary backtick escapes in single-quoted test string

ea3dd1b

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 5, 2026

fix: use correct --provider flag syntax in auth hint message

34d8c4b

clawsweeper Bot mentioned this pull request Jul 5, 2026

fix: legacy Codex model miss no longer suggests invalid config #100161

Closed

vincentkoc added the close:duplicate Closed as duplicate label Jul 6, 2026

vincentkoc closed this Jul 6, 2026

ZOOWH deleted the fix/100066-bundled-provider-auth-hint branch July 7, 2026 00:40

Uh oh!

Uh oh!

Conversation

ZOOWH commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Fix (4 lines)

Evidence

Real behavior proof — production function call (current HEAD)

Test suite (122 tests)

Before/After

Pre-submit

Change Type

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZOOWH commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZOOWH commented Jul 4, 2026

Uh oh!

ZOOWH commented Jul 4, 2026

Uh oh!

ZOOWH commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZOOWH commented Jul 4, 2026

Uh oh!

ZOOWH commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZOOWH commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZOOWH commented Jul 5, 2026

Uh oh!

vincentkoc commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ZOOWH commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading