OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

Hugging Face (Inferenz)

Hugging Face Inference Providers stellt einen OpenAI-kompatiblen Router für Chat Completions bereit, der mit einem einzigen Token den Zugriff auf zahlreiche gehostete Modelle (DeepSeek, Llama und weitere) ermöglicht. OpenClaw kommuniziert ausschließlich mit dem Chat-Completions-Endpunkt; für Text-zu-Bild, Embeddings oder Sprache verwenden Sie direkt die HF-Inferenzclients.

Eigenschaft Wert
Provider-ID huggingface
Plugin gebündelt (standardmäßig aktiviert, kein Installationsschritt)
Authentifizierungs-Umgebungsvariable HUGGINGFACE_HUB_TOKEN oder HF_TOKEN (feingranulares Token)
API OpenAI-kompatibel (https://router.huggingface.co/v1)
Abrechnung Ein einziges HF-Token; die Preisgestaltung richtet sich nach den Provider-Tarifen und umfasst ein kostenloses Kontingent

Erste Schritte

  • Ein feingranulares Token erstellen

    Rufen Sie Hugging Face Settings Tokens auf und erstellen Sie ein neues feingranulares Token.

  • Onboarding ausführen

    Wählen Sie im Provider-Dropdown Hugging Face aus und geben Sie anschließend bei Aufforderung Ihren API-Schlüssel ein:

    bash
    openclaw onboard --auth-choice huggingface-api-key

  • Ein Standardmodell auswählen

    Wählen Sie im Dropdown Default Hugging Face model ein Modell aus. Bei einem gültigen Token wird die Liste aus der Inference API geladen; andernfalls zeigt OpenClaw den unten aufgeführten integrierten Katalog an. Ihre Auswahl wird als agents.defaults.model.primary gespeichert:

    json5
    {  agents: {    defaults: {      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },    },  },}

  • Verfügbarkeit des Modells überprüfen

    bash
    openclaw models list --provider huggingface

    • Nicht interaktive Einrichtung

    bash
    openclaw onboard --non-interactive \  --mode local \  --auth-choice huggingface-api-key \  --huggingface-api-key "$HF_TOKEN"

    Legt huggingface/deepseek-ai/DeepSeek-R1 als Standardmodell fest.

    Modell-IDs

    Modellreferenzen verwenden die Form huggingface/<org>/<model> (IDs im Hub-Stil). Der integrierte Katalog von OpenClaw:

    Modell Referenz (Präfix huggingface/)
    DeepSeek R1 deepseek-ai/DeepSeek-R1
    DeepSeek V3.1 deepseek-ai/DeepSeek-V3.1
    GPT-OSS 120B openai/gpt-oss-120b

    Erweiterte Konfiguration

    Modellerkennung und Onboarding-Dropdown

    OpenClaw erkennt Modelle mit:

    bash
    GET https://router.huggingface.co/v1/modelsAuthorization: Bearer $HUGGINGFACE_HUB_TOKEN   # oder $HF_TOKEN

    Die Antwort entspricht dem OpenAI-Stil: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

    Mit einem konfigurierten Schlüssel (Onboarding, HUGGINGFACE_HUB_TOKEN oder HF_TOKEN) wird das Dropdown Default Hugging Face model während der interaktiven Einrichtung über diesen Endpunkt befüllt. Beim Start des Gateway wird derselbe Aufruf wiederholt, um den Katalog zu aktualisieren. Erkannte Modelle werden mit dem oben aufgeführten integrierten Katalog zusammengeführt, der bei übereinstimmender ID für Metadaten wie Kontextfenster und Kosten verwendet wird. Wenn die Anfrage fehlschlägt, keine Daten zurückgibt oder kein Schlüssel festgelegt ist, verwendet OpenClaw ausschließlich den integrierten Katalog.

    So deaktivieren Sie die Erkennung, ohne den Provider zu entfernen:

    bash
    openclaw config set plugins.entries.huggingface.config.discovery.enabled false
    Modellnamen, Aliasse und Richtliniensuffixe
    • Name aus der API: Erkannte Modelle verwenden, sofern vorhanden, name, title oder display_name aus der API; andernfalls leitet OpenClaw aus der Modell-ID einen Namen ab (beispielsweise wird deepseek-ai/DeepSeek-R1 zu „DeepSeek R1“).
    • Anzeigenamen überschreiben: Legen Sie in der Konfiguration für jedes Modell eine benutzerdefinierte Bezeichnung fest:
    json5
    {  agents: {    defaults: {      models: {        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },      },    },  },}
    • Richtliniensuffixe: :fastest und :cheapest sind Konventionen des HF-Routers und werden nicht von OpenClaw umgeschrieben: Das Suffix wird unverändert als Teil der Modell-ID gesendet, und der HF-Router wählt den entsprechenden Inferenz-Provider aus. Fügen Sie jede Variante als eigenen Eintrag unter models.providers.huggingface.models (oder in model.primary) hinzu, wenn Sie für jedes Suffix einen eigenen Alias verwenden möchten.
    • Zusammenführung der Konfiguration: Vorhandene Einträge in models.providers.huggingface.models (beispielsweise in models.json) bleiben bei der Zusammenführung der Konfiguration erhalten. Dadurch bleiben alle benutzerdefinierten name, alias oder Modelloptionen, die Sie dort festlegen, über Neustarts hinweg erhalten.
    Umgebungs- und Daemon-Einrichtung

    Wenn das Gateway als Daemon (launchd/systemd) ausgeführt wird, stellen Sie sicher, dass HUGGINGFACE_HUB_TOKEN oder HF_TOKEN für diesen Prozess verfügbar ist (beispielsweise in ~/.openclaw/.env oder über env.shellEnv).

    Konfiguration: DeepSeek R1 mit Fallback
    json5
    {  agents: {    defaults: {      model: {        primary: "huggingface/deepseek-ai/DeepSeek-R1",        fallbacks: ["huggingface/openai/gpt-oss-120b"],      },      models: {        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },      },    },  },}
    Konfiguration: DeepSeek mit den günstigsten und schnellsten Varianten
    json5
    {  agents: {    defaults: {      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },      models: {        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" },        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" },      },    },  },}
    Konfiguration: DeepSeek + GPT-OSS mit Aliassen
    json5
    {  agents: {    defaults: {      model: {        primary: "huggingface/deepseek-ai/DeepSeek-V3.1",        fallbacks: ["huggingface/openai/gpt-oss-120b"],      },      models: {        "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },      },    },  },}

    Verwandte Themen

    Modellauswahl

    Übersicht über alle Provider, Modellreferenzen und das Failover-Verhalten.
    Modellauswahl

    So wählen und konfigurieren Sie Modelle.
    Dokumentation zu Inference Providers

    Offizielle Dokumentation zu Hugging Face Inference Providers.
    Konfiguration

    Vollständige Konfigurationsreferenz.
    Was this useful?
    On this page

    On this page