Hugging Face (inference)

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).

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