> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hugging Face (Inferenz)

[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) bieten OpenAI-kompatible Chat Completions über eine einzige Router-API. Sie erhalten mit einem Token Zugriff auf viele Modelle (DeepSeek, Llama und mehr). OpenClaw verwendet den **OpenAI-kompatiblen Endpunkt** (nur Chat Completions); für Text-zu-Bild, Embeddings oder Sprache verwenden Sie die [HF-Inferenz-Clients](https://huggingface.co/docs/api-inference/quicktour) direkt.

* Provider: `huggingface`
* Auth: `HUGGINGFACE_HUB_TOKEN` oder `HF_TOKEN` (feingranulares Token mit **Make calls to Inference Providers**)
* API: OpenAI-kompatibel (`https://router.huggingface.co/v1`)
* Abrechnung: Ein einzelnes HF-Token; [Preise](https://huggingface.co/docs/inference-providers/pricing) folgen den Provider-Tarifen mit einer kostenlosen Stufe.

## Erste Schritte

<Steps>
  <Step title="Feingranulares Token erstellen">
    Gehen Sie zu [Hugging Face Settings Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write\&tokenType=fineGrained) und erstellen Sie ein neues feingranulares Token.

    <Warning>
      Das Token muss die Berechtigung **Make calls to Inference Providers** aktiviert haben, sonst werden API-Anfragen abgewiesen.
    </Warning>
  </Step>

  <Step title="Onboarding ausführen">
    Wählen Sie **Hugging Face** im Provider-Dropdown aus und geben Sie dann Ihren API-Schlüssel ein, wenn Sie dazu aufgefordert werden:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --auth-choice huggingface-api-key
    ```
  </Step>

  <Step title="Ein Standardmodell auswählen">
    Wählen Sie im Dropdown **Default Hugging Face model** das gewünschte Modell aus. Die Liste wird aus der Inference API geladen, wenn Sie ein gültiges Token haben; andernfalls wird eine integrierte Liste angezeigt. Ihre Auswahl wird als Standardmodell gespeichert.

    Sie können das Standardmodell später auch in der Konfiguration setzen oder ändern:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
        },
      },
    }
    ```
  </Step>

  <Step title="Prüfen, ob das Modell verfügbar ist">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw models list --provider huggingface
    ```
  </Step>
</Steps>

### Nicht-interaktives Setup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
```

Dadurch wird `huggingface/deepseek-ai/DeepSeek-R1` als Standardmodell gesetzt.

## Modell-IDs

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

| Modell                 | Ref (mit Präfix `huggingface/`)     |
| ---------------------- | ----------------------------------- |
| DeepSeek R1            | `deepseek-ai/DeepSeek-R1`           |
| DeepSeek V3.2          | `deepseek-ai/DeepSeek-V3.2`         |
| Qwen3 8B               | `Qwen/Qwen3-8B`                     |
| Qwen2.5 7B Instruct    | `Qwen/Qwen2.5-7B-Instruct`          |
| Qwen3 32B              | `Qwen/Qwen3-32B`                    |
| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
| Llama 3.1 8B Instruct  | `meta-llama/Llama-3.1-8B-Instruct`  |
| GPT-OSS 120B           | `openai/gpt-oss-120b`               |
| GLM 4.7                | `zai-org/GLM-4.7`                   |
| Kimi K2.5              | `moonshotai/Kimi-K2.5`              |

<Tip>
  Sie können an jede Modell-ID `:fastest` oder `:cheapest` anhängen. Legen Sie Ihre Standardreihenfolge in den [Inference Provider settings](https://hf.co/settings/inference-providers) fest; siehe [Inference Providers](https://huggingface.co/docs/inference-providers) und **GET** `https://router.huggingface.co/v1/models` für die vollständige Liste.
</Tip>

## Erweiterte Konfiguration

<AccordionGroup>
  <Accordion title="Modellerkennung und Onboarding-Dropdown">
    OpenClaw erkennt Modelle, indem der **Inference-Endpunkt direkt** aufgerufen wird:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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.
  </Accordion>

  <Accordion title="Modellnamen, Aliasse und Richtlinien-Suffixe">
    * **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:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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](https://hf.co/settings/inference-providers) 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.
  </Accordion>

  <Accordion title="Umgebung und Daemon-Setup">
    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`).

    <Note>
      OpenClaw akzeptiert sowohl `HUGGINGFACE_HUB_TOKEN` als auch `HF_TOKEN` als Aliasse für Umgebungsvariablen. Beide funktionieren; wenn beide gesetzt sind, hat `HUGGINGFACE_HUB_TOKEN` Vorrang.
    </Note>
  </Accordion>

  <Accordion title="Konfiguration: DeepSeek R1 mit Qwen-Fallback">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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" },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Konfiguration: Qwen mit cheapest- und fastest-Varianten">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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)" },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Konfiguration: DeepSeek + Llama + GPT-OSS mit Aliasen">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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" },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Konfiguration: Mehrere Qwen- und DeepSeek-Modelle mit Richtlinien-Suffixen">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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" },
          },
        },
      },
    }
    ```
  </Accordion>
</AccordionGroup>

## Verwandt

<CardGroup cols={2}>
  <Card title="Modellauswahl" href="/de/concepts/model-providers" icon="layers">
    Überblick über alle Provider, Modellreferenzen und Failover-Verhalten.
  </Card>

  <Card title="Modellauswahl" href="/de/concepts/models" icon="brain">
    Wie Modelle ausgewählt und konfiguriert werden.
  </Card>

  <Card title="Inference Providers docs" href="https://huggingface.co/docs/inference-providers" icon="book">
    Offizielle Dokumentation zu Hugging Face Inference Providers.
  </Card>

  <Card title="Konfiguration" href="/de/gateway/configuration" icon="gear">
    Vollständige Konfigurationsreferenz.
  </Card>
</CardGroup>