重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。

同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。

Made-with: Cursor

openclaw/extensions/huggingface/api.ts

@@ -0,0 +1,10 @@
+export {
+  buildHuggingfaceModelDefinition,
+  discoverHuggingfaceModels,
+  HUGGINGFACE_BASE_URL,
+  HUGGINGFACE_MODEL_CATALOG,
+  HUGGINGFACE_POLICY_SUFFIXES,
+  isHuggingfacePolicyLocked,
+} from "./models.js";
+export { buildHuggingfaceProvider } from "./provider-catalog.js";
+export { applyHuggingfaceConfig, HUGGINGFACE_DEFAULT_MODEL_REF } from "./onboard.js";

openclaw/extensions/huggingface/index.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import { createTestPluginApi } from "../../test/helpers/plugins/plugin-api.js";
+
+const buildHuggingfaceProviderMock = vi.hoisted(() =>
+  vi.fn(async () => ({
+    baseUrl: "https://router.huggingface.co/v1",
+    api: "openai-completions",
+    models: [],
+  })),
+);
+
+vi.mock("./provider-catalog.js", () => ({
+  buildHuggingfaceProvider: buildHuggingfaceProviderMock,
+}));
+
+vi.mock("./onboard.js", () => ({
+  applyHuggingfaceConfig: vi.fn((cfg) => cfg),
+  HUGGINGFACE_DEFAULT_MODEL_REF: "huggingface/deepseek-ai/DeepSeek-R1",
+}));
+
+import plugin from "./index.js";
+
+function registerProvider() {
+  return registerProviderWithPluginConfig({});
+}
+
+function registerProviderWithPluginConfig(pluginConfig: Record<string, unknown>) {
+  const registerProviderMock = vi.fn();
+
+  plugin.register(
+    createTestPluginApi({
+      id: "huggingface",
+      name: "Hugging Face",
+      source: "test",
+      config: {},
+      pluginConfig,
+      runtime: {} as never,
+      registerProvider: registerProviderMock,
+    }),
+  );
+
+  expect(registerProviderMock).toHaveBeenCalledTimes(1);
+  return registerProviderMock.mock.calls[0]?.[0];
+}
+
+describe("huggingface plugin", () => {
+  it("skips catalog discovery when plugin discovery is disabled", async () => {
+    const provider = registerProvider();
+
+    const result = await provider.catalog.run({
+      config: {
+        plugins: {
+          entries: {
+            huggingface: {
+              config: {
+                discovery: { enabled: false },
+              },
+            },
+          },
+        },
+      },
+      resolveProviderApiKey: () => ({
+        apiKey: "hf_test_token",
+        discoveryApiKey: "hf_test_token",
+      }),
+    } as never);
+
+    expect(result).toBeNull();
+    expect(buildHuggingfaceProviderMock).not.toHaveBeenCalled();
+  });
+});

openclaw/extensions/huggingface/index.ts

