Hugging Face (Inference)

Hugging Face Inference Providers bieten OpenAI-kompatible Chat Completions über eine einzige Router-API. Du bekommst Zugang zu vielen Modellen (DeepSeek, Llama und mehr) mit einem Token. OpenClaw nutzt den OpenAI-kompatiblen Endpunkt (nur Chat Completions); für Text-to-Image, Embeddings oder Speech verwende die HF Inference Clients direkt.

• Provider: huggingface
• Auth: HUGGINGFACE_HUB_TOKEN oder HF_TOKEN (Fein-granulares Token mit Make calls to Inference Providers)
• API: OpenAI-kompatibel (https://router.huggingface.co/v1)
• Abrechnung: Ein einzelnes HF-Token; Preise richten sich nach Provider-Tarifen mit einem kostenlosen Kontingent.

Schnellstart

1. Erstelle ein fein-granulares Token unter Hugging Face → Settings → Tokens mit der Berechtigung Make calls to Inference Providers.
2. Führe das Onboarding aus und wähle Hugging Face im Provider-Dropdown, dann gib deinen API-Key ein:

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

3. Im Dropdown Default Hugging Face model wähle das gewünschte Modell (die Liste wird von der Inference API geladen, wenn du ein gültiges Token hast; andernfalls wird eine integrierte Liste angezeigt). Deine Wahl wird als Standardmodell gespeichert.
4. Du kannst das Standardmodell auch später in der Konfiguration setzen oder ändern:

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

Nicht-interaktives Beispiel

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

Das setzt huggingface/deepseek-ai/DeepSeek-R1 als Standardmodell.

Umgebungshinweis

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

Modellerkennung und Onboarding-Dropdown

OpenClaw entdeckt Modelle durch direkten Aufruf des Inference-Endpunkts:

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

(Optional: Sende Authorization: Bearer $HUGGINGFACE_HUB_TOKEN oder $HF_TOKEN für die vollständige Liste; einige Endpunkte liefern ohne Authentifizierung nur eine Teilmenge.) Die Antwort ist im OpenAI-Stil { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

Wenn du einen Hugging Face API-Key konfigurierst (über Onboarding, HUGGINGFACE_HUB_TOKEN oder HF_TOKEN), nutzt OpenClaw diesen GET-Aufruf, um verfügbare Chat-Completion-Modelle zu entdecken. Beim interaktiven Onboarding siehst du nach Eingabe deines Tokens ein Default Hugging Face model-Dropdown, das mit dieser Liste gefüllt wird (oder dem integrierten Katalog, falls die Anfrage fehlschlägt). Zur Laufzeit (z.B. beim Gateway-Start) ruft OpenClaw bei vorhandenem Key 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). Bei fehlgeschlagener Anfrage oder fehlendem Key wird nur der integrierte Katalog verwendet.

Modellnamen und konfigurierbare Optionen

• Name von der API: Der Modell-Anzeigename wird aus GET /v1/models befüllt, wenn die API name, title oder display_name zurückgibt; andernfalls wird er aus der Modell-ID abgeleitet (z.B. deepseek-ai/DeepSeek-R1 → “DeepSeek R1”).
• Anzeigename überschreiben: Du kannst pro Modell ein benutzerdefiniertes Label in der Konfiguration setzen, damit es in CLI und UI so angezeigt wird, wie du möchtest:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

• Provider-/Policy-Auswahl: Hänge ein Suffix an die Modell-ID an, um zu wählen, wie der Router das Backend auswählt:

  • :fastest — höchster Durchsatz (Router wählt; Provider-Auswahl ist gesperrt — kein interaktiver Backend-Picker).
  • :cheapest — niedrigste Kosten pro Output-Token (Router wählt; Provider-Auswahl ist gesperrt).
  • :provider — ein bestimmtes Backend erzwingen (z.B. :sambanova, :together).

  Wenn du :cheapest oder :fastest wählst (z.B. im Onboarding-Modell-Dropdown), ist der Provider gesperrt: Der Router entscheidet nach Kosten oder Geschwindigkeit und es wird kein optionaler “bestimmtes Backend bevorzugen”-Schritt angezeigt. Du kannst diese als separate Einträge in models.providers.huggingface.models hinzufügen oder model.primary mit dem Suffix setzen. Du kannst deine Standardreihenfolge auch in den Inference Provider-Einstellungen setzen (kein Suffix = diese Reihenfolge verwenden).

• Config-Merge: Bestehende Einträge in models.providers.huggingface.models (z.B. in models.json) werden beim Config-Merge beibehalten. Alle benutzerdefinierten name-, alias- oder Modell-Optionen, die du dort gesetzt hast, bleiben erhalten.

Modell-IDs und Konfigurationsbeispiele

Modellreferenzen verwenden die Form huggingface/<org>/<model> (Hub-Style-IDs). Die Liste unten stammt von GET https://router.huggingface.co/v1/models; dein Katalog kann mehr enthalten.

Beispiel-IDs (vom Inference-Endpunkt):

Du kannst :fastest, :cheapest oder :provider (z.B. :together, :sambanova) an die Modell-ID anhängen. Setze deine Standardreihenfolge in den Inference Provider-Einstellungen; siehe Inference Providers und GET https://router.huggingface.co/v1/models für die vollständige Liste.

Vollständige Konfigurationsbeispiele

Primär DeepSeek R1 mit Qwen als Fallback:

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

Qwen als Standard, mit :cheapest- und :fastest-Varianten:

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

DeepSeek + Llama + GPT-OSS mit Aliases:

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

Bestimmtes Backend mit :provider erzwingen:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
      },
    },
  },
}

Mehrere Qwen- und DeepSeek-Modelle mit Policy-Suffixen:

{
  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 (cheap)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
      },
    },
  },
}