From a49d34bf49f99a2ccab6bb14835f8d89820bbf2e Mon Sep 17 00:00:00 2001
From: Diego Rodrigues de Sa e Souza
 <8016841+diegosouzapw@users.noreply.github.com>
Date: Thu, 2 Jul 2026 22:08:44 -0300
Subject: [PATCH] feat(providers): custom icon URL for compatible provider
 nodes (#5815)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Integrated into release/v3.8.44 — custom icon URL for compatible provider nodes (DB migration 113 + nodes.ts + Zod schema + API routes + catalog + ProviderIcon UI). Re-cut onto the release tip (branch was fossilized ~13 real files); reconciled icon_url into the release's evolved nodes.ts/routes via 3-way. Validated: 14 backend + 5 frontend(vitest) + 24 page-utils tests green, typecheck:core 0, provider-consistency OK, file-size/env-doc-sync pass. UNSTABLE red is the inherited environmental setup-claude base-red.
---
 config/quality/file-size-baseline.json        |   2 +-
 .../[id]/components/CompatibleNodeCard.tsx    |  50 ++--
 .../[id]/components/ProviderPageHeader.tsx    |   8 +
 .../modals/EditCompatibleNodeModal.tsx        |  11 +
 .../components/AddCompatibleProviderModal.tsx |  10 +
 .../providers/components/ProviderCard.tsx     |  16 +-
 .../dashboard/providers/providerPageUtils.ts  |  13 +-
 src/app/api/provider-nodes/[id]/route.ts      |   6 +-
 src/app/api/provider-nodes/route.ts           |   3 +
 .../migrations/113_provider_node_icon_url.sql |   5 +
 src/lib/db/providers/nodes.ts                 |  12 +-
 src/lib/providers/catalog.ts                  |   5 +
 src/shared/components/ProviderIcon.tsx        |  63 ++++
 src/shared/validation/schemas/provider.ts     |  24 ++
 tests/unit/provider-node-icon-url.test.ts     | 280 ++++++++++++++++++
 tests/unit/providers-page-utils.test.ts       |  19 +-
 tests/unit/ui/ProviderIcon-icon-url.test.tsx  | 110 +++++++
 17 files changed, 611 insertions(+), 26 deletions(-)
 create mode 100644 src/lib/db/migrations/113_provider_node_icon_url.sql
 create mode 100644 tests/unit/provider-node-icon-url.test.ts
 create mode 100644 tests/unit/ui/ProviderIcon-icon-url.test.tsx

diff --git a/config/quality/file-size-baseline.json b/config/quality/file-size-baseline.json
index 8c9420bada..69e8fbf2bc 100644
--- a/config/quality/file-size-baseline.json
+++ b/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,
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleNodeCard.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleNodeCard.tsx
index 1b01f2eb7d..5347c075a8 100644
--- a/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleNodeCard.tsx
+++ b/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)}>
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/ProviderPageHeader.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/ProviderPageHeader.tsx
index 4e3abaebe6..fda56087f8 100644
--- a/src/app/(dashboard)/dashboard/providers/[id]/components/ProviderPageHeader.tsx
+++ b/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>
diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx
index 049797e4df..ec0f1fcdf7 100644
--- a/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx
+++ b/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"
diff --git a/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx b/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx
index 5eecba769e..7f7fcc0ac9 100644
--- a/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx
+++ b/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"
diff --git a/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx b/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx
index 9a9256b9e7..23a990abf5 100644
--- a/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx
+++ b/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}
diff --git a/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts b/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts
index 85315a54a1..f1ea2cc66f 100644
--- a/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts
+++ b/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,
     });
   }
 
diff --git a/src/app/api/provider-nodes/[id]/route.ts b/src/app/api/provider-nodes/[id]/route.ts
index 8512a94e19..eef4803372 100644
--- a/src/app/api/provider-nodes/[id]/route.ts
+++ b/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,
     };
 