@@ -0,0 +1,60 @@
+import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
+import { applyHuggingfaceConfig, HUGGINGFACE_DEFAULT_MODEL_REF } from "./onboard.js";
+import { buildHuggingfaceProvider } from "./provider-catalog.js";
+
+const PROVIDER_ID = "huggingface";
+
+type HuggingFacePluginConfig = {
+  discovery?: {
+    enabled?: boolean;
+  };
+};
+
+export default defineSingleProviderPluginEntry({
+  id: PROVIDER_ID,
+  name: "Hugging Face Provider",
+  description: "Bundled Hugging Face provider plugin",
+  provider: {
+    label: "Hugging Face",
+    docsPath: "/providers/huggingface",
+    envVars: ["HUGGINGFACE_HUB_TOKEN", "HF_TOKEN"],
+    auth: [
+      {
+        methodId: "api-key",
+        label: "Hugging Face API key",
+        hint: "Inference API (HF token)",
+        optionKey: "huggingfaceApiKey",
+        flagName: "--huggingface-api-key",
+        envVar: "HUGGINGFACE_HUB_TOKEN",
+        promptMessage: "Enter Hugging Face API key",
+        defaultModel: HUGGINGFACE_DEFAULT_MODEL_REF,
+        applyConfig: (cfg) => applyHuggingfaceConfig(cfg),
+      },
+    ],
+    catalog: {
+      order: "simple",
+      run: async (ctx) => {
+        const pluginEntry = ctx.config?.plugins?.entries?.[PROVIDER_ID];
+        const pluginConfig =
+          pluginEntry && typeof pluginEntry === "object" && pluginEntry.config
+            ? (pluginEntry.config as HuggingFacePluginConfig)
+            : undefined;
+        const discoveryEnabled =
+          pluginConfig?.discovery?.enabled ?? ctx.config?.models?.huggingfaceDiscovery?.enabled;
+        if (discoveryEnabled === false) {
+          return null;
+        }
+        const { apiKey, discoveryApiKey } = ctx.resolveProviderApiKey(PROVIDER_ID);
+        if (!apiKey) {
+          return null;
+        }
+        return {
+          provider: {
+            ...(await buildHuggingfaceProvider(discoveryApiKey)),
+            apiKey,
+          },
+        };
+      },
+    },
+  },
+});

openclaw/extensions/huggingface/models.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  buildHuggingfaceModelDefinition,
+  discoverHuggingfaceModels,
+  HUGGINGFACE_MODEL_CATALOG,
+  isHuggingfacePolicyLocked,
+} from "./api.js";
+import { HUGGINGFACE_DISCOVERY_TIMEOUT_MS } from "./models.js";
+
+const ORIGINAL_VITEST = process.env.VITEST;
+const ORIGINAL_NODE_ENV = process.env.NODE_ENV;
+
+afterEach(() => {
+  process.env.VITEST = ORIGINAL_VITEST;
+  process.env.NODE_ENV = ORIGINAL_NODE_ENV;
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("huggingface models", () => {
+  it("buildHuggingfaceModelDefinition returns config with required fields", () => {
+    const entry = HUGGINGFACE_MODEL_CATALOG[0];
+    const def = buildHuggingfaceModelDefinition(entry);
+    expect(def.id).toBe(entry.id);
+    expect(def.name).toBe(entry.name);
+    expect(def.reasoning).toBe(entry.reasoning);
+    expect(def.input).toEqual(entry.input);
+    expect(def.cost).toEqual(entry.cost);
+    expect(def.contextWindow).toBe(entry.contextWindow);
+    expect(def.maxTokens).toBe(entry.maxTokens);
+  });
+
+  it("discoverHuggingfaceModels returns static catalog when apiKey is empty", async () => {
+    const models = await discoverHuggingfaceModels("");
+    expect(models).toHaveLength(HUGGINGFACE_MODEL_CATALOG.length);
+    expect(models.map((m) => m.id)).toEqual(HUGGINGFACE_MODEL_CATALOG.map((m) => m.id));
+  });
+
+  it("discoverHuggingfaceModels returns static catalog in test env (VITEST)", async () => {
+    const models = await discoverHuggingfaceModels("hf_test_token");
+    expect(models).toHaveLength(HUGGINGFACE_MODEL_CATALOG.length);
+    expect(models[0].id).toBe("deepseek-ai/DeepSeek-R1");
+  });
+
+  it("uses the default discovery timeout for live Hugging Face fetches", async () => {
+    process.env.VITEST = "false";
+    process.env.NODE_ENV = "development";
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response("{}", { status: 500, headers: { "Content-Type": "application/json" } }),
+      ),
+    );
+
+    await discoverHuggingfaceModels("hf_test_token");
+
+    expect(timeoutSpy).toHaveBeenCalledWith(HUGGINGFACE_DISCOVERY_TIMEOUT_MS);
+  });
+
+  it("accepts a custom discovery timeout override", async () => {
+    process.env.VITEST = "false";
+    process.env.NODE_ENV = "development";
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response("{}", { status: 500, headers: { "Content-Type": "application/json" } }),
+      ),
+    );
+
+    await discoverHuggingfaceModels("hf_test_token", 25_000);
+
+    expect(timeoutSpy).toHaveBeenCalledWith(25_000);
+  });
+
+  describe("isHuggingfacePolicyLocked", () => {
+    it("returns true for :cheapest and :fastest refs", () => {
+      expect(isHuggingfacePolicyLocked("huggingface/deepseek-ai/DeepSeek-R1:cheapest")).toBe(true);
+      expect(isHuggingfacePolicyLocked("huggingface/deepseek-ai/DeepSeek-R1:fastest")).toBe(true);
+    });
+
+    it("returns false for base ref and :provider refs", () => {
+      expect(isHuggingfacePolicyLocked("huggingface/deepseek-ai/DeepSeek-R1")).toBe(false);
+      expect(isHuggingfacePolicyLocked("huggingface/foo:together")).toBe(false);
+    });
+  });
+});

