Hugging Face (Inference)

Los proveedores de Inference de Hugging Face ofrecen completaciones de chat compatibles con OpenAI a traves de una unica API de enrutamiento. Obtienes acceso a muchos modelos (DeepSeek, Llama y mas) con un solo token. OpenClaw usa el endpoint compatible con OpenAI (solo completaciones de chat); para texto a imagen, embeddings o voz, usa los clientes de inference de HF directamente.

• Proveedor: huggingface
• Autenticacion: HUGGINGFACE_HUB_TOKEN o HF_TOKEN (token detallado con permiso Make calls to Inference Providers)
• API: compatible con OpenAI (https://router.huggingface.co/v1)
• Facturacion: un solo token de HF; los precios siguen las tarifas del proveedor con un nivel gratuito.

Inicio rapido

1. Crea un token detallado en Hugging Face -> Settings -> Tokens con el permiso Make calls to Inference Providers.
2. Ejecuta el onboarding y elige Hugging Face en el menu de proveedores, luego ingresa tu clave API cuando se te solicite:

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

3. En el menu desplegable Default Hugging Face model, selecciona el modelo que deseas (la lista se carga desde la API de Inference cuando tienes un token valido; de lo contrario se muestra una lista predefinida). Tu seleccion se guarda como modelo por defecto.
4. Tambien puedes establecer o cambiar el modelo por defecto mas adelante en la configuracion:

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

Ejemplo no interactivo

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

Esto establecera huggingface/deepseek-ai/DeepSeek-R1 como modelo por defecto.

Nota sobre el entorno

Si el Gateway se ejecuta como daemon (launchd/systemd), asegurate de que HUGGINGFACE_HUB_TOKEN o HF_TOKEN esten disponibles para ese proceso (por ejemplo, en ~/.openclaw/.env o a traves de env.shellEnv).

Descubrimiento de modelos y menu de onboarding

OpenClaw descubre modelos llamando directamente al endpoint de Inference:

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

(Opcional: enviar Authorization: Bearer $HUGGINGFACE_HUB_TOKEN o $HF_TOKEN para la lista completa; algunos endpoints devuelven un subconjunto sin autenticacion.) La respuesta tiene el estilo de OpenAI { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

Cuando configuras una clave API de Hugging Face (via onboarding, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), OpenClaw usa este GET para descubrir los modelos de completacion de chat disponibles. Durante el onboarding interactivo, despues de ingresar tu token veras un menu desplegable Default Hugging Face model poblado desde esa lista (o el catalogo predefinido si la solicitud falla). En tiempo de ejecucion (por ejemplo, al iniciar el Gateway), cuando hay una clave presente, OpenClaw vuelve a llamar a GET https://router.huggingface.co/v1/models para actualizar el catalogo. La lista se fusiona con un catalogo predefinido (para metadatos como ventana de contexto y costo). Si la solicitud falla o no hay clave configurada, solo se usa el catalogo predefinido.

Nombres de modelos y opciones editables

• Nombre de la API: El nombre de visualizacion del modelo se obtiene de GET /v1/models cuando la API devuelve name, title o display_name; de lo contrario se deriva del ID del modelo (por ejemplo deepseek-ai/DeepSeek-R1 -> “DeepSeek R1”).
• Sobreescribir nombre: Puedes establecer una etiqueta personalizada por modelo en la configuracion para que aparezca como desees en el CLI y la interfaz:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

• Seleccion de proveedor / politica: Agrega un sufijo al ID del modelo para elegir como el enrutador selecciona el backend:

  • :fastest — mayor rendimiento (el enrutador elige; la seleccion de proveedor esta bloqueada — no hay selector interactivo de backend).
  • :cheapest — menor costo por token de salida (el enrutador elige; la seleccion de proveedor esta bloqueada).
  • :provider — forzar un backend especifico (por ejemplo :sambanova, :together).

  Cuando seleccionas :cheapest o :fastest (por ejemplo en el menu de seleccion de modelo del onboarding), el proveedor queda bloqueado: el enrutador decide por costo o velocidad y no se muestra un paso opcional de “preferir backend especifico”. Puedes agregarlos como entradas separadas en models.providers.huggingface.models o establecer model.primary con el sufijo. Tambien puedes configurar tu orden por defecto en los ajustes de Inference Provider (sin sufijo = usar ese orden).

• Fusion de configuracion: Las entradas existentes en models.providers.huggingface.models (por ejemplo en models.json) se conservan cuando se fusiona la configuracion. Asi, cualquier name, alias u opciones de modelo personalizadas que establezcas ahi se preservan.

IDs de modelo y ejemplos de configuracion

Las referencias de modelos usan la forma huggingface/<org>/<model> (IDs al estilo Hub). La lista a continuacion proviene de GET https://router.huggingface.co/v1/models; tu catalogo puede incluir mas.

IDs de ejemplo (del endpoint de inference):

Puedes agregar :fastest, :cheapest o :provider (por ejemplo :together, :sambanova) al ID del modelo. Configura tu orden por defecto en los ajustes de Inference Provider; consulta Inference Providers y GET https://router.huggingface.co/v1/models para la lista completa.

Ejemplos completos de configuracion

DeepSeek R1 principal con Qwen como respaldo:

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

Qwen por defecto, con variantes :cheapest y :fastest:

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

DeepSeek + Llama + GPT-OSS con alias:

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

Forzar un backend especifico con :provider:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
      },
    },
  },
}

Multiples modelos Qwen y DeepSeek con sufijos de politica:

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