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.

Für das Token muss die Berechtigung Make calls to Inference Providers aktiviert sein, andernfalls werden API-Anfragen abgelehnt.

Onboarding ausführen

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

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:

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

Verfügbarkeit des Modells überprüfen

openclaw models list --provider huggingface

Nicht interaktive Einrichtung

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`

Wenn Ihr Token gültig ist, erkennt OpenClaw beim Onboarding und beim Start des Gateway außerdem alle weiteren Modelle über GET https://router.huggingface.co/v1/models, sodass Ihr Katalog weit mehr als die drei oben aufgeführten Modelle enthalten kann. Sie können an jede Modell-ID :fastest oder :cheapest anhängen; der HF-Router leitet die Anfrage an den entsprechenden Inferenz-Provider weiter. Legen Sie Ihre standardmäßige Provider-Reihenfolge in den Inference Provider settings fest.

Erweiterte Konfiguration

OpenClaw erkennt Modelle mit:

GET https://router.huggingface.co/v1/models
Authorization: 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:

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:

{
  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).

OpenClaw akzeptiert sowohl HUGGINGFACE_HUB_TOKEN als auch HF_TOKEN. Wenn beide festgelegt sind, hat HUGGINGFACE_HUB_TOKEN Vorrang.

Konfiguration: DeepSeek R1 mit Fallback

{
  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

{
  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

{
  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" },
      },
    },
  },
}

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.

Overview

Concepts and configuration

Providers

Hugging Face (Inferenz)

Erste Schritte

Nicht interaktive Einrichtung

Modell-IDs

Erweiterte Konfiguration

Verwandte Themen

Modellauswahl

Modellauswahl

Dokumentation zu Inference Providers

Konfiguration

​Erste Schritte

​Nicht interaktive Einrichtung

​Modell-IDs

​Erweiterte Konfiguration

​Verwandte Themen

Modellauswahl

Modellauswahl

Dokumentation zu Inference Providers

Konfiguration

Erste Schritte

Nicht interaktive Einrichtung

Modell-IDs

Erweiterte Konfiguration

Verwandte Themen