openclaw/extensions/huggingface/models.ts

@@ -0,0 +1,204 @@
+import type { ModelDefinitionConfig } from "openclaw/plugin-sdk/provider-model-types";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export const HUGGINGFACE_BASE_URL = "https://router.huggingface.co/v1";
+export const HUGGINGFACE_POLICY_SUFFIXES = ["cheapest", "fastest"] as const;
+export const HUGGINGFACE_DISCOVERY_TIMEOUT_MS = 30_000;
+
+const HUGGINGFACE_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+};
+
+const HUGGINGFACE_DEFAULT_CONTEXT_WINDOW = 131072;
+const HUGGINGFACE_DEFAULT_MAX_TOKENS = 8192;
+
+type HFModelEntry = {
+  id: string;
+  owned_by?: string;
+  name?: string;
+  title?: string;
+  display_name?: string;
+  architecture?: {
+    input_modalities?: string[];
+  };
+  providers?: Array<{
+    context_length?: number;
+  }>;
+};
+
+type OpenAIListModelsResponse = {
+  data?: HFModelEntry[];
+};
+
+export const HUGGINGFACE_MODEL_CATALOG: ModelDefinitionConfig[] = [
+  {
+    id: "deepseek-ai/DeepSeek-R1",
+    name: "DeepSeek R1",
+    reasoning: true,
+    input: ["text"],
+    contextWindow: 131072,
+    maxTokens: 8192,
+    cost: { input: 3.0, output: 7.0, cacheRead: 3.0, cacheWrite: 3.0 },
+  },
+  {
+    id: "deepseek-ai/DeepSeek-V3.1",
+    name: "DeepSeek V3.1",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 131072,
+    maxTokens: 8192,
+    cost: { input: 0.6, output: 1.25, cacheRead: 0.6, cacheWrite: 0.6 },
+  },
+  {
+    id: "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+    name: "Llama 3.3 70B Instruct Turbo",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 131072,
+    maxTokens: 8192,
+    cost: { input: 0.88, output: 0.88, cacheRead: 0.88, cacheWrite: 0.88 },
+  },
+  {
+    id: "openai/gpt-oss-120b",
+    name: "GPT-OSS 120B",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 131072,
+    maxTokens: 8192,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  },
+];
+
+export function isHuggingfacePolicyLocked(modelRef: string): boolean {
+  const ref = modelRef.trim();
+  return HUGGINGFACE_POLICY_SUFFIXES.some((suffix) => ref.endsWith(`:${suffix}`) || ref === suffix);
+}
+
+export function buildHuggingfaceModelDefinition(
+  model: (typeof HUGGINGFACE_MODEL_CATALOG)[number],
+): ModelDefinitionConfig {
+  return {
+    id: model.id,
+    name: model.name,
+    reasoning: model.reasoning,
+    input: model.input,
+    cost: model.cost,
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
+  };
+}
+
+function isReasoningModelHeuristic(modelId: string): boolean {
+  const lower = normalizeLowercaseStringOrEmpty(modelId);
+  return (
+    lower.includes("r1") ||
+    lower.includes("reason") ||
+    lower.includes("thinking") ||
+    lower.includes("reasoner") ||
+    lower.includes("grok") ||
+    lower.includes("qwq")
+  );
+}
+
+function inferredMetaFromModelId(id: string): { name: string; reasoning: boolean } {
+  const base = id.split("/").pop() ?? id;
+  const reasoning = isReasoningModelHeuristic(id);
+  const name = base.replace(/-/g, " ").replace(/\b(\w)/g, (c) => c.toUpperCase());
+  return { name, reasoning };
+}
+
+function displayNameFromApiEntry(entry: HFModelEntry, inferredName: string): string {
+  const fromApi =
+    (typeof entry.name === "string" && entry.name.trim()) ||
+    (typeof entry.title === "string" && entry.title.trim()) ||
+    (typeof entry.display_name === "string" && entry.display_name.trim());
+  if (fromApi) {
+    return fromApi;
+  }
+  if (typeof entry.owned_by === "string" && entry.owned_by.trim()) {
+    const base = entry.id.split("/").pop() ?? entry.id;
+    return `${entry.owned_by.trim()}/${base}`;
+  }
+  return inferredName;
+}
+
+export async function discoverHuggingfaceModels(
+  apiKey: string,
+  timeoutMs = HUGGINGFACE_DISCOVERY_TIMEOUT_MS,
+): Promise<ModelDefinitionConfig[]> {
+  if (process.env.VITEST === "true" || process.env.NODE_ENV === "test") {
+    return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+  }
+
+  const trimmedKey = apiKey?.trim();
+  if (!trimmedKey) {
+    return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+  }
+
+  try {
+    const response = await fetch(`${HUGGINGFACE_BASE_URL}/models`, {
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: {
+        Authorization: `Bearer ${trimmedKey}`,
+        "Content-Type": "application/json",
+      },
+    });
+    if (!response.ok) {
+      return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+    }
+
+    const body = (await response.json()) as OpenAIListModelsResponse;
+    const data = body?.data;
+    if (!Array.isArray(data) || data.length === 0) {
+      return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+    }
+
+    const catalogById = new Map(
+      HUGGINGFACE_MODEL_CATALOG.map((model) => [model.id, model] as const),
+    );
+    const seen = new Set<string>();
+    const models: ModelDefinitionConfig[] = [];
+
+    for (const entry of data) {
+      const id = typeof entry?.id === "string" ? entry.id.trim() : "";
+      if (!id || seen.has(id)) {
+        continue;
+      }
+      seen.add(id);
+
+      const catalogEntry = catalogById.get(id);
+      if (catalogEntry) {
+        models.push(buildHuggingfaceModelDefinition(catalogEntry));
+        continue;
+      }
+
+      const inferred = inferredMetaFromModelId(id);
+      const name = displayNameFromApiEntry(entry, inferred.name);
+      const modalities = entry.architecture?.input_modalities;
+      const input: Array<"text" | "image"> =
+        Array.isArray(modalities) && modalities.includes("image") ? ["text", "image"] : ["text"];
+      const providers = Array.isArray(entry.providers) ? entry.providers : [];
+      const providerWithContext = providers.find(
+        (provider) => typeof provider?.context_length === "number" && provider.context_length > 0,
+      );
+      models.push({
+        id,
+        name,
+        reasoning: inferred.reasoning,
+        input,
+        cost: HUGGINGFACE_DEFAULT_COST,
+        contextWindow: providerWithContext?.context_length ?? HUGGINGFACE_DEFAULT_CONTEXT_WINDOW,
+        maxTokens: HUGGINGFACE_DEFAULT_MAX_TOKENS,
+      });
+    }
+
+    return models.length > 0
+      ? models
+      : HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+  } catch {
+    return HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+  }
+}

