fix(agents): cover legacy Codex provider config hint

vincentkoc · vincentkoc · commit 91c94e97badc · 2026-07-05T22:51:51.000-07:00
diff --git a/src/agents/embedded-agent-runner/model.test.ts b/src/agents/embedded-agent-runner/model.test.ts
@@ -2832,24 +2832,45 @@ describe("resolveModel", () => {
     );
   });
 
-  it("suggests running doctor for legacy openai-codex provider", async () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          models: {
-            "openai-codex/gpt-5.4": {},
+  it.each([
+    {
+      name: "agent model entry",
+      cfg: {
+        agents: {
+          defaults: {
+            models: {
+              "openai-codex/gpt-5.4": {},
+            },
           },
         },
       },
-    } as unknown as OpenClawConfig;
-
-    const result = await resolveModelAsync("openai-codex", "gpt-5.4", "/tmp/agent", cfg, {
-      runtimeHooks: createRuntimeHooks(),
-      skipAgentDiscovery: true,
-    });
+    },
+    {
+      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. Found agents.defaults.models["openai-codex/gpt-5.4"], but "openai-codex" is a legacy provider ID. Run `openclaw doctor --fix` to migrate to the current OpenAI provider 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.',
+      '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.',
     );
   });
 
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;
@@ -1929,15 +1935,6 @@ function buildMissingProviderModelRegistrationHint(params: {
   if (agentRuntimeId) {
     return `Found agents.defaults.models["${agentModelKey}"] bound to the "${agentRuntimeId}" agent runtime. Models served by an agent runtime come from that runtime and its linked account, not from models.providers["${params.provider}"].models[] — registering it there will not make it usable. Confirm "${params.modelId}" is still offered by the "${agentRuntimeId}" runtime and switch agents.defaults.model.primary to a currently available model (run \`openclaw models list --provider ${params.provider}\` to list them). See https://docs.openclaw.ai/concepts/model-providers.`;
   }
-  // Legacy openai-codex is folded into the "openai" provider. Its models
-  // register through the OpenAI provider at startup, so a missing-model
-  // error here is almost always a legacy config reference or a missing
-  // auth profile. The correct fix is to migrate the config via doctor
-  // or re-authenticate the provider, not to add a models.providers[]
-  // overlay (which the validator rejects without baseUrl).
-  if (normalizeProviderId(params.provider) === "openai-codex") {
-    return `Found agents.defaults.models["${agentModelKey}"], but "openai-codex" is a legacy provider ID. Run \`openclaw doctor --fix\` to migrate to the current OpenAI provider 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 providerConfig = findNormalizedProviderValue(
     params.cfg?.models?.providers,
     params.provider,
