Hugging Face (Inference)

Les Hugging Face Inference Providers proposent des complétions de chat compatibles OpenAI via une API routeur unique. Vous accédez à de nombreux modèles (DeepSeek, Llama, etc.) avec un seul jeton. OpenClaw utilise le point de terminaison compatible OpenAI (complétions de chat uniquement) ; pour le text-to-image, les embeddings ou la parole, utilisez directement les clients d’inférence HF.

Fournisseur : huggingface
Auth : HUGGINGFACE_HUB_TOKEN ou HF_TOKEN (jeton à granularité fine avec l’autorisation Make calls to Inference Providers)
API : compatible OpenAI (https://router.huggingface.co/v1)
Facturation : jeton HF unique ; la tarification suit les tarifs du fournisseur avec un niveau gratuit.

Prise en main

Créer un jeton à granularité fine

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

Le jeton doit avoir l’autorisation Make calls to Inference Providers activée, sinon les requêtes API seront rejetées.

Exécuter l’onboarding

Choisissez Hugging Face dans la liste déroulante des fournisseurs, puis saisissez votre clé API lorsqu’elle est demandée :

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

Sélectionner un modèle par défaut

Dans la liste déroulante Default Hugging Face model, choisissez le modèle souhaité. La liste est chargée depuis l’API Inference lorsque vous avez un jeton valide ; sinon, une liste intégrée est affichée. Votre choix est enregistré comme modèle par défaut.Vous pouvez aussi définir ou modifier le modèle par défaut plus tard dans la configuration :

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

Vérifier que le modèle est disponible

openclaw models list --provider huggingface

Configuration non interactive

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

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

ID de modèle

Les références de modèles utilisent la forme huggingface/<org>/<model> (ID de style Hub). La liste ci-dessous provient de GET https://router.huggingface.co/v1/models ; votre catalogue peut en inclure davantage.

Modèle	Référence (préfixée par `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`

Vous pouvez ajouter :fastest ou :cheapest à n’importe quel ID de modèle. Définissez votre ordre par défaut dans les paramètres Inference Provider ; voir Inference Providers et GET https://router.huggingface.co/v1/models pour la liste complète.

Détails avancés

Détection des modèles et liste déroulante d’onboarding

OpenClaw détecte les modèles en appelant directement le point de terminaison Inference :

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

(Facultatif : envoyez Authorization: Bearer $HUGGINGFACE_HUB_TOKEN ou $HF_TOKEN pour la liste complète ; certains points de terminaison renvoient un sous-ensemble sans auth.) La réponse suit le style OpenAI : { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.Lorsque vous configurez une clé API Hugging Face (via l’onboarding, HUGGINGFACE_HUB_TOKEN ou HF_TOKEN), OpenClaw utilise ce GET pour détecter les modèles de complétion de chat disponibles. Pendant la configuration interactive, après avoir saisi votre jeton, vous voyez une liste déroulante Default Hugging Face model alimentée à partir de cette liste (ou du catalogue intégré si la requête échoue). À l’exécution (par exemple au démarrage de Gateway), lorsqu’une clé est présente, OpenClaw appelle à nouveau GET https://router.huggingface.co/v1/models pour actualiser le catalogue. La liste est fusionnée avec un catalogue intégré (pour les métadonnées comme la fenêtre de contexte et le coût). Si la requête échoue ou si aucune clé n’est définie, seul le catalogue intégré est utilisé.

Noms de modèles, alias et suffixes de politique

Nom depuis l’API : le nom d’affichage du modèle est hydraté depuis GET /v1/models lorsque l’API renvoie name, title ou display_name ; sinon, il est dérivé de l’ID du modèle (par exemple deepseek-ai/DeepSeek-R1 devient « DeepSeek R1 »).
Remplacer le nom d’affichage : vous pouvez définir une étiquette personnalisée par modèle dans la configuration afin qu’elle apparaisse comme vous le souhaitez dans la CLI et l’interface :

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

Suffixes de politique : la documentation et les helpers intégrés Hugging Face d’OpenClaw traitent actuellement ces deux suffixes comme variantes de politique intégrées :
- :fastest — débit maximal.
- :cheapest — coût le plus bas par jeton de sortie.
Vous pouvez les ajouter comme entrées distinctes dans models.providers.huggingface.models ou définir model.primary avec le suffixe. Vous pouvez également définir votre ordre de fournisseurs par défaut dans les paramètres Inference Provider (sans suffixe = utiliser cet ordre).
Fusion de configuration : les entrées existantes dans models.providers.huggingface.models (par exemple dans models.json) sont conservées lors de la fusion de configuration. Ainsi, tout name, alias ou toute option de modèle que vous y définissez sont préservés.

Environnement et configuration daemon

Si la Gateway s’exécute comme un daemon (launchd/systemd), assurez-vous que HUGGINGFACE_HUB_TOKEN ou HF_TOKEN est disponible pour ce processus (par exemple dans ~/.openclaw/.env ou via env.shellEnv).

OpenClaw accepte à la fois HUGGINGFACE_HUB_TOKEN et HF_TOKEN comme alias de variable d’environnement. Les deux fonctionnent ; si les deux sont définies, HUGGINGFACE_HUB_TOKEN est prioritaire.

Configuration : DeepSeek R1 avec repli Qwen

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

Configuration : Qwen avec variantes cheapest et fastest

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

Configuration : DeepSeek + Llama + GPT-OSS avec alias

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

Configuration : plusieurs modèles Qwen et DeepSeek avec suffixes de politique

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

Liens associés

Model providers

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 les modèles.

Inference Providers docs

Documentation officielle des Hugging Face Inference Providers.

Configuration

Référence complète de configuration.

Overview

Concepts and configuration

Providers

Hugging Face (Inference)

Hugging Face (Inference)

Prise en main

Configuration non interactive

ID de modèle

Détails avancés

Liens associés

Model providers

Model selection

Inference Providers docs

Configuration

Overview

Concepts and configuration

Providers

​Hugging Face (Inference)

​Prise en main

​Configuration non interactive

​ID de modèle

​Détails avancés

​Liens associés

Model providers

Model selection

Inference Providers docs

Configuration

Hugging Face (Inference)

Prise en main

Configuration non interactive

ID de modèle

Détails avancés

Liens associés