openclaw/extensions/huggingface/onboard.ts

@@ -0,0 +1,30 @@
+import {
+  createModelCatalogPresetAppliers,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/provider-onboard";
+import {
+  buildHuggingfaceModelDefinition,
+  HUGGINGFACE_BASE_URL,
+  HUGGINGFACE_MODEL_CATALOG,
+} from "./models.js";
+
+export const HUGGINGFACE_DEFAULT_MODEL_REF = "huggingface/deepseek-ai/DeepSeek-R1";
+
+const huggingfacePresetAppliers = createModelCatalogPresetAppliers({
+  primaryModelRef: HUGGINGFACE_DEFAULT_MODEL_REF,
+  resolveParams: (_cfg: OpenClawConfig) => ({
+    providerId: "huggingface",
+    api: "openai-completions",
+    baseUrl: HUGGINGFACE_BASE_URL,
+    catalogModels: HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition),
+    aliases: [{ modelRef: HUGGINGFACE_DEFAULT_MODEL_REF, alias: "Hugging Face" }],
+  }),
+});
+
+export function applyHuggingfaceProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
+  return huggingfacePresetAppliers.applyProviderConfig(cfg);
+}
+
+export function applyHuggingfaceConfig(cfg: OpenClawConfig): OpenClawConfig {
+  return huggingfacePresetAppliers.applyConfig(cfg);
+}

