feat(providers): custom icon URL for compatible provider nodes

config/quality/file-size-baseline.json

@@ -299,7 +299,7 @@
     "tests/unit/provider-models-route.test.ts": 1752,
     "tests/unit/provider-validation-specialty.test.ts": 2874,
     "_rebaseline_pr4613_compatible_provider_groups": "Reconcile #4613 already-merged growth: providers-page-utils.test.ts 1004->1052 (+48, buildCompatibleProviderGroups partition unit test). Fast-gate PR->release does not run check:file-size, so this surfaced post-merge.",
-    "tests/unit/providers-page-utils.test.ts": 1092,
+    "tests/unit/providers-page-utils.test.ts": 1109,
     "tests/unit/reasoning-cache.test.ts": 980,
     "tests/unit/route-edge-coverage.test.ts": 1234,
     "tests/unit/search-handler-extended.test.ts": 1124,

src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleNodeCard.tsx

@@ -3,6 +3,7 @@
 // Phase 1t.2 extraction — Issue #3501
 import { useRouter } from "next/navigation";
 import { Card, Button } from "@/shared/components";
+import ProviderIcon from "@/shared/components/ProviderIcon";
 import { getApiLabel, getApiPath } from "../providerPageHelpers";
 import type { ProviderMessageTranslator } from "../providerPageHelpers";
 
@@ -11,6 +12,8 @@ interface ProviderNode {
   apiType?: string;
   chatPath?: string;
   prefix?: string;
+  /** Optional operator-supplied remote icon URL (#2166). */
+  iconUrl?: string;
   [key: string]: unknown;
 }
 
