Hugging Face (inferencia)

Proveedores de inferencia de Hugging Face ofrece un enrutador de finalizaciones de chat compatible con OpenAI para numerosos modelos alojados (DeepSeek, Llama y más) mediante un único token. OpenClaw se comunica únicamente con el endpoint de finalizaciones de chat; para texto a imagen, embeddings o voz, use directamente los clientes de inferencia de HF.

Propiedad	Valor
Id. del proveedor	`huggingface`
Plugin	incluido (habilitado de forma predeterminada, sin ningún paso de instalación)
Variable de entorno de autenticación	`HUGGINGFACE_HUB_TOKEN` o `HF_TOKEN` (token específico)
API	Compatible con OpenAI (`https://router.huggingface.co/v1`)
Facturación	Un único token de HF; los precios siguen las tarifas del proveedor con un nivel gratuito

Primeros pasos

Crear un token específico

Vaya a Hugging Face Settings Tokens y cree un nuevo token específico.

El token debe tener habilitado el permiso Make calls to Inference Providers; de lo contrario, se rechazarán las solicitudes de la API.

Ejecutar la incorporación

Elija Hugging Face en la lista desplegable de proveedores y, cuando se le solicite, introduzca su clave de API:

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

Seleccionar un modelo predeterminado

En la lista desplegable Modelo predeterminado de Hugging Face, elija un modelo. La lista se carga desde la API de inferencia cuando el token es válido; de lo contrario, OpenClaw muestra el catálogo integrado que aparece a continuación. La selección se guarda como agents.defaults.model.primary:

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

Verificar que el modelo esté disponible

openclaw models list --provider huggingface

Configuración no interactiva

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

Establece huggingface/deepseek-ai/DeepSeek-R1 como modelo predeterminado.

Id. de modelos

Las referencias de modelos usan el formato huggingface/<org>/<model> (id. al estilo de Hub). Catálogo integrado de OpenClaw:

Modelo	Ref. (con el prefijo `huggingface/`)
DeepSeek R1	`deepseek-ai/DeepSeek-R1`
DeepSeek V3.1	`deepseek-ai/DeepSeek-V3.1`
GPT-OSS 120B	`openai/gpt-oss-120b`

Cuando el token es válido, OpenClaw también detecta cualquier otro modelo mediante GET https://router.huggingface.co/v1/models durante la incorporación y el inicio del Gateway, por lo que el catálogo puede incluir muchos más que los tres modelos anteriores. Puede añadir :fastest o :cheapest a cualquier id. de modelo; el enrutador de HF dirige la solicitud al proveedor de inferencia correspondiente. Establezca el orden predeterminado de los proveedores en la configuración de proveedores de inferencia.

Configuración avanzada

Detección de modelos y lista desplegable de incorporación

OpenClaw detecta los modelos mediante:

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # o $HF_TOKEN

La respuesta sigue el estilo de OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.Con una clave configurada (incorporación, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), la lista desplegable Modelo predeterminado de Hugging Face durante la configuración interactiva se rellena desde este endpoint. El inicio del Gateway repite la misma llamada para actualizar el catálogo. Los modelos detectados se combinan con el catálogo integrado anterior (que se usa para metadatos como la ventana de contexto y el coste cuando coincide un id.). Si la solicitud falla, no devuelve datos o no se ha establecido ninguna clave, OpenClaw recurre únicamente al catálogo integrado.Para deshabilitar la detección sin eliminar el proveedor:

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

Nombres de modelos, alias y sufijos de políticas

Nombre de la API: los modelos detectados usan name, title o display_name de la API cuando están presentes; de lo contrario, OpenClaw deriva un nombre del id. del modelo (por ejemplo, deepseek-ai/DeepSeek-R1 se convierte en “DeepSeek R1”).
Sobrescribir el nombre para mostrar: establezca una etiqueta personalizada para cada modelo en la configuración:

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

Sufijos de políticas: :fastest y :cheapest son convenciones del enrutador de HF, no algo que OpenClaw reescriba: el sufijo se envía literalmente como parte del id. del modelo y el enrutador de HF elige el proveedor de inferencia correspondiente. Añada cada variante como su propia entrada en models.providers.huggingface.models (o en model.primary) si desea un alias distinto para cada sufijo.
Combinación de la configuración: las entradas existentes en models.providers.huggingface.models (por ejemplo, en models.json) se conservan al combinar la configuración, por lo que cualquier name, alias u opción de modelo personalizada que establezca allí se mantiene tras los reinicios.

Configuración del entorno y del demonio

Si el Gateway se ejecuta como demonio (launchd/systemd), asegúrese de que HUGGINGFACE_HUB_TOKEN o HF_TOKEN esté disponible para ese proceso (por ejemplo, en ~/.openclaw/.env o mediante env.shellEnv).

OpenClaw acepta tanto HUGGINGFACE_HUB_TOKEN como HF_TOKEN. Si se establecen ambos, HUGGINGFACE_HUB_TOKEN tiene prioridad.

Configuración: DeepSeek R1 con modelo alternativo

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

Configuración: DeepSeek con las variantes más barata y más rápida

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

Configuración: DeepSeek + GPT-OSS con alias

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

Contenido relacionado

Selección de modelos

Descripción general de todos los proveedores, las referencias de modelos y el comportamiento de conmutación por error.

Selección de modelos

Cómo elegir y configurar modelos.

Documentación de los proveedores de inferencia

Documentación oficial de los proveedores de inferencia de Hugging Face.

Configuración

Referencia completa de la configuración.

Overview

Concepts and configuration

Providers

Hugging Face (inferencia)

Primeros pasos

Configuración no interactiva

Id. de modelos

Configuración avanzada

Contenido relacionado

Selección de modelos

Selección de modelos

Documentación de los proveedores de inferencia

Configuración

​Primeros pasos

​Configuración no interactiva

​Id. de modelos

​Configuración avanzada

​Contenido relacionado

Selección de modelos

Selección de modelos

Documentación de los proveedores de inferencia

Configuración

Primeros pasos

Configuración no interactiva

Id. de modelos

Configuración avanzada

Contenido relacionado