openclaw
diff --git a/‎docs/concepts/models.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/concepts/models.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/gateway/config-agents.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/gateway/config-agents.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/web/control-ui.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/web/control-ui.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎src/auto-reply/reply/conversation-label-generator.test.ts‎
Lines changed: 93 additions & 0 deletions b/‎src/auto-reply/reply/conversation-label-generator.test.ts‎
Lines changed: 93 additions & 0 deletions
diff --git a/‎src/auto-reply/reply/conversation-label-generator.ts‎
Lines changed: 122 additions & 32 deletions b/‎src/auto-reply/reply/conversation-label-generator.ts‎
Lines changed: 122 additions & 32 deletions
@@ -57,7 +57,7 @@ Related model-config surfaces:
 
 - `agents.defaults.models` stores aliases and per-model settings. Adding an entry does not restrict model overrides.
 - `agents.defaults.modelPolicy.allow` is the optional override allowlist. Use exact refs or trailing prefix wildcards such as `provider/*` and `provider/namespace/*`; omit it or set `[]` to allow any model. Per-agent `agents.list[].modelPolicy.allow` replaces the default policy for that agent.
-- `agents.defaults.utilityModel` is an optional lower-cost model for short internal tasks such as generated dashboard session titles, supported channel thread/topic titles, and progress narration. Per-agent `agents.list[].utilityModel` overrides it. When unset, OpenClaw uses the primary provider's declared small-model default when one exists (OpenAI → `gpt-5.6-luna`, Anthropic → `claude-haiku-4-5`), otherwise the agent's primary model; set it to an empty string to disable utility routing. Utility tasks are separate model calls and may send bounded task content to the selected model provider.
+- `agents.defaults.utilityModel` is an optional lower-cost model for short internal tasks such as generated dashboard session titles, supported channel thread/topic titles, and progress narration. Per-agent `agents.list[].utilityModel` overrides it. When unset, OpenClaw uses the primary provider's declared small-model default when one exists (OpenAI → `gpt-5.6-luna`, Anthropic → `claude-haiku-4-5`), otherwise the agent's primary model; set it to an empty string to disable utility routing. Generated title tasks retry once with the primary model when a distinct utility model fails. Utility tasks are separate model calls and may send bounded task content to the selected model provider.
 - `agents.defaults.imageModel` is used only when the primary model cannot accept images.
 - `agents.defaults.pdfModel` is used by the `pdf` tool. If unset, the tool falls back to `imageModel`, then the resolved session/default model.
 - `agents.defaults.imageGenerationModel`, `musicGenerationModel`, and `videoGenerationModel` back the shared media-generation tools. If unset, each tool infers an auth-backed provider default: current default provider first, then the remaining registered providers for that capability in provider-id order. Set `agents.defaults.mediaGenerationAutoProviderFallback: false` to disable that cross-provider inference while keeping explicit fallbacks.
 
@@ -401,7 +401,7 @@ Time format in system prompt. Default: `auto` (OS preference).
 - `model`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - String form sets only the primary model.
   - Object form sets primary plus ordered failover models.
