Hugging Face (inférence)

Hugging Face Inference Providers expose un routeur de complétions de chat compatible avec OpenAI, donnant accès à de nombreux modèles hébergés (DeepSeek, Llama et d’autres) avec un seul jeton. OpenClaw communique uniquement avec le point de terminaison des complétions de chat ; pour la génération d’images à partir de texte, les embeddings ou la parole, utilisez directement les clients d’inférence HF.

Propriété	Valeur
Identifiant du fournisseur	`huggingface`
Plugin	intégré (activé par défaut, aucune étape d’installation)
Variable d’environnement d’authentification	`HUGGINGFACE_HUB_TOKEN` ou `HF_TOKEN` (jeton à granularité fine)
API	compatible avec OpenAI (`https://router.huggingface.co/v1`)
Facturation	Un seul jeton HF ; la tarification suit les tarifs du fournisseur avec un niveau gratuit

Prise en main

Create a fine-grained token

Accédez à Hugging Face Settings Tokens et créez un nouveau jeton à granularité fine.

L’autorisation Make calls to Inference Providers doit être activée pour le jeton, sinon les requêtes API seront rejetées.

Run onboarding

Choisissez Hugging Face dans la liste déroulante des fournisseurs, puis saisissez votre clé API lorsque vous y êtes invité :

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

Select a default model

Dans la liste déroulante Modèle Hugging Face par défaut, choisissez un modèle. La liste est chargée depuis l’API d’inférence lorsque votre jeton est valide ; sinon, OpenClaw affiche le catalogue intégré ci-dessous. Votre choix est enregistré dans agents.defaults.model.primary :

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

Verify the model is available

openclaw models list --provider huggingface

Configuration non interactive

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

Définit huggingface/deepseek-ai/DeepSeek-R1 comme modèle par défaut.

Identifiants de modèles

Les références de modèles utilisent la forme huggingface/<org>/<model> (identifiants au format Hub). Catalogue intégré d’OpenClaw :

Modèle	Référence (préfixée par `huggingface/`)
DeepSeek R1	`deepseek-ai/DeepSeek-R1`
DeepSeek V3.1	`deepseek-ai/DeepSeek-V3.1`
GPT-OSS 120B	`openai/gpt-oss-120b`
Llama 3.3 70B Instruct Turbo	`meta-llama/Llama-3.3-70B-Instruct-Turbo`

Lorsque votre jeton est valide, OpenClaw découvre également tout autre modèle fourni par GET https://router.huggingface.co/v1/models lors de l’intégration et du démarrage du Gateway. Votre catalogue peut donc contenir bien plus que les quatre modèles ci-dessus. Vous pouvez ajouter :fastest ou :cheapest à n’importe quel identifiant de modèle ; le routeur de HF achemine alors la requête vers le fournisseur d’inférence correspondant. Définissez l’ordre par défaut de vos fournisseurs dans les paramètres des fournisseurs d’inférence.

Configuration avancée

OpenClaw découvre les modèles avec :

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # or $HF_TOKEN

La réponse suit le format d’OpenAI : { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.Lorsqu’une clé est configurée (pendant l’intégration, via HUGGINGFACE_HUB_TOKEN ou via HF_TOKEN), la liste déroulante Modèle Hugging Face par défaut de la configuration interactive est alimentée à partir de ce point de terminaison. Au démarrage, le Gateway répète le même appel pour actualiser le catalogue. Les modèles découverts sont fusionnés avec le catalogue intégré ci-dessus, qui fournit notamment les métadonnées telles que la fenêtre de contexte et le coût lorsqu’un identifiant correspond. Si la requête échoue, ne renvoie aucune donnée ou qu’aucune clé n’est définie, OpenClaw utilise uniquement le catalogue intégré.Désactivez la découverte sans supprimer le fournisseur :

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

Model names, aliases, and policy suffixes

Nom provenant de l’API : les modèles découverts utilisent la valeur name, title ou display_name de l’API lorsqu’elle est présente ; sinon, OpenClaw déduit un nom de l’identifiant du modèle (par exemple, deepseek-ai/DeepSeek-R1 devient « DeepSeek R1 »).
Remplacement du nom d’affichage : définissez un libellé personnalisé pour chaque modèle dans la configuration :

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

Suffixes de stratégie : :fastest et :cheapest sont des conventions du routeur de HF, et non des valeurs réécrites par OpenClaw : le suffixe est envoyé tel quel dans l’identifiant du modèle, puis le routeur de HF sélectionne le fournisseur d’inférence correspondant. Ajoutez chaque variante comme entrée distincte sous models.providers.huggingface.models (ou dans model.primary) si vous souhaitez un alias différent pour chaque suffixe.
Fusion de la configuration : les entrées existantes dans models.providers.huggingface.models (par exemple dans models.json) sont conservées lors de la fusion de la configuration. Tout name, alias ou toute option de modèle personnalisée que vous y définissez persiste donc après les redémarrages.

Environment and daemon setup

Si le Gateway s’exécute comme un démon (launchd/systemd), assurez-vous que HUGGINGFACE_HUB_TOKEN ou HF_TOKEN est accessible à ce processus (par exemple dans ~/.openclaw/.env ou via env.shellEnv).

OpenClaw accepte à la fois HUGGINGFACE_HUB_TOKEN et HF_TOKEN. Si les deux sont définis, HUGGINGFACE_HUB_TOKEN est prioritaire.

Config: DeepSeek R1 with 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" },
      },
    },
  },
}

Config: DeepSeek with cheapest and fastest variants

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

Config: DeepSeek + Llama + GPT-OSS with aliases

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

Contenu associé

Model selection

Vue d’ensemble de tous les fournisseurs, des références de modèles et du comportement de basculement.

Model selection

Comment choisir et configurer des modèles.

Inference Providers docs

Documentation officielle de Hugging Face Inference Providers.

Configuration

Référence complète de la configuration.

Overview

Concepts and configuration

Providers

Hugging Face (inférence)

Prise en main

Configuration non interactive

Identifiants de modèles

Configuration avancée

Contenu associé

Model selection

Model selection

Inference Providers docs

Configuration

​Prise en main

​Configuration non interactive

​Identifiants de modèles

​Configuration avancée

​Contenu associé

Model selection

Model selection

Inference Providers docs

Configuration

Prise en main

Configuration non interactive

Identifiants de modèles

Configuration avancée

Contenu associé