Hugging Face (inférence)

OpenClaw découvre les modèles en appelant directement l’endpoint Inference :

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

(Facultatif : envoyez Authorization: Bearer $HUGGINGFACE_HUB_TOKEN ou $HF_TOKEN pour la liste complète ; certains endpoints renvoient un sous-ensemble sans authentification.) La réponse est de 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écouvrir les modèles de chat completion disponibles. Pendant le setup interactif, 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). Au runtime (par ex. au démarrage du Gateway), lorsqu’une clé est présente, OpenClaw appelle à nouveau GET https://router.huggingface.co/v1/models pour rafraîchir le catalogue. La liste est fusionnée avec un catalogue intégré (pour des métadonnées comme la fenêtre de contexte et le coût). Si la requête échoue ou qu’aucune clé n’est définie, seul le catalogue intégré est utilisé.

• 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’identifiant du modèle (par ex. deepseek-ai/DeepSeek-R1 devient « DeepSeek R1 »).
• Surcharger le nom d’affichage : vous pouvez définir un libellé personnalisé par modèle dans la configuration pour qu’il 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 Hugging Face inclus d’OpenClaw traitent actuellement ces deux suffixes comme variantes de politique intégrées :

  • :fastest — débit le plus élevé.
  • :cheapest — coût le plus faible par jeton de sortie.

  Vous pouvez les ajouter comme entrées séparées dans models.providers.huggingface.models ou définir model.primary avec le suffixe. Vous pouvez aussi définir votre ordre de fournisseur par défaut dans les paramètres Inference Provider (pas de suffixe = utiliser cet ordre).

• Fusion de configuration : les entrées existantes dans models.providers.huggingface.models (par ex. dans models.json) sont conservées lors de la fusion de la configuration. Ainsi, tout name, alias, ou option de modèle personnalisé que vous y définissez est préservé.

Si le Gateway s’exécute comme 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).

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

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

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

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