openclaw/extensions/huggingface/openclaw.plugin.json

@@ -0,0 +1,47 @@
+{
+  "id": "huggingface",
+  "enabledByDefault": true,
+  "providers": ["huggingface"],
+  "providerAuthEnvVars": {
+    "huggingface": ["HUGGINGFACE_HUB_TOKEN", "HF_TOKEN"]
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "huggingface",
+      "method": "api-key",
+      "choiceId": "huggingface-api-key",
+      "choiceLabel": "Hugging Face API key",
+      "choiceHint": "Inference API (HF token)",
+      "groupId": "huggingface",
+      "groupLabel": "Hugging Face",
+      "groupHint": "Inference API (HF token)",
+      "optionKey": "huggingfaceApiKey",
+      "cliFlag": "--huggingface-api-key",
+      "cliOption": "--huggingface-api-key <key>",
+      "cliDescription": "Hugging Face API key (HF token)"
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "discovery": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "discovery": {
+      "label": "Model Discovery",
+      "help": "Plugin-owned controls for Hugging Face model auto-discovery."
+    },
+    "discovery.enabled": {
+      "label": "Enable Discovery",
+      "help": "When false, OpenClaw keeps the Hugging Face plugin available but skips implicit startup discovery from ambient Hugging Face credentials."
+    }
+  }
+}

openclaw/extensions/huggingface/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@openclaw/huggingface-provider",
+  "version": "2026.4.20",
+  "private": true,
+  "description": "OpenClaw Hugging Face provider plugin",
+  "type": "module",
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

openclaw/extensions/huggingface/provider-catalog.ts

@@ -0,0 +1,29 @@
+import type { ModelProviderConfig } from "openclaw/plugin-sdk/provider-model-types";
+import {
+  buildHuggingfaceModelDefinition,
+  discoverHuggingfaceModels,
+  HUGGINGFACE_BASE_URL,
+  HUGGINGFACE_MODEL_CATALOG,
+} from "./models.js";
+
+export {
+  buildHuggingfaceModelDefinition,
+  discoverHuggingfaceModels,
+  HUGGINGFACE_BASE_URL,
+  HUGGINGFACE_MODEL_CATALOG,
+} from "./models.js";
+
+export async function buildHuggingfaceProvider(
+  discoveryApiKey?: string,
+): Promise<ModelProviderConfig> {
+  const resolvedSecret = discoveryApiKey?.trim() ?? "";
+  const models =
+    resolvedSecret !== ""
+      ? await discoverHuggingfaceModels(resolvedSecret)
+      : HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+  return {
+    baseUrl: HUGGINGFACE_BASE_URL,
+    api: "openai-completions",
+    models,
+  };
+}

openclaw/extensions/huggingface/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}