diff --git a/src/app/api/provider-nodes/route.ts b/src/app/api/provider-nodes/route.ts
index 10871381da..87bb5330b2 100644
--- a/src/app/api/provider-nodes/route.ts
+++ b/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 });
diff --git a/src/lib/db/migrations/113_provider_node_icon_url.sql b/src/lib/db/migrations/113_provider_node_icon_url.sql
new file mode 100644
index 0000000000..51737ca8ee
--- /dev/null
+++ b/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;
diff --git a/src/lib/db/providers/nodes.ts b/src/lib/db/providers/nodes.ts
index 08bcad36f7..667f00900c 100644
--- a/src/lib/db/providers/nodes.ts
+++ b/src/lib/db/providers/nodes.ts
@@ -64,6 +64,8 @@ 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,
@@ -71,8 +73,8 @@ export async function createProviderNode(data: JsonRecord) {
 
   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"],
   });
diff --git a/src/lib/providers/catalog.ts b/src/lib/providers/catalog.ts
index 7454acc564..1c9d5e4621 100644
--- a/src/lib/providers/catalog.ts
+++ b/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",
diff --git a/src/shared/components/ProviderIcon.tsx b/src/shared/components/ProviderIcon.tsx
index e3d8486a7d..c12fb7ec7c 100644
--- a/src/shared/components/ProviderIcon.tsx
+++ b/src/shared/components/ProviderIcon.tsx
@@ -4,6 +4,10 @@
  * ProviderIcon — Renders a provider logo using @lobehub/icons with static asset fallbacks.
  *
  * Strategy (#529):
+ * 0. If `src` is set (operator-supplied remote icon URL, #2166), render it — this always
+ *    wins over the @lobehub/static resolution below. On load error, falls back to
+ *    `fallbackText`/`fallbackColor` (a colored text badge) if provided, otherwise falls
+ *    through to steps 1-4.
  * 1. Try @lobehub/icons direct icon components (no @lobehub/ui peer runtime)
  * 2. Fall back to /providers/{id}.png (existing static assets)
  * 3. Fall back to /providers/{id}.svg (SVG assets)
@@ -12,6 +16,7 @@
  * Usage:
  *   <ProviderIcon providerId="openai" size={24} />
  *   <ProviderIcon providerId="anthropic" size={28} type="color" />
+ *   <ProviderIcon providerId="openai-compatible-abc" src={node.iconUrl} fallbackText="OC" />
  */
 
 import { createElement, memo, useState } from "react";
@@ -25,6 +30,16 @@ interface ProviderIconProps {
   type?: "mono" | "color";
   className?: string;
   style?: React.CSSProperties;
+  /**
+   * Optional operator-supplied remote icon URL (#2166) — e.g. a custom icon set for an
+   * OpenAI-/Anthropic-compatible provider node. When set, this always takes priority
+   * over the @lobehub/static resolution. On load error, falls back to `fallbackText`
+   * (if provided) or the normal resolution chain below.
+   */
+  src?: string;
+  alt?: string;
+  fallbackText?: string;
+  fallbackColor?: string;
 }
 
 function GenericProviderIcon({ size }: { size: number }) {
@@ -122,6 +137,10 @@ const ProviderIcon = memo(function ProviderIcon({
   type = "color",
   className,
   style,
+  src,
+  alt,
+  fallbackText,
+  fallbackColor,
 }: ProviderIconProps) {
   const normalizedId = providerId.toLowerCase();
   const lobeIcon = getLobeProviderIcon(normalizedId, type);
@@ -129,11 +148,55 @@ const ProviderIcon = memo(function ProviderIcon({
   const hasSvg = KNOWN_SVGS.has(normalizedId);
 
   const [failedAssets, setFailedAssets] = useState<Record<string, true>>({});
+  const [remoteSrcFailed, setRemoteSrcFailed] = useState(false);
   const pngKey = `${normalizedId}:png`;
   const svgKey = `${normalizedId}:svg`;
   const usePng = !lobeIcon && hasPng && !failedAssets[pngKey];
   const useSvg = !lobeIcon && hasSvg && !failedAssets[svgKey] && (!hasPng || failedAssets[pngKey]);
 
+  const trimmedSrc = typeof src === "string" ? src.trim() : "";
+
+  // #2166: a custom remote icon URL always wins over the @lobehub/static resolution
+  // below. It is a plain <img> (not next/image) so operators can point at any host
+  // without requiring `images.remotePatterns` allow-listing for arbitrary domains.
+  if (trimmedSrc && !remoteSrcFailed) {
+    return (
+      <span className={className} style={{ display: "inline-flex", alignItems: "center", ...style }}>
+        {/* eslint-disable-next-line @next/next/no-img-element -- operator-supplied remote URL, not a static/known asset */}
+        <img
+          src={trimmedSrc}
+          alt={alt || providerId}
+          width={size}
+          height={size}
+          style={{ objectFit: "contain", flex: "none" }}
+          onError={() => setRemoteSrcFailed(true)}
+        />
+      </span>
+    );
+  }
+
+  if (trimmedSrc && remoteSrcFailed && fallbackText) {
+    return (
+      <span
+        className={className}
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          width: size,
+          height: size,
+          fontSize: Math.max(10, Math.round(size * 0.4)),
+          fontWeight: 700,
+          lineHeight: 1,
+          color: fallbackColor || "currentColor",
+          ...style,
+        }}
+      >
+        {fallbackText}
+      </span>
+    );
+  }
+
   if (lobeIcon) {
     return (
       <span
diff --git a/src/shared/validation/schemas/provider.ts b/src/shared/validation/schemas/provider.ts
index 3f8f06bd48..f57bb8124b 100644
--- a/src/shared/validation/schemas/provider.ts
+++ b/src/shared/validation/schemas/provider.ts
@@ -25,6 +25,22 @@ export { validateProviderSpecificData };
 
 // ──── Provider Schemas ────
 
+// #2166: shared optional remote icon URL for compatible provider nodes. Empty string
+// is accepted as "no custom icon" (clears any previously stored value). Restricted to
+// http(s) — `.url()` alone also accepts syntactically-valid-but-unsafe schemes like
+// `javascript:`/`data:`, which we never want persisted as an <img src>.
+const providerNodeIconUrlSchema = z
+  .string()
+  .trim()
+  .max(2000)
+  .refine((value) => value === "" || z.string().url().safeParse(value).success, {
+    message: "Icon URL must be a valid URL",
+  })
+  .refine((value) => value === "" || /^https?:\/\//i.test(value), {
+    message: "Icon URL must be a valid http:// or https:// URL",
+  })
+  .optional();
+
 export const createProviderSchema = z
   .object({
     provider: z.string().min(1).max(100),
@@ -207,6 +223,11 @@ export const createProviderNodeSchema = z
     compatMode: z.enum(["cc"]).optional(),
     chatPath: z.string().trim().startsWith("/").max(500).optional().or(z.literal("")),
     modelsPath: z.string().trim().startsWith("/").max(500).optional().or(z.literal("")),
+    // #2166: optional operator-supplied remote icon URL for the provider node. Empty
+    // string is accepted so callers can explicitly submit "no custom icon" (falls back
+    // to the built-in @lobehub/static resolution). Restricted to http(s) — `.url()` alone
+    // also accepts syntactically-valid-but-unsafe schemes like `javascript:`/`data:`.
+    iconUrl: providerNodeIconUrlSchema,
     customHeaders: customHeadersSchema,
   })
   .superRefine((value, ctx) => {
@@ -236,6 +257,9 @@ export const updateProviderNodeSchema = z.object({
   baseUrl: z.string().trim().min(1, "Base URL is required"),
   chatPath: z.string().trim().startsWith("/").max(500).optional().or(z.literal("")),
   modelsPath: z.string().trim().startsWith("/").max(500).optional().or(z.literal("")),
+  // #2166: same optional remote icon URL as createProviderNodeSchema — empty string
+  // clears a previously stored custom icon.
+  iconUrl: providerNodeIconUrlSchema,
   customHeaders: customHeadersSchema,
 });
 
diff --git a/tests/unit/provider-node-icon-url.test.ts b/tests/unit/provider-node-icon-url.test.ts
new file mode 100644
index 0000000000..541781708d
--- /dev/null
+++ b/tests/unit/provider-node-icon-url.test.ts
@@ -0,0 +1,280 @@
+// #2166 — custom remote icon URL for OpenAI-/Anthropic-compatible provider nodes.
+// Mirrors the structure of tests/unit/custom-headers-provider-nodes.test.ts.
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-icon-url-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+
+const core = await import("../../src/lib/db/core.ts");
+const providersDb = await import("../../src/lib/db/providers.ts");
+const providerNodesRoute = await import("../../src/app/api/provider-nodes/route.ts");
+const providerNodesIdRoute = await import("../../src/app/api/provider-nodes/[id]/route.ts");
+const { OPENAI_COMPATIBLE_PREFIX } = await import("../../src/shared/constants/providers.ts");
+const { createProviderNodeSchema, updateProviderNodeSchema } =
+  await import("../../src/shared/validation/schemas.ts");
+
+async function resetStorage() {
+  core.resetDbInstance();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+function makeRequest(body: Record<string, unknown>) {
+  return new Request("http://localhost/api/provider-nodes", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+function makeUpdateRequest(id: string, body: Record<string, unknown>) {
+  return new Request(`http://localhost/api/provider-nodes/${id}`, {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+test.beforeEach(async () => {
+  await resetStorage();
+});
+
+test.after(async () => {
+  await resetStorage();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+});
+
+test("createProviderNodeSchema accepts a valid iconUrl", () => {
+  const result = createProviderNodeSchema.safeParse({
+    name: "Test",
+    prefix: "test",
+    apiType: "chat",
+    iconUrl: "https://example.com/logo.png",
+  });
+  assert.equal(result.success, true);
+});
+
+test("createProviderNodeSchema accepts an empty iconUrl (no custom icon)", () => {
+  const result = createProviderNodeSchema.safeParse({
+    name: "Test",
+    prefix: "test",
+    apiType: "chat",
+    iconUrl: "",
+  });
+  assert.equal(result.success, true);
+});
+
+test("createProviderNodeSchema accepts a missing iconUrl", () => {
+  const result = createProviderNodeSchema.safeParse({
+    name: "Test",
+    prefix: "test",
+    apiType: "chat",
+  });
+  assert.equal(result.success, true);
+});
+
+test("createProviderNodeSchema rejects a non-URL or non-http(s) iconUrl", () => {
+  // "   " is intentionally NOT in this list — it trims to "" (no custom icon),
+  // matching the chatPath/modelsPath convention for optional path-like fields.
+  const invalidInputs = ["not-a-url", "javascript:alert(1)", "data:text/html,evil", "ftp://broken"];
+  for (const iconUrl of invalidInputs) {
+    const result = createProviderNodeSchema.safeParse({
+      name: "Test",
+      prefix: "test",
+      apiType: "chat",
+      iconUrl,
+    });
+    assert.equal(result.success, false, `Should reject: ${JSON.stringify(iconUrl)}`);
+  }
+});
+
+test("updateProviderNodeSchema accepts a valid iconUrl", () => {
+  const result = updateProviderNodeSchema.safeParse({
+    name: "Test",
+    prefix: "test",
+    baseUrl: "https://test.com",
+    iconUrl: "https://example.com/logo.png",
+  });
+  assert.equal(result.success, true);
+});
+
+test("updateProviderNodeSchema rejects a non-URL iconUrl", () => {
+  const result = updateProviderNodeSchema.safeParse({
+    name: "Test",
+    prefix: "test",
+    baseUrl: "https://test.com",
+    iconUrl: "not-a-url",
+  });
+  assert.equal(result.success, false);
+});
+
+test("provider nodes route creates an OpenAI-compatible node with iconUrl", async () => {
+  const response = await providerNodesRoute.POST(
+    makeRequest({
+      name: "Icon URL Node",
+      prefix: "icon-url",
+      apiType: "chat",
+      baseUrl: "https://custom.example.com/v1",
+      iconUrl: "https://cdn.example.com/icons/custom.png",
+    })
+  );
+  const body = (await response.json()) as any;
+
+  assert.equal(response.status, 201);
+  assert.match(body.node.id, new RegExp(`^${OPENAI_COMPATIBLE_PREFIX}chat-`));
+  assert.equal(body.node.iconUrl, "https://cdn.example.com/icons/custom.png");
+});
+
+test("provider nodes route creates nodes without iconUrl (null)", async () => {
+  const response = await providerNodesRoute.POST(
+    makeRequest({
+      name: "No Icon Node",
+      prefix: "no-icon",
+      apiType: "chat",
+      baseUrl: "https://noicon.example.com/v1",
+    })
+  );
+  const body = (await response.json()) as any;
+
+  assert.equal(response.status, 201);
+  assert.equal(body.node.iconUrl, null);
+});
+
+test("provider nodes route update modifies iconUrl", async () => {
+  const createResponse = await providerNodesRoute.POST(
+    makeRequest({
+      name: "Original Node",
+      prefix: "original-icon",
+      apiType: "chat",
+      baseUrl: "https://original.example.com/v1",
+    })
+  );
+  const created = (await createResponse.json()) as any;
+  const nodeId = created.node.id;
+  assert.equal(created.node.iconUrl, null);
+
+  const updateResponse = await providerNodesIdRoute.PUT(
+    makeUpdateRequest(nodeId, {
+      name: "Updated Node",
+      prefix: "updated-icon",
+      apiType: "chat",
+      baseUrl: "https://updated.example.com/v1",
+      iconUrl: "https://cdn.example.com/icons/updated.png",
+    }),
+    { params: Promise.resolve({ id: nodeId }) }
+  );
+  const updated = (await updateResponse.json()) as any;
+
+  assert.equal(updateResponse.status, 200);
+  assert.equal(updated.node.iconUrl, "https://cdn.example.com/icons/updated.png");
+});
+
+test("provider nodes route update can clear iconUrl by passing an empty string", async () => {
+  const createResponse = await providerNodesRoute.POST(
+    makeRequest({
+      name: "Node With Icon",
+      prefix: "with-icon",
+      apiType: "chat",
+      baseUrl: "https://withicon.example.com/v1",
+      iconUrl: "https://cdn.example.com/icons/keep.png",
+    })
+  );
+  const created = (await createResponse.json()) as any;
+  const nodeId = created.node.id;
+  assert.equal(created.node.iconUrl, "https://cdn.example.com/icons/keep.png");
+
+  const updateResponse = await providerNodesIdRoute.PUT(
+    makeUpdateRequest(nodeId, {
+      name: "Node Without Icon",
+      prefix: "no-clear",
+      apiType: "chat",
+      baseUrl: "https://noclear.example.com/v1",
+      iconUrl: "",
+    }),
+    { params: Promise.resolve({ id: nodeId }) }
+  );
+  const updated = (await updateResponse.json()) as any;
+
+  assert.equal(updateResponse.status, 200);
+  assert.equal(updated.node.iconUrl, null);
+});
+
+test("db: createProviderNode and getProviderNodeById round-trip iconUrl", async () => {
+  const node = await providersDb.createProviderNode({
+    id: "openai-compatible-chat-icon-url-db",
+    type: "openai-compatible",
+    name: "DB Icon URL Test",
+    prefix: "db-icon",
+    apiType: "chat",
+    baseUrl: "https://db.example.com/v1",
+    iconUrl: "https://cdn.example.com/icons/db.png",
+  });
+
+  assert.equal(node.iconUrl, "https://cdn.example.com/icons/db.png");
+
+  const retrieved = await providersDb.getProviderNodeById("openai-compatible-chat-icon-url-db");
+  assert.equal(retrieved.iconUrl, "https://cdn.example.com/icons/db.png");
+});
+
+test("db: createProviderNode without iconUrl stores null", async () => {
+  const node = await providersDb.createProviderNode({
+    id: "openai-compatible-chat-no-icon-db",
+    type: "openai-compatible",
+    name: "DB No Icon Test",
+    prefix: "db-no-icon",
+    apiType: "chat",
+    baseUrl: "https://db-no-icon.example.com/v1",
+  });
+
+  assert.equal(node.iconUrl, null);
+});
+
+test("db: updateProviderNode modifies iconUrl", async () => {
+  const node = await providersDb.createProviderNode({
+    id: "openai-compatible-chat-update-icon",
+    type: "openai-compatible",
+    name: "Update Icon Test",
+    prefix: "update-icon",
+    apiType: "chat",
+    baseUrl: "https://update-icon.example.com/v1",
+    iconUrl: "https://cdn.example.com/icons/initial.png",
+  });
+
+  assert.equal(node.iconUrl, "https://cdn.example.com/icons/initial.png");
+
+  const updated = await providersDb.updateProviderNode("openai-compatible-chat-update-icon", {
+    iconUrl: "https://cdn.example.com/icons/updated.png",
+  });
+
+  assert.equal(updated.iconUrl, "https://cdn.example.com/icons/updated.png");
+
+  const retrieved = await providersDb.getProviderNodeById("openai-compatible-chat-update-icon");
+  assert.equal(retrieved.iconUrl, "https://cdn.example.com/icons/updated.png");
+});
+
+test("db: updateProviderNode can clear iconUrl by passing null", async () => {
+  const node = await providersDb.createProviderNode({
+    id: "openai-compatible-chat-clear-icon",
+    type: "openai-compatible",
+    name: "Clear Icon Test",
+    prefix: "clear-icon",
+    apiType: "chat",
+    baseUrl: "https://clear-icon.example.com/v1",
+    iconUrl: "https://cdn.example.com/icons/clear-me.png",
+  });
+
+  assert.equal(node.iconUrl, "https://cdn.example.com/icons/clear-me.png");
+
+  const updated = await providersDb.updateProviderNode("openai-compatible-chat-clear-icon", {
+    iconUrl: null,
+  });
+
+  assert.equal(updated.iconUrl, null);
+
+  const retrieved = await providersDb.getProviderNodeById("openai-compatible-chat-clear-icon");
+  assert.equal(retrieved.iconUrl, null);
+});
diff --git a/tests/unit/providers-page-utils.test.ts b/tests/unit/providers-page-utils.test.ts
index 620e7610a8..17f30b9038 100644
--- a/tests/unit/providers-page-utils.test.ts
+++ b/tests/unit/providers-page-utils.test.ts
@@ -748,6 +748,7 @@ test("compatible catalog entries keep dynamic compatible metadata", () => {
         type: "openai-compatible",
         apiType: "responses",
         baseUrl: "https://example.test",
+        iconUrl: "https://cdn.example.com/icons/lab.png",
       },
       compatibleLabels: {
         ccCompatibleName: "CC Compatible",
@@ -762,6 +763,8 @@ test("compatible catalog entries keep dynamic compatible metadata", () => {
   assert.equal(compatibleProvider?.toggleAuthType, "apikey");
   assert.equal(compatibleProvider?.apiType, "responses");
   assert.equal(compatibleProvider?.baseUrl, "https://example.test");
+  // #2166: custom remote icon URL passthrough.
+  assert.equal(compatibleProvider?.iconUrl, "https://cdn.example.com/icons/lab.png");
 });
 
 test("model search filter matches providers by model id", async () => {
@@ -1015,7 +1018,13 @@ test("buildCompatibleProviderGroups partitions nodes by type + claude-code prefi
 
   const groups = providerPageUtils.buildCompatibleProviderGroups(
     [
-      { id: "my-oai", name: "My OAI", type: "openai-compatible", apiType: "responses" },
+      {
+        id: "my-oai",
+        name: "My OAI",
+        type: "openai-compatible",
+        apiType: "responses",
+        iconUrl: "https://cdn.example.com/icons/my-oai.png",
+      },
       { id: "my-anthropic", name: "My Claude", type: "anthropic-compatible" },
       { id: "anthropic-compatible-cc-acme", name: "Acme CC", type: "anthropic-compatible" },
       { id: "ignored-node", name: "Ignored", type: "unsupported-provider" },
@@ -1037,6 +1046,14 @@ test("buildCompatibleProviderGroups partitions nodes by type + claude-code prefi
     "missing name falls back to the openai-compatible label"
   );
 
+  // #2166: custom remote icon URL passthrough.
+  assert.equal(
+    groups.openai[0].iconUrl,
+    "https://cdn.example.com/icons/my-oai.png",
+    "iconUrl is preserved for nodes that set it"
+  );
+  assert.equal(groups.openai[1].iconUrl, undefined, "iconUrl is undefined when the node has none");
+
   assert.deepEqual(
     groups.anthropic.map((p) => p.id),
     ["my-anthropic"],
diff --git a/tests/unit/ui/ProviderIcon-icon-url.test.tsx b/tests/unit/ui/ProviderIcon-icon-url.test.tsx
new file mode 100644
index 0000000000..19977c1455
--- /dev/null
+++ b/tests/unit/ui/ProviderIcon-icon-url.test.tsx
@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+// #2166 — ProviderIcon custom remote icon URL (`src` prop) support.
+import React from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+
+vi.mock("next/image", () => ({
+  default: (props: Record<string, unknown>) => {
+    const { onError, alt, ...rest } = props as { onError?: () => void; alt?: string } & Record<
+      string,
+      unknown
+    >;
+    // eslint-disable-next-line @next/next/no-img-element -- test double for next/image
+    return <img data-testid="next-image" alt={alt || ""} onError={onError} {...rest} />;
+  },
+}));
+
+const { default: ProviderIcon } = await import("@/shared/components/ProviderIcon");
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+// Deliberately not registered in @lobehub/icons aliases or the KNOWN_PNGS/KNOWN_SVGS
+// static-asset sets, so tests exercise only the `src` override + generic-icon fallback
+// paths, never the @lobehub/static resolution chain.
+const UNKNOWN_PROVIDER_ID = "openai-compatible-test-node-xyz";
+
+const containers: HTMLElement[] = [];
+
+function renderIcon(props: Record<string, unknown>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const root = createRoot(container);
+  act(() => {
+    root.render(<ProviderIcon providerId={UNKNOWN_PROVIDER_ID} {...props} />);
+  });
+  return container;
+}
+
+function fireImgError(container: HTMLElement) {
+  const img = container.querySelector("img");
+  if (!img) throw new Error("expected an <img> element to fire error on");
+  act(() => {
+    img.dispatchEvent(new Event("error"));
+  });
+}
+
+beforeEach(() => {
+  (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+    true;
+});
+
+afterEach(() => {
+  while (containers.length > 0) {
+    containers.pop()?.remove();
+  }
+  document.body.innerHTML = "";
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("ProviderIcon — custom remote icon URL (#2166)", () => {
+  it("renders an <img> with the given src when `src` is set", () => {
+    const container = renderIcon({ src: "https://example.com/logo.png", size: 32 });
+    const img = container.querySelector("img");
+    expect(img).not.toBeNull();
+    expect(img?.getAttribute("src")).toBe("https://example.com/logo.png");
+  });
+
+  it("falls back to the generic icon when `src` is unset", () => {
+    const container = renderIcon({});
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("falls back to the generic (lobehub/static) icon chain when `src` load fails and no fallbackText is given", () => {
+    const container = renderIcon({ src: "https://example.com/broken.png" });
+    expect(container.querySelector("img")).not.toBeNull();
+
+    fireImgError(container);
+
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("falls back to a text badge when `src` load fails and fallbackText is given", () => {
+    const container = renderIcon({
+      src: "https://example.com/broken.png",
+      fallbackText: "OC",
+      fallbackColor: "#10A37F",
+    });
+    expect(container.querySelector("img")).not.toBeNull();
+
+    fireImgError(container);
+
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("svg")).toBeNull();
+    expect(container.textContent).toBe("OC");
+  });
+
+  it("ignores a whitespace-only src and falls back to the generic icon", () => {
+    const container = renderIcon({ src: "   " });
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+});