Hugging Face (Inferenz)

OpenClaw erkennt Modelle, indem der Inference-Endpunkt direkt aufgerufen wird:

GET https://router.huggingface.co/v1/models

(Optional: senden Sie Authorization: Bearer $HUGGINGFACE_HUB_TOKEN oder $HF_TOKEN für die vollständige Liste; einige Endpunkte geben ohne Auth nur eine Teilmenge zurück.) Die Antwort entspricht dem OpenAI-Stil: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

Wenn Sie einen Hugging-Face-API-Schlüssel konfigurieren (über Onboarding, HUGGINGFACE_HUB_TOKEN oder HF_TOKEN), verwendet OpenClaw dieses GET, um verfügbare Chat-Completion-Modelle zu erkennen. Während des interaktiven Setups sehen Sie nach Eingabe Ihres Tokens ein Dropdown Default Hugging Face model, das aus dieser Liste befüllt wird (oder aus dem integrierten Katalog, wenn die Anfrage fehlschlägt). Zur Laufzeit (z. B. beim Gateway-Start) ruft OpenClaw, wenn ein Schlüssel vorhanden ist, erneut GET https://router.huggingface.co/v1/models auf, um den Katalog zu aktualisieren. Die Liste wird mit einem integrierten Katalog zusammengeführt (für Metadaten wie Kontextfenster und Kosten). Wenn die Anfrage fehlschlägt oder kein Schlüssel gesetzt ist, wird nur der integrierte Katalog verwendet.

• Name aus der API: Der Anzeigename des Modells wird aus GET /v1/models abgeleitet, wenn die API name, title oder display_name zurückgibt; andernfalls wird er aus der Modell-ID abgeleitet (z. B. wird deepseek-ai/DeepSeek-R1 zu „DeepSeek R1“).
• Anzeigenamen überschreiben: Sie können pro Modell ein benutzerdefiniertes Label in der Konfiguration setzen, sodass es in CLI und UI so erscheint, wie Sie es möchten:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (schnell)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (günstig)" },
      },
    },
  },
}

• Richtlinien-Suffixe: Die gebündelten Hugging-Face-Dokumente und -Helfer in OpenClaw behandeln derzeit diese beiden Suffixe als integrierte Richtlinienvarianten:

  • :fastest — höchster Durchsatz.
  • :cheapest — niedrigste Kosten pro Ausgabetoken.

  Sie können diese als separate Einträge in models.providers.huggingface.models hinzufügen oder model.primary mit dem Suffix setzen. Sie können Ihre Standardreihenfolge für Provider auch in den Inference Provider settings festlegen (ohne Suffix = diese Reihenfolge verwenden).

• Zusammenführung der Konfiguration: Bestehende Einträge in models.providers.huggingface.models (z. B. in models.json) bleiben beim Zusammenführen der Konfiguration erhalten. Daher bleiben benutzerdefinierte Werte für name, alias oder Modelloptionen, die Sie dort setzen, erhalten.

Wenn das Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass HUGGINGFACE_HUB_TOKEN oder HF_TOKEN für diesen Prozess verfügbar ist (zum Beispiel in ~/.openclaw/.env oder über env.shellEnv).

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/Qwen/Qwen3-8B"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen3-8B" },
      models: {
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
        "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (am günstigsten)" },
        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (am schnellsten)" },
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
        fallbacks: [
          "huggingface/meta-llama/Llama-3.3-70B-Instruct",
          "huggingface/openai/gpt-oss-120b",
        ],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
        "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
      models: {
        "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
        "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (günstig)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (schnell)" },
        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
      },
    },
  },
}