fix(agents): detect bundled and legacy providers in model-not-found hint (#100120)

SunnyShu0925 · claude · vincentkoc · web-flow · commit d6dad9d9d595 · 2026-07-06T06:21:49.000Z
* [AI] fix(agents): detect legacy openai-codex provider in model-not-found hint In buildMissingProviderModelRegistrationHint, add an early-return check for the legacy openai-codex alias (via normalizeProviderId). Instead of suggesting a models.providers[] config entry that the config validator rejects without baseUrl, the hint now points operators to run openclaw doctor --fix for migration or check provider auth. Fixes #100066 Co-Authored-By: Claude <noreply@anthropic.com> * fix(agents): cover legacy Codex provider config hint --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Vincent Koc <25068+vincentkoc@users.noreply.github.com>
diff --git a/src/agents/embedded-agent-runner/model.test.ts b/src/agents/embedded-agent-runner/model.test.ts
@@ -2832,6 +2832,69 @@ describe("resolveModel", () => {
     );
   });
 
+  it.each([
+    {
+      name: "agent model entry",
+      cfg: {
+        agents: {
+          defaults: {
+            models: {
+              "openai-codex/gpt-5.4": {},
+            },
+          },
+        },
+      },
+    },
+    {
+      name: "legacy provider config",
+      cfg: {
+        models: {
+          providers: {
+            "openai-codex": {
+              models: [{ id: "gpt-5.3-codex", name: "GPT-5.3 Codex" }],
+            },
+          },
+        },
+      },
+    },
+  ])("suggests running doctor for openai-codex from $name", async ({ cfg }) => {
+    const result = await resolveModelAsync(
+      "openai-codex",
+      "gpt-5.4",
+      "/tmp/agent",
+      cfg as unknown as OpenClawConfig,
+      {
+        runtimeHooks: createRuntimeHooks(),
+        skipAgentDiscovery: true,
+      },
+    );
+
+    expect(result.error).toBe(
+      'Unknown model: openai-codex/gpt-5.4. "openai-codex" is a legacy provider ID. Run `openclaw doctor --fix` to migrate legacy model and provider config to the current OpenAI format. If the provider has no authenticated profile, run `openclaw models status` to check provider auth and re-authenticate if needed. See https://docs.openclaw.ai/concepts/model-providers.',
+    );
+  });
+
+  it("suggests adding config entry when a non-bundled provider model is missing", async () => {
+    const cfg = {
+      agents: {
+        defaults: {
+          models: {
+            "custom-provider/some-model": {},
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const result = await resolveModelAsync("custom-provider", "some-model", "/tmp/agent", cfg, {
+      runtimeHooks: createRuntimeHooks(),
+      skipAgentDiscovery: true,
+    });
+
+    expect(result.error).toBe(
+      'Unknown model: custom-provider/some-model. Found agents.defaults.models["custom-provider/some-model"], but no matching models.providers["custom-provider"].models[] entry. Add { "id": "some-model", "name": "some-model" } to models.providers["custom-provider"].models[] to register this provider model. For custom or proxy providers, also set api and baseUrl so requests route to the intended endpoint. See https://docs.openclaw.ai/concepts/model-providers.',
+    );
+  });
+
   it("points runtime-bound model entries at the runtime catalog instead of provider registration", async () => {
     const cfg = {
       agents: {
diff --git a/src/agents/embedded-agent-runner/model.ts b/src/agents/embedded-agent-runner/model.ts
@@ -1908,6 +1908,12 @@ function buildMissingProviderModelRegistrationHint(params: {
   modelId: string;
   cfg?: OpenClawConfig;
 }): string | undefined {
+  // Legacy openai-codex refs can come from model selections, provider config,
+  // or persisted routes. All of them should be repaired by doctor rather than
+  // turned into a new models.providers[] registration.
+  if (normalizeProviderId(params.provider) === "openai-codex") {
+    return `"openai-codex" is a legacy provider ID. Run \`openclaw doctor --fix\` to migrate legacy model and provider config to the current OpenAI format. If the provider has no authenticated profile, run \`openclaw models status\` to check provider auth and re-authenticate if needed. See https://docs.openclaw.ai/concepts/model-providers.`;
+  }
   const configuredModels = params.cfg?.agents?.defaults?.models;
   if (!configuredModels) {
     return undefined;