@@ -42,24 +45,35 @@ export default function CompatibleNodeCard({
   return (
     <Card>
       <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
-        <div>
-          <h2 className="text-lg font-semibold">
-            {isCcCompatible
-              ? t("ccCompatibleDetailsTitle")
-              : isAnthropicCompatible
-                ? t("anthropicCompatibleDetails")
-                : t("openaiCompatibleDetails")}
-          </h2>
-          <p className="text-sm text-text-muted">
-            {getApiLabel(t, isAnthropicProtocolCompatible, providerNode?.apiType)} ·{" "}
-            {(providerNode.baseUrl || "").replace(/\/$/, "")}/
-            {getApiPath(
-              isCcCompatible,
-              isAnthropicCompatible,
-              providerNode?.apiType,
-              providerNode?.chatPath
-            )}
-          </p>
+        <div className="flex items-center gap-3">
+          {providerNode.iconUrl && (
+            <ProviderIcon
+              providerId={providerId}
+              src={providerNode.iconUrl}
+              size={32}
+              className="shrink-0 rounded-lg"
+              fallbackText={isCcCompatible ? "CC" : isAnthropicCompatible ? "AC" : "OC"}
+            />
+          )}
+          <div>
+            <h2 className="text-lg font-semibold">
+              {isCcCompatible
+                ? t("ccCompatibleDetailsTitle")
+                : isAnthropicCompatible
+                  ? t("anthropicCompatibleDetails")
+                  : t("openaiCompatibleDetails")}
+            </h2>
+            <p className="text-sm text-text-muted">
+              {getApiLabel(t, isAnthropicProtocolCompatible, providerNode?.apiType)} ·{" "}
+              {(providerNode.baseUrl || "").replace(/\/$/, "")}/
+              {getApiPath(
+                isCcCompatible,
+                isAnthropicCompatible,
+                providerNode?.apiType,
+                providerNode?.chatPath
+              )}
+            </p>
+          </div>
         </div>
         <div className="flex flex-wrap items-center gap-2">
           <Button size="sm" icon="add" onClick={() => gateConnectionFlow(openApiKeyAddFlow)}>

src/app/(dashboard)/dashboard/providers/[id]/components/ProviderPageHeader.tsx

@@ -12,6 +12,10 @@ interface ProviderInfo {
   website?: string;
   color: string;
   apiType?: string;
+  /** Optional operator-supplied remote icon URL (#2166) for compatible provider nodes. */
+  iconUrl?: string;
+  /** Short text-badge fallback (e.g. "OC"/"AC"/"CC") shown if `iconUrl` fails to load. */
+  textIcon?: string;
 }
 
 interface ProviderPageHeaderProps {
@@ -56,6 +60,10 @@ export default function ProviderPageHeader({
             )}
             size={48}
             type="color"
+            src={providerInfo.iconUrl}
+            alt={providerInfo.name}
+            fallbackText={providerInfo.textIcon}
+            fallbackColor={providerInfo.color}
           />
         </div>
         <div>

src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx

@@ -11,6 +11,7 @@ interface EditCompatibleNodeModalNode {
   baseUrl?: string;
   chatPath?: string;
   modelsPath?: string;
+  iconUrl?: string;
 }
 
 interface EditCompatibleNodeModalProps {
@@ -38,6 +39,7 @@ export default function EditCompatibleNodeModal({
     baseUrl: "https://api.openai.com/v1",
     chatPath: "",
     modelsPath: "",
+    iconUrl: "",
   });
   const [saving, setSaving] = useState(false);
   const [checkKey, setCheckKey] = useState("");
@@ -63,6 +65,7 @@ export default function EditCompatibleNodeModal({
               : "https://api.openai.com/v1"),
         chatPath: node.chatPath || (isCcCompatible ? CC_COMPATIBLE_DEFAULT_CHAT_PATH : ""),
         modelsPath: isCcCompatible ? "" : node.modelsPath || "",
+        iconUrl: node.iconUrl || "",
       });
       setShowAdvanced(
         !!(
@@ -93,6 +96,7 @@ export default function EditCompatibleNodeModal({
         baseUrl: formData.baseUrl,
         chatPath: formData.chatPath || (isCcCompatible ? CC_COMPATIBLE_DEFAULT_CHAT_PATH : ""),
         modelsPath: isCcCompatible ? "" : formData.modelsPath,
+        iconUrl: formData.iconUrl.trim(),
       };
       if (!isAnthropic) {
         payload.apiType = formData.apiType;
@@ -208,6 +212,13 @@ export default function EditCompatibleNodeModal({
                 })
           }
         />
+        <Input
+          label={t("iconUrlLabel")}
+          value={formData.iconUrl}
+          onChange={(e) => setFormData({ ...formData, iconUrl: e.target.value })}
+          placeholder="https://example.com/logo.png"
+          hint={t("iconUrlHint")}
+        />
         <button
           type="button"
           className="text-sm text-text-muted hover:text-text-primary flex items-center gap-1"

src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx

@@ -23,6 +23,7 @@ interface CompatibleFormState {
   baseUrl: string;
   chatPath: string;
   modelsPath: string;
+  iconUrl: string;
 }
 
 const CC_DEFAULT_CHAT_PATH = "/v1/messages?beta=true";
@@ -75,6 +76,7 @@ function createInitialForm(mode: CompatibleMode): CompatibleFormState {
     baseUrl: defaults.baseUrl,
     chatPath: defaults.chatPath,
     modelsPath: "",
+    iconUrl: "",
   };
 }
 
@@ -181,6 +183,7 @@ export default function AddCompatibleProviderModal({
       if (defaults.hasApiType) body.apiType = formData.apiType;
       if (defaults.hasModelsPath) body.modelsPath = formData.modelsPath || "";
       if (defaults.compatMode) body.compatMode = defaults.compatMode;
+      body.iconUrl = formData.iconUrl.trim();
 
       const res = await fetch("/api/provider-nodes", {
         method: "POST",
@@ -276,6 +279,13 @@ export default function AddCompatibleProviderModal({
           placeholder={baseUrlPlaceholder}
           hint={baseUrlHint}
         />
+        <Input
+          label={t("iconUrlLabel")}
+          value={formData.iconUrl}
+          onChange={(e) => setFormData({ ...formData, iconUrl: e.target.value })}
+          placeholder="https://example.com/logo.png"
+          hint={t("iconUrlHint")}
+        />
 
         <button
           type="button"

src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx

@@ -56,6 +56,10 @@ interface ProviderCardProps {
     subscriptionRisk?: boolean;
     /** Declared service kinds — "llm" enables the inline Test button */
     serviceKinds?: string[];
+    /** Optional operator-supplied remote icon URL (#2166) for compatible provider nodes. */
+    iconUrl?: string;
+    /** Short text-badge fallback (e.g. "OC"/"AC"/"CC") shown if `iconUrl` fails to load. */
+    textIcon?: string;
   };
   stats: ProviderStats;
   authType?: string;
@@ -240,7 +244,17 @@ export default function ProviderCard({
                 className="size-9 rounded-lg flex items-center justify-center shrink-0"
                 style={{ backgroundColor: `${provider.color || "#64748b"}15` }}
               >
-                {staticIconPath ? (
+                {provider.iconUrl ? (
+                  <ProviderIcon
+                    providerId={provider.id || providerId}
+                    src={provider.iconUrl}
+                    alt={provider.name}
+                    size={26}
+                    className="max-h-[26px] max-w-[26px] rounded-lg object-contain"
+                    fallbackText={provider.textIcon}
+                    fallbackColor={provider.color}
+                  />
+                ) : staticIconPath ? (
                   <Image
                     src={staticIconPath}
                     alt={provider.name}

src/app/(dashboard)/dashboard/providers/providerPageUtils.ts

@@ -35,6 +35,8 @@ export type CompatibleProviderInfo = {
   color: string;
   textIcon: string;
   apiType?: string;
+  /** Optional operator-supplied remote icon URL (#2166). */
+  iconUrl?: string;
 };
 
 export type CompatibleProviderGroups = {
@@ -149,7 +151,13 @@ export function buildStaticProviderEntries(
 }
 
 export function buildCompatibleProviderGroups(
-  providerNodes: Array<{ id: string; name?: string; type?: string; apiType?: string }>,
+  providerNodes: Array<{
+    id: string;
+    name?: string;
+    type?: string;
+    apiType?: string;
+    iconUrl?: string | null;
+  }>,
   labels: {
     openaiCompatibleName: string;
     anthropicCompatibleName: string;
@@ -168,6 +176,7 @@ export function buildCompatibleProviderGroups(
         color: "#10A37F",
         textIcon: "OC",
         apiType: node.apiType,
+        iconUrl: node.iconUrl || undefined,
       });
       continue;
     }
@@ -180,6 +189,7 @@ export function buildCompatibleProviderGroups(
         name: node.name || labels.claudeCodeCompatibleName,
         color: "#B45309",
         textIcon: "CC",
+        iconUrl: node.iconUrl || undefined,
       });
       continue;
     }
@@ -189,6 +199,7 @@ export function buildCompatibleProviderGroups(
       name: node.name || labels.anthropicCompatibleName,
       color: "#D97757",
       textIcon: "AC",
+      iconUrl: node.iconUrl || undefined,
     });
   }
 

src/app/api/provider-nodes/[id]/route.ts

@@ -56,7 +56,8 @@ export async function PUT(request: Request, { params }: { params: Promise<{ id:
     if (isValidationFailure(validation)) {
       return NextResponse.json({ error: validation.error }, { status: 400 });
     }
-    const { name, prefix, apiType, baseUrl, chatPath, modelsPath, customHeaders } = validation.data;
+    const { name, prefix, apiType, baseUrl, chatPath, modelsPath, customHeaders, iconUrl } =
+      validation.data;
     const node: any = await getProviderNodeById(id);
 
     if (!node) {
@@ -93,6 +94,9 @@ export async function PUT(request: Request, { params }: { params: Promise<{ id:
       baseUrl: sanitizedBaseUrl,
       chatPath: chatPath || null,
       modelsPath: isClaudeCodeCompatibleProvider(id) ? null : modelsPath || null,
+      // #2166: explicit null (not omission) so an empty submission clears a
+      // previously stored custom icon.
+      iconUrl: iconUrl?.trim() || null,
       customHeaders: customHeaders || null,
     };
 

src/app/api/provider-nodes/route.ts

@@ -79,6 +79,7 @@ export async function POST(request) {
       chatPath,
       modelsPath,
       customHeaders,
+      iconUrl,
     } = validation.data;
 
     // Determine type
@@ -98,6 +99,7 @@ export async function POST(request) {
         name: name.trim(),
         chatPath: chatPath || null,
         modelsPath: modelsPath || null,
+        iconUrl: iconUrl?.trim() || null,
         customHeaders: customHeaders || null,
       });
       return NextResponse.json({ node }, { status: 201 });
@@ -127,6 +129,7 @@ export async function POST(request) {
         name: name.trim(),
         chatPath: chatPath || null,
         modelsPath: compatMode === "cc" ? null : modelsPath || null,
+        iconUrl: iconUrl?.trim() || null,
         customHeaders: customHeaders || null,
       });
       return NextResponse.json({ node }, { status: 201 });

src/lib/db/migrations/113_provider_node_icon_url.sql

@@ -0,0 +1,5 @@
+-- Add icon_url column to provider_nodes
+-- Stores an optional operator-supplied remote icon URL for OpenAI-/Anthropic-compatible
+-- provider nodes. NULL = no custom icon (falls back to the built-in @lobehub/static resolution).
+-- Plain TEXT column (no `_json` suffix) — rowToCamel passes it through as a string as-is.
+ALTER TABLE provider_nodes ADD COLUMN icon_url TEXT;

src/lib/db/providers/nodes.ts

@@ -64,15 +64,17 @@ export async function createProviderNode(data: JsonRecord) {
     baseUrl: data.baseUrl || null,
     chatPath: data.chatPath || null,
     modelsPath: data.modelsPath || null,
+    // Optional operator-supplied remote icon URL (#2166) — plain TEXT, no JSON parsing needed.
+    iconUrl: data.iconUrl || null,
     customHeadersJson,
     createdAt: now,
     updatedAt: now,
   };
 
   db.prepare(
     `
-    INSERT INTO provider_nodes (id, type, name, prefix, api_type, base_url, chat_path, models_path, custom_headers_json, created_at, updated_at)
-    VALUES (@id, @type, @name, @prefix, @apiType, @baseUrl, @chatPath, @modelsPath, @customHeadersJson, @createdAt, @updatedAt)
+    INSERT INTO provider_nodes (id, type, name, prefix, api_type, base_url, chat_path, models_path, icon_url, custom_headers_json, created_at, updated_at)
+    VALUES (@id, @type, @name, @prefix, @apiType, @baseUrl, @chatPath, @modelsPath, @iconUrl, @customHeadersJson, @createdAt, @updatedAt)
   `
   ).run(node);
 
@@ -119,7 +121,8 @@ export async function updateProviderNode(id: string, data: JsonRecord) {
     `
     UPDATE provider_nodes SET type = @type, name = @name, prefix = @prefix,
     api_type = @apiType, base_url = @baseUrl, chat_path = @chatPath,
-    models_path = @modelsPath, custom_headers_json = @customHeadersJson, updated_at = @updatedAt
+    models_path = @modelsPath, icon_url = @iconUrl,
+    custom_headers_json = @customHeadersJson, updated_at = @updatedAt
     WHERE id = @id
   `
   ).run({
@@ -131,6 +134,9 @@ export async function updateProviderNode(id: string, data: JsonRecord) {
     baseUrl: merged["baseUrl"] || null,
     chatPath: merged["chatPath"] || null,
     modelsPath: merged["modelsPath"] || null,
+    // #2166: iconUrl is nullable — explicit `null` (not omission) clears a previously
+    // stored custom icon when the caller submits an empty value.
+    iconUrl: merged["iconUrl"] || null,
     customHeadersJson: merged["customHeadersJson"] || null,
     updatedAt: merged["updatedAt"],
   });

src/lib/providers/catalog.ts

@@ -41,6 +41,8 @@ export interface ProviderCatalogMetadata {
   riskNoticeVariant?: RiskNoticeVariant;
   apiType?: string;
   baseUrl?: string;
+  /** Optional operator-supplied remote icon URL (#2166) for compatible provider nodes. */
+  iconUrl?: string;
   [key: string]: unknown;
 }
 
@@ -59,6 +61,8 @@ export interface CompatibleProviderNodeLike {
   type?: string | null;
   apiType?: string | null;
   baseUrl?: string | null;
+  /** Optional operator-supplied remote icon URL (#2166). */
+  iconUrl?: string | null;
 }
 
 export interface CompatibleProviderLabels {
@@ -218,6 +222,7 @@ export function resolveCompatibleProviderCatalogEntry(
     textIcon: isCcCompatible ? "CC" : isAnthropicCompatible ? "AC" : "OC",
     apiType: providerNode.apiType || undefined,
     baseUrl: providerNode.baseUrl || undefined,
+    iconUrl: providerNode.iconUrl || undefined,
     type: providerNode.type,
     category: "compatible",
     displayAuthType: "compatible",