Vai al contenuto principale

​
Hugging Face (Inference)

Gli Hugging Face Inference Providers offrono chat completions compatibili con OpenAI tramite una singola API router. Ottieni accesso a molti modelli (DeepSeek, Llama e altri) con un solo token. OpenClaw usa l’endpoint compatibile con OpenAI (solo chat completions); per text-to-image, embeddings o speech usa direttamente i client di inferenza HF.
  • Provider: huggingface
  • Auth: HUGGINGFACE_HUB_TOKEN o HF_TOKEN (token a granularità fine con Make calls to Inference Providers)
  • API: compatibile con OpenAI (https://router.huggingface.co/v1)
  • Billing: singolo token HF; i prezzi seguono le tariffe del provider con un livello gratuito.

​
Per iniziare

1

Crea un token a granularità fine

Vai su Hugging Face Settings Tokens e crea un nuovo token a granularità fine.
Il token deve avere abilitato il permesso Make calls to Inference Providers, altrimenti le richieste API verranno rifiutate.
2

Esegui l’onboarding

Scegli Hugging Face nel menu a discesa del provider, poi inserisci la tua chiave API quando richiesto:
openclaw onboard --auth-choice huggingface-api-key
3

Seleziona un modello predefinito

Nel menu a discesa Default Hugging Face model, scegli il modello che vuoi. L’elenco viene caricato dall’API Inference quando hai un token valido; altrimenti viene mostrato un elenco integrato. La tua scelta viene salvata come modello predefinito.Puoi anche impostare o cambiare il modello predefinito più tardi nella configurazione:
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}
4

Verifica che il modello sia disponibile

openclaw models list --provider huggingface

​
Configurazione non interattiva

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
Questo imposterà huggingface/deepseek-ai/DeepSeek-R1 come modello predefinito.

​
ID modello

I riferimenti di modello usano il formato huggingface/<org>/<model> (ID in stile Hub). L’elenco seguente proviene da GET https://router.huggingface.co/v1/models; il tuo catalogo potrebbe includerne altri.
ModelRef (prefix with huggingface/)
DeepSeek R1deepseek-ai/DeepSeek-R1
DeepSeek V3.2deepseek-ai/DeepSeek-V3.2
Qwen3 8BQwen/Qwen3-8B
Qwen2.5 7B InstructQwen/Qwen2.5-7B-Instruct
Qwen3 32BQwen/Qwen3-32B
Llama 3.3 70B Instructmeta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instructmeta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120Bopenai/gpt-oss-120b
GLM 4.7zai-org/GLM-4.7
Kimi K2.5moonshotai/Kimi-K2.5
Puoi aggiungere :fastest o :cheapest a qualsiasi ID modello. Imposta il tuo ordine predefinito nelle impostazioni di Inference Provider; consulta Inference Providers e GET https://router.huggingface.co/v1/models per l’elenco completo.

​
Dettagli avanzati

OpenClaw rileva i modelli chiamando direttamente l’endpoint Inference:
GET https://router.huggingface.co/v1/models
(Facoltativo: invia Authorization: Bearer $HUGGINGFACE_HUB_TOKEN o $HF_TOKEN per l’elenco completo; alcuni endpoint restituiscono un sottoinsieme senza autenticazione.) La risposta è in stile OpenAI { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.Quando configuri una chiave API Hugging Face (tramite onboarding, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), OpenClaw usa questa GET per rilevare i modelli di chat-completion disponibili. Durante la configurazione interattiva, dopo aver inserito il token vedi un menu a discesa Default Hugging Face model popolato da quell’elenco (oppure dal catalogo integrato se la richiesta fallisce). In fase di esecuzione (ad esempio all’avvio del Gateway), quando è presente una chiave, OpenClaw richiama di nuovo GET https://router.huggingface.co/v1/models per aggiornare il catalogo. L’elenco viene unito con un catalogo integrato (per metadati come finestra di contesto e costo). Se la richiesta fallisce o non è impostata alcuna chiave, viene usato solo il catalogo integrato.
  • Nome dall’API: il nome visualizzato del modello viene idratato da GET /v1/models quando l’API restituisce name, title o display_name; altrimenti viene derivato dall’ID del modello (ad esempio deepseek-ai/DeepSeek-R1 diventa “DeepSeek R1”).
  • Sostituisci il nome visualizzato: puoi impostare un’etichetta personalizzata per modello nella configurazione in modo che appaia come vuoi nella CLI e nell’interfaccia:
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}
  • Suffissi di policy: la documentazione e gli helper integrati di Hugging Face in OpenClaw attualmente trattano questi due suffissi come varianti di policy integrate:
    • :fastest — massima velocità effettiva.
    • :cheapest — costo più basso per token di output.
    Puoi aggiungerli come voci separate in models.providers.huggingface.models oppure impostare model.primary con il suffisso. Puoi anche impostare il tuo ordine predefinito del provider nelle impostazioni di Inference Provider (senza suffisso = usa quell’ordine).
  • Unione della configurazione: le voci esistenti in models.providers.huggingface.models (ad esempio in models.json) vengono mantenute quando la configurazione viene unita. Quindi qualsiasi name, alias o opzione del modello che imposti lì viene preservata.
Se il Gateway viene eseguito come daemon (launchd/systemd), assicurati che HUGGINGFACE_HUB_TOKEN o HF_TOKEN sia disponibile per quel processo (ad esempio in ~/.openclaw/.env o tramite env.shellEnv).
OpenClaw accetta sia HUGGINGFACE_HUB_TOKEN sia HF_TOKEN come alias di variabile d’ambiente. Funzionano entrambi; se sono impostati entrambi, HUGGINGFACE_HUB_TOKEN ha la precedenza.
{
  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" },
      },
    },
  },
}

​
Correlati

Provider di modelli

Panoramica di tutti i provider, dei riferimenti di modello e del comportamento di failover.

Selezione del modello

Come scegliere e configurare i modelli.

Documentazione Inference Providers

Documentazione ufficiale di Hugging Face Inference Providers.

Configurazione

Riferimento completo della configurazione.