Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

I provider Hugging Face Inference 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 HF inference.
  • 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 free tier.

​
Per iniziare

1

Crea un token a granularità fine

Vai a 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 desiderato. L’elenco viene caricato dalla Inference API 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 successivamente 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 ai modelli usano la forma huggingface/<org>/<model> (ID in stile Hub). L’elenco qui sotto 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 l’ordine predefinito in Inference Provider settings; vedi Inference Providers e GET https://router.huggingface.co/v1/models per l’elenco completo.

​
Configurazione avanzata

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 auth.) 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). A runtime (per esempio all’avvio del Gateway), quando è presente una chiave, OpenClaw chiama 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 idrato da GET /v1/models quando l’API restituisce name, title o display_name; altrimenti viene derivato dall’id del modello (per esempio deepseek-ai/DeepSeek-R1 diventa “DeepSeek R1”).
  • Override del nome visualizzato: puoi impostare un’etichetta personalizzata per modello nella configurazione così appare come vuoi nella CLI e nella UI:
{
  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 Hugging Face inclusi in OpenClaw trattano attualmente questi due suffissi come varianti di policy integrate:
    • :fastest — throughput massimo.
    • :cheapest — costo minimo per token in uscita.
    Puoi aggiungerli come voci separate in models.providers.huggingface.models oppure impostare model.primary con il suffisso. Puoi anche impostare l’ordine predefinito del provider in Inference Provider settings (senza suffisso = usa quell’ordine).
  • Merge della configurazione: le voci esistenti in models.providers.huggingface.models (per 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 gira come daemon (launchd/systemd), assicurati che HUGGINGFACE_HUB_TOKEN o HF_TOKEN sia disponibile per quel processo (per esempio in ~/.openclaw/.env o tramite env.shellEnv).
OpenClaw accetta sia HUGGINGFACE_HUB_TOKEN sia HF_TOKEN come alias di variabile env. Entrambi funzionano; 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

Selezione del provider di modelli

Panoramica di tutti i provider, dei riferimenti ai modelli 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.