-- `utilityModel`: optional `provider/model` ref or alias for short internal tasks. It currently powers generated Control UI session titles, Telegram DM topic titles, Discord auto-thread titles, and [progress-draft narration](/concepts/progress-drafts#narrated-status). When unset, OpenClaw derives the primary provider's declared small-model default when one exists (OpenAI → `gpt-5.6-luna`, Anthropic → `claude-haiku-4-5`); title tasks otherwise fall back to the agent's primary model, and narration stays off. Set `utilityModel: ""` to disable utility routing entirely. `agents.list[].utilityModel` overrides the default (an empty per-agent value disables it for that agent), and an operation-specific model override wins over both. Utility tasks make separate model calls and send task-specific content to the selected model provider. Dashboard title generation sends at most the first 1,000 characters of the first non-command message; narration sends the inbound request plus compact redacted tool summaries. Choose a provider that matches your cost and data-handling requirements.
+- `utilityModel`: optional `provider/model` ref or alias for short internal tasks. It currently powers generated Control UI session titles, Telegram DM topic titles, Discord auto-thread titles, and [progress-draft narration](/concepts/progress-drafts#narrated-status). When unset, OpenClaw derives the primary provider's declared small-model default when one exists (OpenAI → `gpt-5.6-luna`, Anthropic → `claude-haiku-4-5`); title tasks otherwise use the agent's primary model, and narration stays off. If a distinct utility model cannot prepare or complete a generated title, OpenClaw retries that title once with the primary model. Set `utilityModel: ""` to disable utility routing entirely. `agents.list[].utilityModel` overrides the default (an empty per-agent value disables it for that agent), and an operation-specific model override wins over both. Utility tasks make separate model calls and send task-specific content to the selected model provider. Dashboard title generation sends at most the first 1,000 characters of the first non-command message; narration sends the inbound request plus compact redacted tool summaries. Choose a provider that matches your cost and data-handling requirements.
 - `imageModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the `image` tool path as its vision-model config when the active model cannot accept images. Native-vision models receive loaded image bytes directly instead.
   - Also used as fallback routing when the selected/default model cannot accept image input.
 
@@ -391,7 +391,7 @@ The macOS app keeps its native link-browser sidebar for links clicked in the das
     - During an active send and the final history refresh, the chat view keeps local optimistic user/assistant messages visible if `chat.history` briefly returns an older snapshot; the canonical transcript replaces those local messages once the Gateway history catches up.
     - Live `chat` events are delivery state, while `chat.history` is rebuilt from the durable session transcript. After tool-final events the Control UI reloads history and merges only a small optimistic tail; the transcript boundary is documented in [WebChat](/web/webchat).
     - `chat.inject` appends an assistant note to the session transcript and broadcasts a `chat` event for UI-only updates (no agent run, no channel delivery).
-    - The sidebar lists every loaded active session by agent section and pinned/channel/work/custom/Chats buckets with a single New Session action that opens the draft dialog. Opening a visible row moves only the highlight. Sessions can be dropped onto Pinned to pin them, or onto a custom group or Chats to move them; custom groups are collapsible and drag-reorderable, group names and order sync through the gateway, and collapsed state stays in the browser. A new dashboard session asynchronously gets a concise generated title from its first non-command message; explicit names are never replaced. Set `agents.defaults.utilityModel` (or `agents.list[].utilityModel`) to route this separate model call to a lower-cost model. Expanding another agent section browses that agent's sessions without leaving the open chat.
+    - The sidebar lists every loaded active session by agent section and pinned/channel/work/custom/Chats buckets with a single New Session action that opens the draft dialog. Opening a visible row moves only the highlight. Sessions can be dropped onto Pinned to pin them, or onto a custom group or Chats to move them; custom groups are collapsible and drag-reorderable, group names and order sync through the gateway, and collapsed state stays in the browser. A new dashboard session asynchronously gets a concise generated title from its first non-command message; explicit names and authenticated sender identity remain separate, so account names are never used as generated titles. Set `agents.defaults.utilityModel` (or `agents.list[].utilityModel`) to route this separate model call to a lower-cost model; if that distinct model fails, title generation retries once with the primary model. Expanding another agent section browses that agent's sessions without leaving the open chat.
     - Thread search lives in the command palette (⌘K, or the Search field at the top of the sidebar): typing a query follows a bounded number of matching pages across agents, filters internal child/cron rows, and lists visible matches next to navigation commands. The Threads page keeps the exhaustive searchable list with filters.
     - Each sidebar row keeps direct pin access plus a full context menu for unread state, rename, fork, grouping, archive, and delete. Multi-selected rows (Cmd/Ctrl-click, Shift-click for ranges) get a batch menu covering unread state, grouping, archive, and delete; batch archive/delete stays disabled unless every selected session is archivable. An active run and an agent's main session cannot be archived. Archiving or deleting the currently selected session switches Chat back to that agent's main session.
     - In the macOS app, the OpenClaw mark uses the otherwise-empty native titlebar strip next to the window controls instead of consuming a sidebar row.
 
@@ -164,6 +164,99 @@ describe("generateConversationLabel", () => {
     expect(completeWithPreparedSimpleCompletionModel).not.toHaveBeenCalled();
   });
 
+  it("falls back to the primary model when utility model preparation fails", async () => {
+    prepareSimpleCompletionModelForAgent
+      .mockResolvedValueOnce({
+        error: 'No API key resolved for provider "openai".',
+        selection: {
+          provider: "openai",
+          modelId: "gpt-5.6-luna",
+          agentDir: "/tmp/openclaw-agent",
+        },
+      })
+      .mockResolvedValueOnce({
+        selection: {
+          provider: "openai",
+          modelId: "gpt-5.6-sol",
+          agentDir: "/tmp/openclaw-agent",
+        },
+        model: { provider: "openai", id: "gpt-5.6-sol", maxTokens: 8192 },
+        auth: { apiKey: "test-api-key", mode: "api-key" },
+      });
+
+    await expect(
+      generateConversationLabel({
+        userMessage: "Need help with invoices",
+        prompt: "Generate a label",
+        cfg: {},
+      }),
+    ).resolves.toBe("Topic label");
+
+    expect(prepareSimpleCompletionModelForAgent).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ useUtilityModel: false }),
+    );
+    expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledOnce();
+  });
+
+  it("falls back to the primary model when the utility completion fails", async () => {
+    prepareSimpleCompletionModelForAgent
+      .mockResolvedValueOnce({
+        selection: {
+          provider: "openai",
+          modelId: "gpt-5.6-luna",
+          agentDir: "/tmp/openclaw-agent",
+        },
+        model: { provider: "openai", id: "gpt-5.6-luna", maxTokens: 8192 },
+        auth: { apiKey: "test-api-key", mode: "oauth" },
+      })
+      .mockResolvedValueOnce({
+        selection: {
+          provider: "openai",
+          modelId: "gpt-5.6-sol",
+          agentDir: "/tmp/openclaw-agent",
+        },
+        model: { provider: "openai", id: "gpt-5.6-sol", maxTokens: 8192 },
+        auth: { apiKey: "test-api-key", mode: "oauth" },
+      });
+    completeWithPreparedSimpleCompletionModel
+      .mockResolvedValueOnce({
+        content: [],
+        stopReason: "error",
+        errorMessage: "utility unavailable",
+      })
+      .mockResolvedValueOnce({ content: [{ type: "text", text: "Primary title" }] });
+
+    await expect(
+      generateConversationLabel({
+        userMessage: "Need help with invoices",
+        prompt: "Generate a label",
+        cfg: {},
+      }),
+    ).resolves.toBe("Primary title");
+
+    expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not call the same primary model twice when utility routing resolves to it", async () => {
+    completeWithPreparedSimpleCompletionModel.mockResolvedValue({
+      content: [],
+      stopReason: "error",
+      errorMessage: "primary unavailable",
+    });
+
+    await expect(
+      generateConversationLabel({
+        userMessage: "Need help with invoices",
+        prompt: "Generate a label",
+        cfg: {},
+      }),
+    ).resolves.toBeNull();
+
+    expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledTimes(2);
+    expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledOnce();
+  });
+
   it("logs completion errors instead of treating them as empty labels", async () => {
     completeWithPreparedSimpleCompletionModel.mockResolvedValue({
       content: [],
 
@@ -16,6 +16,10 @@ const DEFAULT_MAX_LABEL_LENGTH = 128;
 const CONVERSATION_LABEL_MAX_TOKENS = 4_096;
 const TIMEOUT_MS = 15_000;
 
+type PreparedLabelModel = Awaited<ReturnType<typeof prepareSimpleCompletionModelForAgent>>;
+type ReadyLabelModel = Extract<PreparedLabelModel, { model: unknown }>;
+type LabelModelPhase = "utility" | "primary fallback";
+
 /** Inputs for generating a short conversation label from the configured utility model. */
 export type ConversationLabelParams = {
   userMessage: string;
@@ -44,64 +48,92 @@ function extractSimpleCompletionError(result: {
   return result.errorMessage?.trim() || "unknown error";
 }
 
-/** Generates a bounded human-readable label for a session, or null on failure. */
-export async function generateConversationLabel(
-  params: ConversationLabelParams,
-): Promise<string | null> {
-  const { userMessage, prompt, cfg, agentId, agentDir } = params;
-  const maxLength =
-    typeof params.maxLength === "number" &&
-    Number.isFinite(params.maxLength) &&
-    params.maxLength > 0
-      ? Math.floor(params.maxLength)
-      : DEFAULT_MAX_LABEL_LENGTH;
-  let prepared: Awaited<ReturnType<typeof prepareSimpleCompletionModelForAgent>>;
+function logLabelFailure(phase: LabelModelPhase, message: string): void {
+  const prefix = phase === "utility" ? "" : `${phase} `;
+  logVerbose(`conversation-label-generator: ${prefix}${message}`);
+}
+
+async function prepareLabelModel(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  agentDir?: string;
+  useUtilityModel: boolean;
+  phase: LabelModelPhase;
+}): Promise<PreparedLabelModel | null> {
   try {
-    prepared = await prepareSimpleCompletionModelForAgent({
-      cfg,
-      agentId: agentId ?? resolveDefaultAgentId(cfg),
-      agentDir,
-      useUtilityModel: true,
+    const prepared = await prepareSimpleCompletionModelForAgent({
+      cfg: params.cfg,
+      agentId: params.agentId,
+      agentDir: params.agentDir,
+      useUtilityModel: params.useUtilityModel,
       useAsyncModelResolution: true,
       allowMissingApiKeyModes: ["aws-sdk"],
     });
+    if ("error" in prepared) {
+      logLabelFailure(params.phase, prepared.error);
+    }
+    return prepared;
   } catch (err) {
-    logVerbose(`conversation-label-generator: model preparation failed: ${String(err)}`);
-    return null;
-  }
-  if ("error" in prepared) {
-    logVerbose(`conversation-label-generator: ${prepared.error}`);
+    logLabelFailure(params.phase, `model preparation failed: ${String(err)}`);
     return null;
   }
+}
 
+function selectedLabelModelsMatch(
+  first: PreparedLabelModel | null,
+  second: PreparedLabelModel | null,
+): boolean {
+  const firstSelection = first && "selection" in first ? first.selection : undefined;
+  const secondSelection = second && "selection" in second ? second.selection : undefined;
+  return Boolean(
+    firstSelection &&
+    secondSelection &&
+    firstSelection.provider === secondSelection.provider &&
+    firstSelection.runtimeProvider === secondSelection.runtimeProvider &&
+    firstSelection.modelId === secondSelection.modelId &&
+    firstSelection.profileId === secondSelection.profileId,
+  );
+}
+
+async function completeLabel(params: {
+  prepared: ReadyLabelModel;
+  cfg: OpenClawConfig;
+  userMessage: string;
+  prompt: string;
+  maxLength: number;
+  phase: LabelModelPhase;
+}): Promise<string | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
   try {
-    const maxTokens = Math.min(CONVERSATION_LABEL_MAX_TOKENS, Math.floor(prepared.model.maxTokens));
+    const maxTokens = Math.min(
+      CONVERSATION_LABEL_MAX_TOKENS,
+      Math.floor(params.prepared.model.maxTokens),
+    );
     // Label generation should never block normal reply handling for long.
     const result = await completeWithPreparedSimpleCompletionModel({
-      model: prepared.model,
-      auth: prepared.auth,
-      cfg,
+      model: params.prepared.model,
+      auth: params.prepared.auth,
+      cfg: params.cfg,
       context: {
-        systemPrompt: prompt,
+        systemPrompt: params.prompt,
         messages: [
           {
             role: "user",
-            content: userMessage,
+            content: params.userMessage,
             timestamp: Date.now(),
           },
         ],
       },
       options: {
         maxTokens,
-        ...(isCodexSimpleCompletionModel(prepared.model) ? {} : { temperature: 0.3 }),
+        ...(isCodexSimpleCompletionModel(params.prepared.model) ? {} : { temperature: 0.3 }),
         signal: controller.signal,
       },
     });
     const errorMessage = extractSimpleCompletionError(result);
     if (errorMessage) {
-      logVerbose(`conversation-label-generator: completion failed: ${errorMessage}`);
+      logLabelFailure(params.phase, `completion failed: ${errorMessage}`);
       return null;
     }
 
@@ -115,11 +147,69 @@ export async function generateConversationLabel(
       return null;
     }
 
-    return truncateUtf16Safe(text, maxLength) || null;
+    return truncateUtf16Safe(text, params.maxLength) || null;
   } catch (err) {
-    logVerbose(`conversation-label-generator: completion failed: ${String(err)}`);
+    logLabelFailure(params.phase, `completion failed: ${String(err)}`);
     return null;
   } finally {
     clearTimeout(timeout);
   }
 }
+
+/** Generates a bounded human-readable label for a session, or null on failure. */
+export async function generateConversationLabel(
+  params: ConversationLabelParams,
+): Promise<string | null> {
+  const { userMessage, prompt, cfg, agentId, agentDir } = params;
+  const maxLength =
+    typeof params.maxLength === "number" &&
+    Number.isFinite(params.maxLength) &&
+    params.maxLength > 0
+      ? Math.floor(params.maxLength)
+      : DEFAULT_MAX_LABEL_LENGTH;
+  const resolvedAgentId = agentId ?? resolveDefaultAgentId(cfg);
+  const utilityPrepared = await prepareLabelModel({
+    cfg,
+    agentId: resolvedAgentId,
+    agentDir,
+    useUtilityModel: true,
+    phase: "utility",
+  });
+  const utilityCompletionAttempted = Boolean(utilityPrepared && !("error" in utilityPrepared));
+  if (utilityPrepared && !("error" in utilityPrepared)) {
+    const label = await completeLabel({
+      prepared: utilityPrepared,
+      cfg,
+      userMessage,
+      prompt,
+      maxLength,
+      phase: "utility",
+    });
+    if (label) {
+      return label;
+    }
+  }
+
+  const primaryPrepared = await prepareLabelModel({
+    cfg,
+    agentId: resolvedAgentId,
+    agentDir,
+    useUtilityModel: false,
+    phase: "primary fallback",
+  });
+  if (
+    !primaryPrepared ||
+    "error" in primaryPrepared ||
+    (utilityCompletionAttempted && selectedLabelModelsMatch(utilityPrepared, primaryPrepared))
+  ) {
+    return null;
+  }
+  return await completeLabel({
+    prepared: primaryPrepared,
+    cfg,
+    userMessage,
+    prompt,
+    maxLength,
+    phase: "primary fallback",
+  });
+}