OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

Hugging Face (inferenza)

Hugging Face Inference Providers espone un router per completamenti chat compatibile con OpenAI davanti a numerosi modelli ospitati (DeepSeek, Llama e altri), accessibili con un unico token. OpenClaw comunica esclusivamente con l'endpoint dei completamenti chat; per la conversione da testo a immagine, gli embedding o la sintesi vocale, usa direttamente i client di inferenza HF.

Proprietà Valore
ID del provider huggingface
Plugin incluso (abilitato per impostazione predefinita, nessun passaggio di installazione)
Variabile di ambiente per l'autenticazione HUGGINGFACE_HUB_TOKEN o HF_TOKEN (token granulare)
API Compatibile con OpenAI (https://router.huggingface.co/v1)
Fatturazione Un unico token HF; i prezzi seguono le tariffe del provider con un piano gratuito

Per iniziare

  • Crea un token granulare

    Vai a Hugging Face Settings Tokens e crea un nuovo token granulare.

  • Esegui la configurazione iniziale

    Scegli Hugging Face nell'elenco a discesa dei provider, quindi inserisci la chiave API quando richiesto:

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

  • Seleziona un modello predefinito

    Nell'elenco a discesa Default Hugging Face model, scegli un modello. L'elenco viene caricato dall'Inference API quando il token è valido; in caso contrario, OpenClaw mostra il catalogo integrato riportato di seguito. La scelta viene salvata come agents.defaults.model.primary:

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

  • Verifica che il modello sia disponibile

    bash
    openclaw models list --provider huggingface

    • Configurazione non interattiva

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

    Imposta huggingface/deepseek-ai/DeepSeek-R1 come modello predefinito.

    ID dei modelli

    I riferimenti ai modelli usano il formato huggingface/<org>/<model> (ID in stile Hub). Catalogo integrato di OpenClaw:

    Modello Riferimento (con prefisso 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

    Configurazione avanzata

    Rilevamento dei modelli ed elenco a discesa della configurazione iniziale

    OpenClaw rileva i modelli tramite:

    bash
    GET https://router.huggingface.co/v1/modelsAuthorization: Bearer $HUGGINGFACE_HUB_TOKEN   # oppure $HF_TOKEN

    La risposta segue il formato di OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

    Con una chiave configurata (tramite la configurazione iniziale, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), l'elenco a discesa Default Hugging Face model durante la configurazione interattiva viene popolato da questo endpoint. All'avvio, il Gateway ripete la stessa chiamata per aggiornare il catalogo. I modelli rilevati vengono uniti al catalogo integrato riportato sopra, usato per metadati quali la finestra di contesto e il costo quando un ID corrisponde. Se la richiesta non riesce, non restituisce dati o non è impostata alcuna chiave, OpenClaw utilizza esclusivamente il catalogo integrato.

    Disabilita il rilevamento senza rimuovere il provider:

    bash
    openclaw config set plugins.entries.huggingface.config.discovery.enabled false
    Nomi e alias dei modelli e suffissi dei criteri
    • Nome dall'API: i modelli rilevati usano il valore name, title o display_name dell'API quando presente; altrimenti OpenClaw ricava un nome dall'ID modello (ad esempio, deepseek-ai/DeepSeek-R1 diventa "DeepSeek R1").
    • Sostituzione del nome visualizzato: imposta un'etichetta personalizzata per ciascun modello nella configurazione:
    json5
    {  agents: {    defaults: {      models: {        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },      },    },  },}
    • Suffissi dei criteri: :fastest e :cheapest sono convenzioni del router HF e non vengono riscritti da OpenClaw: il suffisso viene inviato invariato come parte dell'ID modello e il router HF sceglie il provider di inferenza corrispondente. Aggiungi ogni variante come voce distinta in models.providers.huggingface.models (o in model.primary) se desideri un alias diverso per ciascun suffisso.
    • Unione della configurazione: le voci esistenti in models.providers.huggingface.models (ad esempio in models.json) vengono mantenute durante l'unione della configurazione, quindi qualsiasi valore personalizzato di name, alias o qualsiasi opzione del modello impostata in quella posizione persiste tra i riavvii.
    Configurazione dell'ambiente e del daemon

    Se il Gateway viene eseguito come daemon (launchd/systemd), assicurati che HUGGINGFACE_HUB_TOKEN o HF_TOKEN sia disponibile per tale processo, ad esempio in ~/.openclaw/.env o tramite env.shellEnv.

    Configurazione: DeepSeek R1 con modello alternativo
    json5
    {  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" },      },    },  },}
    Configurazione: DeepSeek con le varianti più economica e più veloce
    json5
    {  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)" },      },    },  },}
    Configurazione: DeepSeek + Llama + GPT-OSS con alias
    json5
    {  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" },      },    },  },}

    Contenuti correlati

    Selezione del modello

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

    Come scegliere e configurare i modelli.
    Documentazione di Inference Providers

    Documentazione ufficiale di Hugging Face Inference Providers.
    Configurazione

    Riferimento completo della configurazione.
    Was this useful?
    On this page

    On this page