fix(model): hint at missing models.providers block in Unknown model error

mushuiyu886 · mushuiyu886 · commit ce7027b2fea9 · 2026-05-10T12:31:50.000+08:00
When a model is registered in agents.defaults.models but the provider has no models.providers[].models[] entry, the 'Unknown model' error now explains that both config blocks are required. Closes #80089
diff --git a/src/agents/pi-embedded-runner/model.test.ts b/src/agents/pi-embedded-runner/model.test.ts
@@ -2410,4 +2410,52 @@ describe("resolveModel", () => {
       baseUrl: "https://api.x.ai/v1",
     });
   });
+
+  it("hints at missing models.providers block when model is in agents.defaults.models only (#80089)", () => {
+    const cfg = {
+      agents: {
+        defaults: {
+          models: {
+            "microsoft-foundry/Kimi-K2.6-1": {
+              contextWindow: 262144,
+              maxOutputTokens: 16384,
+            },
+          },
+        },
+      },
+      models: {
+        providers: {},
+      },
+    } as never;
+
+    const result = resolveModel("microsoft-foundry", "Kimi-K2.6-1", "/tmp/agent", cfg, {
+      authStorage: { mocked: true } as never,
+      modelRegistry: discoverModels({ mocked: true } as never, "/tmp/agent"),
+      runtimeHooks: {
+        applyProviderResolvedModelCompatWithPlugins: () => undefined,
+        buildProviderUnknownModelHintWithPlugin: () => undefined,
+        prepareProviderDynamicModel: async () => {},
+        runProviderDynamicModel: () => undefined,
+        applyProviderResolvedTransportWithPlugin: () => undefined,
+        normalizeProviderResolvedModelWithPlugin: () => undefined,
+        normalizeProviderTransportWithPlugin: () => undefined,
+      },
+    });
+
+    expect(result.model).toBeUndefined();
+    expect(result.error).toContain("Unknown model: microsoft-foundry/Kimi-K2.6-1");
+    expect(result.error).toContain("agents.defaults.models");
+    expect(result.error).toContain('models.providers["microsoft-foundry"].models[]');
+  });
+
+  it("does not hint at providers block when model is not in agents.defaults.models", () => {
+    const result = resolveModel("mistral", "mistral-medium-3-5", "/tmp/agent", undefined, {
+      authStorage: { mocked: true } as never,
+      modelRegistry: discoverModels({ mocked: true } as never, "/tmp/agent"),
+      runtimeHooks: createRuntimeHooks(),
+    });
+
+    expect(result.model).toBeUndefined();
+    expect(result.error).toBe("Unknown model: mistral/mistral-medium-3-5");
+  });
 });
diff --git a/src/agents/pi-embedded-runner/model.ts b/src/agents/pi-embedded-runner/model.ts
@@ -1223,6 +1223,11 @@ function buildUnknownModelError(params: {
     return suppressed;
   }
   const base = `Unknown model: ${params.provider}/${params.modelId}`;
+  const configHints = buildUnknownModelConfigHints({
+    provider: params.provider,
+    modelId: params.modelId,
+    cfg: params.cfg,
+  });
   const runtimeHooks = params.runtimeHooks ?? DEFAULT_PROVIDER_RUNTIME_HOOKS;
   const hint = runtimeHooks.buildProviderUnknownModelHintWithPlugin({
     provider: params.provider,
@@ -1238,5 +1243,31 @@ function buildUnknownModelError(params: {
       modelId: params.modelId,
     },
   });
-  return hint ? `${base}. ${hint}` : base;
+  const parts = [base, ...configHints];
+  if (hint) {
+    parts.push(hint);
+  }
+  return parts.join(". ");
+}
+
+function buildUnknownModelConfigHints(params: {
+  provider: string;
+  modelId: string;
+  cfg?: OpenClawConfig;
+}): string[] {
+  const hints: string[] = [];
+  const key = `${params.provider}/${params.modelId}`;
+  const defaultsModels = params.cfg?.agents?.defaults?.models;
+  const inDefaultsModels = defaultsModels && key in defaultsModels;
+  const providerConfig = params.cfg?.models?.providers?.[params.provider];
+  const providerModels =
+    providerConfig && typeof providerConfig === "object" ? providerConfig.models : undefined;
+  const hasProviderModels = Array.isArray(providerModels) && providerModels.length > 0;
+  if (inDefaultsModels && !hasProviderModels) {
+    hints.push(
+      `Found in agents.defaults.models but not in models.providers["${params.provider}"].models[]. ` +
+        "Both blocks are required to register a model with a provider plugin",
+    );
+  }
+  return hints;
 }
