fix(agents): fall back to agents.defaults.model when agent has no model config (#24210)

Merged via /review-pr -> /prepare-pr -> /merge-pr. Prepared head SHA: 0f272b1027 Co-authored-by: bianbiandashen <16240681+bianbiandashen@users.noreply.github.com> Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com> Reviewed-by: @gumadeiras
2026-05-09 01:28:27 +00:00 · 2026-02-23 16:18:55 +08:00
parent db32677f1d
commit a4c373935f
39 changed files with 434 additions and 251 deletions
--- a/src/commands/agent.ts
+++ b/src/commands/agent.ts
@@ -2,7 +2,6 @@ import {
  listAgentIds,
  resolveAgentDir,
  resolveEffectiveModelFallbacks,
-  resolveAgentModelPrimary,
  resolveSessionAgentId,
  resolveAgentSkillsFilter,
  resolveAgentWorkspaceDir,
@@ -21,6 +20,7 @@ import {
  modelKey,
  normalizeModelRef,
  resolveConfiguredModelRef,
+  resolveDefaultModelForAgent,
  resolveThinkingDefault,
 } from "../agents/model-selection.js";
 import { runEmbeddedPiAgent } from "../agents/pi-embedded.js";
@@ -372,29 +372,9 @@ export async function agentCommand(
      sessionEntry = next;
    }

-    const agentModelPrimary = resolveAgentModelPrimary(cfg, sessionAgentId);
-    const cfgForModelSelection = agentModelPrimary
-      ? {
-          ...cfg,
-          agents: {
-            ...cfg.agents,
-            defaults: {
-              ...cfg.agents?.defaults,
-              model: {
-                ...(typeof cfg.agents?.defaults?.model === "object"
-                  ? cfg.agents.defaults.model
-                  : undefined),
-                primary: agentModelPrimary,
-              },
-            },
-          },
-        }
-      : cfg;
-
-    const configuredDefaultRef = resolveConfiguredModelRef({
-      cfg: cfgForModelSelection,
-      defaultProvider: DEFAULT_PROVIDER,
-      defaultModel: DEFAULT_MODEL,
+    const configuredDefaultRef = resolveDefaultModelForAgent({
+      cfg,
+      agentId: sessionAgentId,
    });
    const { provider: defaultProvider, model: defaultModel } = normalizeModelRef(
      configuredDefaultRef.provider,
--- a/src/commands/auth-choice.apply.github-copilot.ts
+++ b/src/commands/auth-choice.apply.github-copilot.ts
@@ -1,3 +1,4 @@
+import { toAgentModelListLike } from "../config/model-input.js";
 import { githubCopilotLoginCommand } from "../providers/github-copilot-auth.js";
 import type { ApplyAuthChoiceParams, ApplyAuthChoiceResult } from "./auth-choice.apply.js";
 import { applyAuthProfileConfig } from "./onboard-auth.js";
@@ -49,9 +50,7 @@ export async function applyAuthChoiceGitHubCopilot(
        defaults: {
          ...nextConfig.agents?.defaults,
          model: {
-            ...(typeof nextConfig.agents?.defaults?.model === "object"
-              ? nextConfig.agents.defaults.model
-              : undefined),
+            ...toAgentModelListLike(nextConfig.agents?.defaults?.model),
            primary: model,
          },
        },
--- a/src/commands/auth-choice.apply.huggingface.test.ts
+++ b/src/commands/auth-choice.apply.huggingface.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveAgentModelPrimaryValue } from "../config/model-input.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { applyAuthChoiceHuggingface } from "./auth-choice.apply.huggingface.js";
 import {
@@ -87,7 +88,9 @@ describe("applyAuthChoiceHuggingface", () => {
      provider: "huggingface",
      mode: "api_key",
    });
-    expect(result?.config.agents?.defaults?.model?.primary).toMatch(/^huggingface\/.+/);
+    expect(resolveAgentModelPrimaryValue(result?.config.agents?.defaults?.model)).toMatch(
+      /^huggingface\/.+/,
+    );
    expect(text).toHaveBeenCalledWith(
      expect.objectContaining({ message: expect.stringContaining("Hugging Face") }),
    );
@@ -173,7 +176,9 @@ describe("applyAuthChoiceHuggingface", () => {
    });

    expect(result).not.toBeNull();
-    expect(String(result?.config.agents?.defaults?.model?.primary)).toContain(":cheapest");
+    expect(String(resolveAgentModelPrimaryValue(result?.config.agents?.defaults?.model))).toContain(
+      ":cheapest",
+    );
    expect(note).toHaveBeenCalledWith(
      "Provider locked — router will choose backend by cost or speed.",
      "Hugging Face",
--- a/src/commands/auth-choice.apply.minimax.test.ts
+++ b/src/commands/auth-choice.apply.minimax.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveAgentModelPrimaryValue } from "../config/model-input.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { applyAuthChoiceMiniMax } from "./auth-choice.apply.minimax.js";
 import {
@@ -114,7 +115,9 @@ describe("applyAuthChoiceMiniMax", () => {
        provider,
        mode: "api_key",
      });
-      expect(result?.config.agents?.defaults?.model?.primary).toBe(expectedModel);
+      expect(resolveAgentModelPrimaryValue(result?.config.agents?.defaults?.model)).toBe(
+        expectedModel,
+      );
      expect(text).not.toHaveBeenCalled();
      expect(confirm).not.toHaveBeenCalled();

@@ -144,7 +147,9 @@ describe("applyAuthChoiceMiniMax", () => {
      provider: "minimax-cn",
      mode: "api_key",
    });
-    expect(result?.config.agents?.defaults?.model?.primary).toBe("minimax-cn/MiniMax-M2.5");
+    expect(resolveAgentModelPrimaryValue(result?.config.agents?.defaults?.model)).toBe(
+      "minimax-cn/MiniMax-M2.5",
+    );
    expect(text).not.toHaveBeenCalled();
    expect(confirm).toHaveBeenCalled();

@@ -176,7 +181,9 @@ describe("applyAuthChoiceMiniMax", () => {
      provider: "minimax",
      mode: "api_key",
    });
-    expect(result?.config.agents?.defaults?.model?.primary).toBe("minimax/MiniMax-M2.5-Lightning");
+    expect(resolveAgentModelPrimaryValue(result?.config.agents?.defaults?.model)).toBe(
+      "minimax/MiniMax-M2.5-Lightning",
+    );
    expect(text).not.toHaveBeenCalled();
    expect(confirm).not.toHaveBeenCalled();

--- a/src/commands/auth-choice.model-check.ts
+++ b/src/commands/auth-choice.model-check.ts
@@ -1,9 +1,7 @@
-import { resolveAgentModelPrimary } from "../agents/agent-scope.js";
 import { ensureAuthProfileStore, listProfilesForProvider } from "../agents/auth-profiles.js";
-import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js";
 import { getCustomProviderApiKey, resolveEnvApiKey } from "../agents/model-auth.js";
 import { loadModelCatalog } from "../agents/model-catalog.js";
-import { resolveConfiguredModelRef } from "../agents/model-selection.js";
+import { resolveDefaultModelForAgent } from "../agents/model-selection.js";
 import type { OpenClawConfig } from "../config/config.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { OPENAI_CODEX_DEFAULT_MODEL } from "./openai-codex-model-default.js";
@@ -13,35 +11,13 @@ export async function warnIfModelConfigLooksOff(
  prompter: WizardPrompter,
  options?: { agentId?: string; agentDir?: string },
 ) {
-  const agentModelOverride = options?.agentId
-    ? resolveAgentModelPrimary(config, options.agentId)
-    : undefined;
-  const configWithModel =
-    agentModelOverride && agentModelOverride.length > 0
-      ? {
-          ...config,
-          agents: {
-            ...config.agents,
-            defaults: {
-              ...config.agents?.defaults,
-              model: {
-                ...(typeof config.agents?.defaults?.model === "object"
-                  ? config.agents.defaults.model
-                  : undefined),
-                primary: agentModelOverride,
-              },
-            },
-          },
-        }
-      : config;
-  const ref = resolveConfiguredModelRef({
-    cfg: configWithModel,
-    defaultProvider: DEFAULT_PROVIDER,
-    defaultModel: DEFAULT_MODEL,
+  const ref = resolveDefaultModelForAgent({
+    cfg: config,
+    agentId: options?.agentId,
  });
  const warnings: string[] = [];
  const catalog = await loadModelCatalog({
-    config: configWithModel,
+    config,
    useCache: false,
  });
  if (catalog.length > 0) {
--- a/src/commands/auth-choice.moonshot.test.ts
+++ b/src/commands/auth-choice.moonshot.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveAgentModelPrimaryValue } from "../config/model-input.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { applyAuthChoice } from "./auth-choice.js";
 import {
@@ -72,7 +73,9 @@ describe("applyAuthChoice (moonshot)", () => {
    expect(text).toHaveBeenCalledWith(
      expect.objectContaining({ message: "Enter Moonshot API key (.cn)" }),
    );
-    expect(result.config.agents?.defaults?.model?.primary).toBe("anthropic/claude-opus-4-5");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "anthropic/claude-opus-4-5",
+    );
    expect(result.config.models?.providers?.moonshot?.baseUrl).toBe("https://api.moonshot.cn/v1");
    expect(result.agentModelOverride).toBe("moonshot/kimi-k2.5");

@@ -88,7 +91,9 @@ describe("applyAuthChoice (moonshot)", () => {
      setDefaultModel: true,
    });

-    expect(result.config.agents?.defaults?.model?.primary).toBe("moonshot/kimi-k2.5");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "moonshot/kimi-k2.5",
+    );
    expect(result.config.models?.providers?.moonshot?.baseUrl).toBe("https://api.moonshot.cn/v1");
    expect(result.agentModelOverride).toBeUndefined();

--- a/src/commands/auth-choice.test.ts
+++ b/src/commands/auth-choice.test.ts
@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import type { OAuthCredentials } from "@mariozechner/pi-ai";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveAgentModelPrimaryValue } from "../config/model-input.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { applyAuthChoice, resolvePreferredProviderForAuthChoice } from "./auth-choice.js";
 import { GOOGLE_GEMINI_DEFAULT_MODEL } from "./google-gemini-model-default.js";
@@ -278,7 +279,9 @@ describe("applyAuthChoice", () => {
      provider: "huggingface",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toMatch(/^huggingface\/.+/);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toMatch(
+      /^huggingface\/.+/,
+    );

    expect((await readAuthProfile("huggingface:default"))?.key).toBe("hf-test-token");
  });
@@ -310,7 +313,7 @@ describe("applyAuthChoice", () => {
      expect.objectContaining({ message: "Select Z.AI endpoint", initialValue: "global" }),
    );
    expect(result.config.models?.providers?.zai?.baseUrl).toBe(ZAI_CODING_CN_BASE_URL);
-    expect(result.config.agents?.defaults?.model?.primary).toBe("zai/glm-5");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe("zai/glm-5");

    expect((await readAuthProfile("zai:default"))?.key).toBe("zai-test-key");
  });
@@ -368,7 +371,9 @@ describe("applyAuthChoice", () => {
      expect.objectContaining({ message: "Select Z.AI endpoint" }),
    );
    expect(result.config.models?.providers?.zai?.baseUrl).toBe(ZAI_CODING_GLOBAL_BASE_URL);
-    expect(result.config.agents?.defaults?.model?.primary).toBe("zai/glm-4.5");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "zai/glm-4.5",
+    );
  });

  it("maps apiKey + tokenProvider=huggingface to huggingface-api-key flow", async () => {
@@ -396,7 +401,9 @@ describe("applyAuthChoice", () => {
      provider: "huggingface",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toMatch(/^huggingface\/.+/);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toMatch(
+      /^huggingface\/.+/,
+    );
    expect(text).not.toHaveBeenCalled();

    expect((await readAuthProfile("huggingface:default"))?.key).toBe("hf-token-provider-test");
@@ -425,7 +432,9 @@ describe("applyAuthChoice", () => {
      provider: "together",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toMatch(/^together\/.+/);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toMatch(
+      /^together\/.+/,
+    );
    expect(text).not.toHaveBeenCalled();
    expect(confirm).not.toHaveBeenCalled();
    expect((await readAuthProfile("together:default"))?.key).toBe(
@@ -456,7 +465,9 @@ describe("applyAuthChoice", () => {
      provider: "kimi-coding",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toMatch(/^kimi-coding\/.+/);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toMatch(
+      /^kimi-coding\/.+/,
+    );
    expect(text).not.toHaveBeenCalled();
    expect(confirm).not.toHaveBeenCalled();
    expect((await readAuthProfile("kimi-coding:default"))?.key).toBe("sk-kimi-token-provider-test");
@@ -485,7 +496,9 @@ describe("applyAuthChoice", () => {
      provider: "google",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe(GOOGLE_GEMINI_DEFAULT_MODEL);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      GOOGLE_GEMINI_DEFAULT_MODEL,
+    );
    expect(text).not.toHaveBeenCalled();
    expect(confirm).not.toHaveBeenCalled();
    expect((await readAuthProfile("google:default"))?.key).toBe("sk-gemini-token-provider-test");
@@ -514,7 +527,9 @@ describe("applyAuthChoice", () => {
      provider: "litellm",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toMatch(/^litellm\/.+/);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toMatch(
+      /^litellm\/.+/,
+    );
    expect(text).not.toHaveBeenCalled();
    expect(confirm).not.toHaveBeenCalled();
    expect((await readAuthProfile("litellm:default"))?.key).toBe("sk-litellm-token-provider-test");
@@ -612,7 +627,11 @@ describe("applyAuthChoice", () => {
        provider,
        mode: "api_key",
      });
-      expect(result.config.agents?.defaults?.model?.primary?.startsWith(modelPrefix)).toBe(true);
+      expect(
+        resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)?.startsWith(
+          modelPrefix,
+        ),
+      ).toBe(true);
      expect((await readAuthProfile(profileId))?.key).toBe(token);
    },
  );
@@ -642,7 +661,9 @@ describe("applyAuthChoice", () => {
      provider: "google",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe("openai/gpt-4o-mini");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "openai/gpt-4o-mini",
+    );
    expect(result.agentModelOverride).toBe(GOOGLE_GEMINI_DEFAULT_MODEL);
    expect((await readAuthProfile("google:default"))?.key).toBe("sk-gemini-test");
  });
@@ -706,7 +727,9 @@ describe("applyAuthChoice", () => {
      provider: "synthetic",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toMatch(/^synthetic\/.+/);
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toMatch(
+      /^synthetic\/.+/,
+    );

    expect((await readAuthProfile("synthetic:default"))?.key).toBe("sk-synthetic-env");
  });
@@ -731,7 +754,9 @@ describe("applyAuthChoice", () => {
      provider: "xai",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe("openai/gpt-4o-mini");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "openai/gpt-4o-mini",
+    );
    expect(result.agentModelOverride).toBe("xai/grok-4");

    expect((await readAuthProfile("xai:default"))?.key).toBe("sk-xai-test");
@@ -761,7 +786,9 @@ describe("applyAuthChoice", () => {
        setDefaultModel: true,
      });

-      expect(result.config.agents?.defaults?.model?.primary).toBe("github-copilot/gpt-4o");
+      expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+        "github-copilot/gpt-4o",
+      );
    } finally {
      if (previousIsTTYDescriptor) {
        Object.defineProperty(stdin, "isTTY", previousIsTTYDescriptor);
@@ -794,7 +821,9 @@ describe("applyAuthChoice", () => {
    expect(text).toHaveBeenCalledWith(
      expect.objectContaining({ message: "Enter OpenCode Zen API key" }),
    );
-    expect(result.config.agents?.defaults?.model?.primary).toBe("anthropic/claude-opus-4-5");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "anthropic/claude-opus-4-5",
+    );
    expect(result.config.models?.providers?.["opencode-zen"]).toBeUndefined();
    expect(result.agentModelOverride).toBe("opencode/claude-opus-4-6");
  });
@@ -868,7 +897,9 @@ describe("applyAuthChoice", () => {
      provider: "openrouter",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe("openrouter/auto");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "openrouter/auto",
+    );

    expect((await readAuthProfile("openrouter:default"))?.key).toBe("sk-openrouter-test");

@@ -963,7 +994,7 @@ describe("applyAuthChoice", () => {
      provider: "vercel-ai-gateway",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe(
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
      "vercel-ai-gateway/anthropic/claude-opus-4.6",
    );

@@ -1001,7 +1032,7 @@ describe("applyAuthChoice", () => {
      provider: "cloudflare-ai-gateway",
      mode: "api_key",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe(
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
      "cloudflare-ai-gateway/claude-sonnet-4-5",
    );

@@ -1178,7 +1209,9 @@ describe("applyAuthChoice", () => {
      provider: "qwen-portal",
      mode: "oauth",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe("qwen-portal/coder-model");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "qwen-portal/coder-model",
+    );
    expect(result.config.models?.providers?.["qwen-portal"]).toMatchObject({
      baseUrl: "https://portal.qwen.ai/v1",
      apiKey: "qwen-oauth",
@@ -1252,7 +1285,9 @@ describe("applyAuthChoice", () => {
      provider: "minimax-portal",
      mode: "oauth",
    });
-    expect(result.config.agents?.defaults?.model?.primary).toBe("minimax-portal/MiniMax-M2.1");
+    expect(resolveAgentModelPrimaryValue(result.config.agents?.defaults?.model)).toBe(
+      "minimax-portal/MiniMax-M2.1",
+    );
    expect(result.config.models?.providers?.["minimax-portal"]).toMatchObject({
      baseUrl: "https://api.minimax.io/anthropic",
      apiKey: "minimax-oauth",
--- a/src/commands/model-picker.ts
+++ b/src/commands/model-picker.ts
@@ -10,6 +10,7 @@ import {
  resolveConfiguredModelRef,
 } from "../agents/model-selection.js";
 import type { OpenClawConfig } from "../config/config.js";
+import { resolveAgentModelPrimaryValue } from "../config/model-input.js";
 import type { WizardPrompter, WizardSelectOption } from "../wizard/prompts.js";
 import { formatTokenK } from "./models/shared.js";
 import { OPENAI_CODEX_DEFAULT_MODEL } from "./openai-codex-model-default.js";
@@ -77,11 +78,7 @@ function createProviderAuthChecker(params: {
 }

 function resolveConfiguredModelRaw(cfg: OpenClawConfig): string {
-  const raw = cfg.agents?.defaults?.model as { primary?: string } | string | undefined;
-  if (typeof raw === "string") {
-    return raw.trim();
-  }
-  return raw?.primary?.trim() ?? "";
+  return resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model) ?? "";
 }

 function resolveConfiguredModelKeys(cfg: OpenClawConfig): string[] {
--- a/src/commands/models.set.test.ts
+++ b/src/commands/models.set.test.ts
@@ -82,6 +82,25 @@ describe("models set + fallbacks", () => {
    });
  });

+  it("preserves primary when adding fallbacks to string defaults.model", async () => {
+    mockConfigSnapshot({ agents: { defaults: { model: "openai/gpt-4.1-mini" } } });
+    const runtime = makeRuntime();
+
+    await modelsFallbacksAddCommand("anthropic/claude-opus-4-6", runtime);
+
+    expect(writeConfigFile).toHaveBeenCalledTimes(1);
+    const written = getWrittenConfig();
+    expect(written.agents).toEqual({
+      defaults: {
+        model: {
+          primary: "openai/gpt-4.1-mini",
+          fallbacks: ["anthropic/claude-opus-4-6"],
+        },
+        models: { "anthropic/claude-opus-4-6": {} },
+      },
+    });
+  });
+
  it("normalizes provider casing in models set", async () => {
    mockConfigSnapshot({});
    const runtime = makeRuntime();
@@ -90,4 +109,20 @@ describe("models set + fallbacks", () => {

    expectWrittenPrimaryModel("zai/glm-4.7");
  });
+
+  it("rewrites string defaults.model to object form when setting primary", async () => {
+    mockConfigSnapshot({ agents: { defaults: { model: "openai/gpt-4.1-mini" } } });
+    const runtime = makeRuntime();
+
+    await modelsSetCommand("anthropic/claude-opus-4-6", runtime);
+
+    expect(writeConfigFile).toHaveBeenCalledTimes(1);
+    const written = getWrittenConfig();
+    expect(written.agents).toEqual({
+      defaults: {
+        model: { primary: "anthropic/claude-opus-4-6" },
+        models: { "anthropic/claude-opus-4-6": {} },
+      },
+    });
+  });
 });
--- a/src/commands/models/fallbacks-shared.ts
+++ b/src/commands/models/fallbacks-shared.ts
@@ -2,12 +2,12 @@ import { buildModelAliasIndex, resolveModelRefFromString } from "../../agents/mo
 import type { OpenClawConfig } from "../../config/config.js";
 import { loadConfig } from "../../config/config.js";
 import { logConfigUpdated } from "../../config/logging.js";
+import { resolveAgentModelFallbackValues, toAgentModelListLike } from "../../config/model-input.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import {
  DEFAULT_PROVIDER,
  ensureFlagCompatibility,
  mergePrimaryFallbackConfig,
-  type PrimaryFallbackConfig,
  modelKey,
  resolveModelTarget,
  resolveModelKeysFromEntries,
@@ -17,17 +17,14 @@ import {
 type DefaultsFallbackKey = "model" | "imageModel";

 function getFallbacks(cfg: OpenClawConfig, key: DefaultsFallbackKey): string[] {
-  const entry = cfg.agents?.defaults?.[key] as unknown as PrimaryFallbackConfig | undefined;
-  return entry?.fallbacks ?? [];
+  return resolveAgentModelFallbackValues(cfg.agents?.defaults?.[key]);
 }

 function patchDefaultsFallbacks(
  cfg: OpenClawConfig,
  params: { key: DefaultsFallbackKey; fallbacks: string[]; models?: Record<string, unknown> },
 ): OpenClawConfig {
-  const existing = cfg.agents?.defaults?.[params.key] as unknown as
-    | PrimaryFallbackConfig
-    | undefined;
+  const existing = toAgentModelListLike(cfg.agents?.defaults?.[params.key]);
  return {
    ...cfg,
    agents: {
--- a/src/commands/models/list.configured.ts
+++ b/src/commands/models/list.configured.ts
@@ -5,6 +5,10 @@ import {
  resolveModelRefFromString,
 } from "../../agents/model-selection.js";
 import type { OpenClawConfig } from "../../config/config.js";
+import {
+  resolveAgentModelFallbackValues,
+  resolveAgentModelPrimaryValue,
+} from "../../config/model-input.js";
 import type { ConfiguredEntry } from "./list.types.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER, modelKey } from "./shared.js";

@@ -37,16 +41,9 @@ export function resolveConfiguredEntries(cfg: OpenClawConfig) {

  addEntry(resolvedDefault, "default");

-  const modelConfig = cfg.agents?.defaults?.model as
-    | { primary?: string; fallbacks?: string[] }
-    | undefined;
-  const imageModelConfig = cfg.agents?.defaults?.imageModel as
-    | { primary?: string; fallbacks?: string[] }
-    | undefined;
-  const modelFallbacks = typeof modelConfig === "object" ? (modelConfig?.fallbacks ?? []) : [];
-  const imageFallbacks =
-    typeof imageModelConfig === "object" ? (imageModelConfig?.fallbacks ?? []) : [];
-  const imagePrimary = imageModelConfig?.primary?.trim() ?? "";
+  const modelFallbacks = resolveAgentModelFallbackValues(cfg.agents?.defaults?.model);
+  const imageFallbacks = resolveAgentModelFallbackValues(cfg.agents?.defaults?.imageModel);
+  const imagePrimary = resolveAgentModelPrimaryValue(cfg.agents?.defaults?.imageModel) ?? "";

  modelFallbacks.forEach((raw, idx) => {
    const resolved = resolveModelRefFromString({
--- a/src/commands/models/list.status-command.ts
+++ b/src/commands/models/list.status-command.ts
@@ -2,8 +2,8 @@ import path from "node:path";
 import { resolveOpenClawAgentDir } from "../../agents/agent-paths.js";
 import {
  resolveAgentDir,
+  resolveAgentExplicitModelPrimary,
  resolveAgentModelFallbacksOverride,
-  resolveAgentModelPrimary,
 } from "../../agents/agent-scope.js";
 import {
  buildAuthHealthSummary,
@@ -26,6 +26,10 @@ import {
 import { formatCliCommand } from "../../cli/command-format.js";
 import { withProgressTotals } from "../../cli/progress.js";
 import { CONFIG_PATH, loadConfig } from "../../config/config.js";
+import {
+  resolveAgentModelFallbackValues,
+  resolveAgentModelPrimaryValue,
+} from "../../config/model-input.js";
 import {
  formatUsageWindowSummary,
  loadProviderUsageSummary,
@@ -75,7 +79,7 @@ export async function modelsStatusCommand(
  const cfg = loadConfig();
  const agentId = resolveKnownAgentId({ cfg, rawAgentId: opts.agent });
  const agentDir = agentId ? resolveAgentDir(cfg, agentId) : resolveOpenClawAgentDir();
-  const agentModelPrimary = agentId ? resolveAgentModelPrimary(cfg, agentId) : undefined;
+  const agentModelPrimary = agentId ? resolveAgentExplicitModelPrimary(cfg, agentId) : undefined;
  const agentFallbacksOverride = agentId
    ? resolveAgentModelFallbacksOverride(cfg, agentId)
    : undefined;
@@ -87,24 +91,14 @@ export async function modelsStatusCommand(
        defaultModel: DEFAULT_MODEL,
      });

-  const modelConfig = cfg.agents?.defaults?.model as
-    | { primary?: string; fallbacks?: string[] }
-    | string
-    | undefined;
-  const imageConfig = cfg.agents?.defaults?.imageModel as
-    | { primary?: string; fallbacks?: string[] }
-    | string
-    | undefined;
-  const rawDefaultsModel =
-    typeof modelConfig === "string" ? modelConfig.trim() : (modelConfig?.primary?.trim() ?? "");
+  const rawDefaultsModel = resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model) ?? "";
  const rawModel = agentModelPrimary ?? rawDefaultsModel;
  const resolvedLabel = `${resolved.provider}/${resolved.model}`;
  const defaultLabel = rawModel || resolvedLabel;
-  const defaultsFallbacks = typeof modelConfig === "object" ? (modelConfig?.fallbacks ?? []) : [];
+  const defaultsFallbacks = resolveAgentModelFallbackValues(cfg.agents?.defaults?.model);
  const fallbacks = agentFallbacksOverride ?? defaultsFallbacks;
-  const imageModel =
-    typeof imageConfig === "string" ? imageConfig.trim() : (imageConfig?.primary?.trim() ?? "");
-  const imageFallbacks = typeof imageConfig === "object" ? (imageConfig?.fallbacks ?? []) : [];
+  const imageModel = resolveAgentModelPrimaryValue(cfg.agents?.defaults?.imageModel) ?? "";
+  const imageFallbacks = resolveAgentModelFallbackValues(cfg.agents?.defaults?.imageModel);
  const aliases = Object.entries(cfg.agents?.defaults?.models ?? {}).reduce<Record<string, string>>(
    (acc, [key, entry]) => {
      const alias = typeof entry?.alias === "string" ? entry.alias.trim() : undefined;
--- a/src/commands/models/list.status.test.ts
+++ b/src/commands/models/list.status.test.ts
@@ -32,7 +32,8 @@ const mocks = vi.hoisted(() => {
    store,
    resolveOpenClawAgentDir: vi.fn().mockReturnValue("/tmp/openclaw-agent"),
    resolveAgentDir: vi.fn().mockReturnValue("/tmp/openclaw-agent"),
-    resolveAgentModelPrimary: vi.fn().mockReturnValue(undefined),
+    resolveAgentExplicitModelPrimary: vi.fn().mockReturnValue(undefined),
+    resolveAgentEffectiveModelPrimary: vi.fn().mockReturnValue(undefined),
    resolveAgentModelFallbacksOverride: vi.fn().mockReturnValue(undefined),
    listAgentIds: vi.fn().mockReturnValue(["main", "jeremiah"]),
    ensureAuthProfileStore: vi.fn().mockReturnValue(store),
@@ -83,7 +84,8 @@ vi.mock("../../agents/agent-paths.js", () => ({

 vi.mock("../../agents/agent-scope.js", () => ({
  resolveAgentDir: mocks.resolveAgentDir,
-  resolveAgentModelPrimary: mocks.resolveAgentModelPrimary,
+  resolveAgentExplicitModelPrimary: mocks.resolveAgentExplicitModelPrimary,
+  resolveAgentEffectiveModelPrimary: mocks.resolveAgentEffectiveModelPrimary,
  resolveAgentModelFallbacksOverride: mocks.resolveAgentModelFallbacksOverride,
  listAgentIds: mocks.listAgentIds,
 }));
@@ -153,11 +155,13 @@ async function withAgentScopeOverrides<T>(
  },
  run: () => Promise<T>,
 ) {
-  const originalPrimary = mocks.resolveAgentModelPrimary.getMockImplementation();
+  const originalPrimary = mocks.resolveAgentExplicitModelPrimary.getMockImplementation();
+  const originalEffectivePrimary = mocks.resolveAgentEffectiveModelPrimary.getMockImplementation();
  const originalFallbacks = mocks.resolveAgentModelFallbacksOverride.getMockImplementation();
  const originalAgentDir = mocks.resolveAgentDir.getMockImplementation();

-  mocks.resolveAgentModelPrimary.mockReturnValue(overrides.primary);
+  mocks.resolveAgentExplicitModelPrimary.mockReturnValue(overrides.primary);
+  mocks.resolveAgentEffectiveModelPrimary.mockReturnValue(overrides.primary);
  mocks.resolveAgentModelFallbacksOverride.mockReturnValue(overrides.fallbacks);
  if (overrides.agentDir) {
    mocks.resolveAgentDir.mockReturnValue(overrides.agentDir);
@@ -167,9 +171,14 @@ async function withAgentScopeOverrides<T>(
    return await run();
  } finally {
    if (originalPrimary) {
-      mocks.resolveAgentModelPrimary.mockImplementation(originalPrimary);
+      mocks.resolveAgentExplicitModelPrimary.mockImplementation(originalPrimary);
    } else {
-      mocks.resolveAgentModelPrimary.mockReturnValue(undefined);
+      mocks.resolveAgentExplicitModelPrimary.mockReturnValue(undefined);
+    }
+    if (originalEffectivePrimary) {
+      mocks.resolveAgentEffectiveModelPrimary.mockImplementation(originalEffectivePrimary);
+    } else {
+      mocks.resolveAgentEffectiveModelPrimary.mockReturnValue(undefined);
    }
    if (originalFallbacks) {
      mocks.resolveAgentModelFallbacksOverride.mockImplementation(originalFallbacks);
@@ -262,6 +271,24 @@ describe("modelsStatusCommand auth overview", () => {
    );
  });

+  it("reports defaults source in JSON when --agent has no overrides", async () => {
+    const localRuntime = createRuntime();
+    await withAgentScopeOverrides(
+      {
+        primary: undefined,
+        fallbacks: undefined,
+      },
+      async () => {
+        await modelsStatusCommand({ json: true, agent: "main" }, localRuntime as never);
+        const payload = JSON.parse(String((localRuntime.log as Mock).mock.calls[0]?.[0]));
+        expect(payload.modelConfig).toEqual({
+          defaultSource: "defaults",
+          fallbacksSource: "defaults",
+        });
+      },
+    );
+  });
+
  it("throws when agent id is unknown", async () => {
    const localRuntime = createRuntime();
    await expect(modelsStatusCommand({ agent: "unknown" }, localRuntime as never)).rejects.toThrow(
--- a/src/commands/models/scan.ts
+++ b/src/commands/models/scan.ts
@@ -4,6 +4,7 @@ import { type ModelScanResult, scanOpenRouterModels } from "../../agents/model-s
 import { withProgressTotals } from "../../cli/progress.js";
 import { loadConfig } from "../../config/config.js";
 import { logConfigUpdated } from "../../config/logging.js";
+import { toAgentModelListLike } from "../../config/model-input.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import {
  stylePromptHint,
@@ -297,9 +298,7 @@ export async function modelsScanCommand(
        nextModels[entry] = {};
      }
    }
-    const existingImageModel = cfg.agents?.defaults?.imageModel as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
+    const existingImageModel = toAgentModelListLike(cfg.agents?.defaults?.imageModel);
    const nextImageModel =
      selectedImages.length > 0
        ? {
@@ -308,9 +307,7 @@ export async function modelsScanCommand(
            ...(opts.setImage ? { primary: selectedImages[0] } : {}),
          }
        : cfg.agents?.defaults?.imageModel;
-    const existingModel = cfg.agents?.defaults?.model as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
+    const existingModel = toAgentModelListLike(cfg.agents?.defaults?.model);
    const defaults = {
      ...cfg.agents?.defaults,
      model: {
--- a/src/commands/models/set-image.ts
+++ b/src/commands/models/set-image.ts
@@ -1,4 +1,5 @@
 import { logConfigUpdated } from "../../config/logging.js";
+import { resolveAgentModelPrimaryValue } from "../../config/model-input.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import { applyDefaultModelPrimaryUpdate, updateConfig } from "./shared.js";

@@ -8,5 +9,7 @@ export async function modelsSetImageCommand(modelRaw: string, runtime: RuntimeEn
  });

  logConfigUpdated(runtime);
-  runtime.log(`Image model: ${updated.agents?.defaults?.imageModel?.primary ?? modelRaw}`);
+  runtime.log(
+    `Image model: ${resolveAgentModelPrimaryValue(updated.agents?.defaults?.imageModel) ?? modelRaw}`,
+  );
 }
--- a/src/commands/models/set.ts
+++ b/src/commands/models/set.ts
@@ -1,4 +1,5 @@
 import { logConfigUpdated } from "../../config/logging.js";
+import { resolveAgentModelPrimaryValue } from "../../config/model-input.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import { applyDefaultModelPrimaryUpdate, updateConfig } from "./shared.js";

@@ -8,5 +9,7 @@ export async function modelsSetCommand(modelRaw: string, runtime: RuntimeEnv) {
  });

  logConfigUpdated(runtime);
-  runtime.log(`Default model: ${updated.agents?.defaults?.model?.primary ?? modelRaw}`);
+  runtime.log(
+    `Default model: ${resolveAgentModelPrimaryValue(updated.agents?.defaults?.model) ?? modelRaw}`,
+  );
 }
--- a/src/commands/models/shared.ts
+++ b/src/commands/models/shared.ts
@@ -12,6 +12,8 @@ import {
  readConfigFileSnapshot,
  writeConfigFile,
 } from "../../config/config.js";
+import { toAgentModelListLike } from "../../config/model-input.js";
+import type { AgentModelConfig } from "../../config/types.agents-shared.js";
 import { normalizeAgentId } from "../../routing/session-key.js";

 export const ensureFlagCompatibility = (opts: { json?: boolean; plain?: boolean }) => {
@@ -164,7 +166,8 @@ export function mergePrimaryFallbackConfig(
  existing: PrimaryFallbackConfig | undefined,
  patch: { primary?: string; fallbacks?: string[] },
 ): PrimaryFallbackConfig {
-  const next: PrimaryFallbackConfig = { ...existing };
+  const base = existing && typeof existing === "object" ? existing : undefined;
+  const next: PrimaryFallbackConfig = { ...base };
  if (patch.primary !== undefined) {
    next.primary = patch.primary;
  }
@@ -188,9 +191,9 @@ export function applyDefaultModelPrimaryUpdate(params: {
  }

  const defaults = params.cfg.agents?.defaults ?? {};
-  const existing = (defaults as Record<string, unknown>)[params.field] as
-    | PrimaryFallbackConfig
-    | undefined;
+  const existing = toAgentModelListLike(
+    (defaults as Record<string, unknown>)[params.field] as AgentModelConfig | undefined,
+  );

  return {
    ...params.cfg,
--- a/src/commands/onboard-auth.config-minimax.ts
+++ b/src/commands/onboard-auth.config-minimax.ts
@@ -1,4 +1,5 @@
 import type { OpenClawConfig } from "../config/config.js";
+import { toAgentModelListLike } from "../config/model-input.js";
 import type { ModelProviderConfig } from "../config/types.models.js";
 import {
  applyAgentDefaultModelPrimary,
@@ -100,7 +101,7 @@ export function applyMinimaxHostedConfig(
      defaults: {
        ...next.agents?.defaults,
        model: {
-          ...next.agents?.defaults?.model,
+          ...toAgentModelListLike(next.agents?.defaults?.model),
          primary: MINIMAX_HOSTED_MODEL_REF,
        },
      },
--- a/src/commands/onboard-auth.test.ts
+++ b/src/commands/onboard-auth.test.ts
@@ -4,6 +4,10 @@ import path from "node:path";
 import type { OAuthCredentials } from "@mariozechner/pi-ai";
 import { afterEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
+import {
+  resolveAgentModelFallbackValues,
+  resolveAgentModelPrimaryValue,
+} from "../config/model-input.js";
 import {
  applyAuthProfileConfig,
  applyLitellmProviderConfig,
@@ -84,11 +88,15 @@ function createConfigWithFallbacks() {
 }

 function expectFallbacksPreserved(cfg: ReturnType<typeof applyMinimaxApiConfig>) {
-  expect(cfg.agents?.defaults?.model?.fallbacks).toEqual([...EXPECTED_FALLBACKS]);
+  expect(resolveAgentModelFallbackValues(cfg.agents?.defaults?.model)).toEqual([
+    ...EXPECTED_FALLBACKS,
+  ]);
 }

 function expectPrimaryModelPreserved(cfg: ReturnType<typeof applyMinimaxApiProviderConfig>) {
-  expect(cfg.agents?.defaults?.model?.primary).toBe("anthropic/claude-opus-4-5");
+  expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe(
+    "anthropic/claude-opus-4-5",
+  );
 }

 function expectAllowlistContains(
@@ -431,7 +439,7 @@ describe("applyZaiConfig", () => {
    for (const modelId of ["glm-4.7-flash", "glm-4.7-flashx"] as const) {
      const cfg = applyZaiConfig({}, { endpoint: "coding-cn", modelId });
      expect(cfg.models?.providers?.zai?.baseUrl).toBe(ZAI_CODING_CN_BASE_URL);
-      expect(cfg.agents?.defaults?.model?.primary).toBe(`zai/${modelId}`);
+      expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe(`zai/${modelId}`);
    }
  });
 });
@@ -479,7 +487,7 @@ describe("primary model defaults", () => {
    ] as const;
    for (const { getConfig, primaryModel } of configCases) {
      const cfg = getConfig();
-      expect(cfg.agents?.defaults?.model?.primary).toBe(primaryModel);
+      expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe(primaryModel);
    }
  });
 });
@@ -491,7 +499,7 @@ describe("applyXiaomiConfig", () => {
      baseUrl: "https://api.xiaomimimo.com/anthropic",
      api: "anthropic-messages",
    });
-    expect(cfg.agents?.defaults?.model?.primary).toBe("xiaomi/mimo-v2-flash");
+    expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe("xiaomi/mimo-v2-flash");
  });

  it("merges Xiaomi models and keeps existing provider overrides", () => {
@@ -521,7 +529,7 @@ describe("applyXaiConfig", () => {
      baseUrl: "https://api.x.ai/v1",
      api: "openai-completions",
    });
-    expect(cfg.agents?.defaults?.model?.primary).toBe(XAI_DEFAULT_MODEL_REF);
+    expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe(XAI_DEFAULT_MODEL_REF);
  });
 });

@@ -550,7 +558,9 @@ describe("applyMistralConfig", () => {
      baseUrl: "https://api.mistral.ai/v1",
      api: "openai-completions",
    });
-    expect(cfg.agents?.defaults?.model?.primary).toBe(MISTRAL_DEFAULT_MODEL_REF);
+    expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe(
+      MISTRAL_DEFAULT_MODEL_REF,
+    );
  });
 });

@@ -685,7 +695,7 @@ describe("default-model config helpers", () => {
    ] as const;
    for (const { applyConfig, primaryModel } of configCases) {
      const cfg = applyConfig({});
-      expect(cfg.agents?.defaults?.model?.primary).toBe(primaryModel);
+      expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe(primaryModel);

      const cfgWithFallbacks = applyConfig(createConfigWithFallbacks());
      expectFallbacksPreserved(cfgWithFallbacks);
--- a/src/commands/onboard-helpers.ts
+++ b/src/commands/onboard-helpers.ts
@@ -6,6 +6,7 @@ import { cancel, isCancel } from "@clack/prompts";
 import { DEFAULT_AGENT_WORKSPACE_DIR, ensureAgentWorkspace } from "../agents/workspace.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { CONFIG_PATH } from "../config/config.js";
+import { resolveAgentModelPrimaryValue } from "../config/model-input.js";
 import { resolveSessionTranscriptsDirForAgent } from "../config/sessions.js";
 import { callGateway } from "../gateway/call.js";
 import { normalizeControlUiBasePath } from "../gateway/control-ui-shared.js";
@@ -43,7 +44,7 @@ export function summarizeExistingConfig(config: OpenClawConfig): string {
    rows.push(shortenHomeInString(`workspace: ${defaults.workspace}`));
  }
  if (defaults?.model) {
-    const model = typeof defaults.model === "string" ? defaults.model : defaults.model.primary;
+    const model = resolveAgentModelPrimaryValue(defaults.model);
    if (model) {
      rows.push(shortenHomeInString(`model: ${model}`));
    }