Hugging Face (inferencia)

Los proveedores de inferencia de Hugging Face ofrecen completaciones de chat compatibles con OpenAI a través de una única API de enrutamiento. Obtienes acceso a muchos modelos (DeepSeek, Llama y más) con un solo token. OpenClaw utiliza el endpoint compatible con OpenAI (solo completaciones de chat); para texto a imagen, incrustaciones o voz, usa los clientes de inferencia de HF directamente.

• Proveedor: huggingface
• Autenticación: HUGGINGFACE_HUB_TOKEN o HF_TOKEN (token de grano fino con Realizar llamadas a proveedores de inferencia)
• API: Compatible con OpenAI (https://router.huggingface.co/v1)
• Facturación: Token único de HF; precios sigue las tarifas del proveedor con un nivel gratuito.

Primeros pasos

1. Crear un token de grano fino

   Ve a Tokens de configuración de Hugging Face y crea un nuevo token de grano fino.

   Warning

   El token debe tener el permiso Realizar llamadas a proveedores de inferencia habilitado o las solicitudes de la API serán rechazadas.

2. Ejecutar la incorporación

   Elige Hugging Face en el menú desplegable de proveedores, luego ingresa tu clave de API cuando se te solicite:

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

3. Seleccionar un modelo predeterminado

   En el menú desplegable Modelo Hugging Face predeterminado, elige el modelo que deseas. La lista se carga desde la API de inferencia cuando tienes un token válido; de lo contrario, se muestra una lista integrada. Tu elección se guarda como el modelo predeterminado.

   También puedes establecer o cambiar el modelo predeterminado más tarde en la configuración:

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

4. 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"

Esto establecerá huggingface/deepseek-ai/DeepSeek-R1 como el modelo predeterminado.

ID de modelo

Las referencias de modelos utilizan el formato huggingface/<org>/<model> (ID de estilo Hub). La lista a continuación proviene de GET https://router.huggingface.co/v1/models; tu catálogo puede incluir más.

Modelo	Ref (con el prefijo huggingface/)
DeepSeek R1	deepseek-ai/DeepSeek-R1
DeepSeek V3.2	deepseek-ai/DeepSeek-V3.2
Qwen3 8B	Qwen/Qwen3-8B
Qwen2.5 7B Instruct	Qwen/Qwen2.5-7B-Instruct
Qwen3 32B	Qwen/Qwen3-32B
Llama 3.3 70B Instruct	meta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instruct	meta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120B	openai/gpt-oss-120b
GLM 4.7	zai-org/GLM-4.7
Kimi K2.5	moonshotai/Kimi-K2.5

Tip

Puedes añadir

:fastest

o

:cheapest

a cualquier ID de modelo. Establece tu orden predeterminado en

Inference Provider settings

; consulta

Inference Providers

y

GET

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

para ver la lista completa.

Configuración avanzada

Model discovery and onboarding dropdown

OpenClaw descubre los modelos llamando al Inference endpoint directamente:

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

(Opcional: envía Authorization: Bearer $HUGGINGFACE_HUB_TOKEN o $HF_TOKEN para obtener la lista completa; algunos endpoints devuelven un subconjunto sin autenticación). La respuesta es de estilo OpenAI { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

Cuando configuras una clave de API de Hugging Face (vía onboarding, HUGGINGFACE_HUB_TOKEN, o HF_TOKEN), OpenClaw utiliza este GET para descubrir los modelos de chat-completion disponibles. Durante la configuración interactiva, después de ingresar tu token, verás un menú desplegable de Default Hugging Face model rellenado a partir de esa lista (o el catálogo integrado si la solicitud falla). En tiempo de ejecución (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 catálogo. La lista se fusiona con un catálogo integrado (para metadatos como la ventana de contexto y el costo). Si la solicitud falla o no se establece ninguna clave, solo se utiliza el catálogo integrado.

Nombres de modelos, alias y sufijos de política

• Nombre de la API: El nombre visible 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 se convierte en “DeepSeek R1”).
• Sobrescribir nombre visible: Puede establecer una etiqueta personalizada por modelo en la configuración para que aparezca como desee en la CLI y la UI:

{
  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ítica: La documentación y las utilidades de Hugging Face incluidas en OpenClaw actualmente tratan estos dos sufijos como variantes de política integradas:

  • :fastest — máximo rendimiento.
  • :cheapest — menor costo por token de salida.

  Puede agregarlos como entradas separadas en models.providers.huggingface.models o establecer model.primary con el sufijo. También puede establecer su orden predeterminado de proveedores en Configuración del proveedor de inferencia (sin sufijo = usar ese orden).

• Fusión de configuración: Las entradas existentes en models.providers.huggingface.models (por ejemplo, en models.json) se mantienen cuando se fusiona la configuración. Por lo tanto, cualquier name, alias u opciones de modelo que establezca allí se conservan.

Configuración de entorno y demonio

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

Note

OpenClaw acepta tanto HUGGINGFACE_HUB_TOKEN como HF_TOKEN como alias de variables de entorno. Cualquiera de los dos funciona; si ambos están establecidos, HUGGINGFACE_HUB_TOKEN tiene prioridad.

Config: DeepSeek R1 con respaldo Qwen

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

Config: Qwen con las variantes más económicas y rápidas

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

Config: 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" },
      },
    },
  },
}

Config: Múltiples Qwen y DeepSeek con sufijos de política

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

Relacionado

Selección de modelo

Resumen de todos los proveedores, referencias de modelos y comportamiento de conmutación por error.

Selección de modelo

Cómo elegir y configurar modelos.

Documentación de Inference Providers

Documentación oficial de Hugging Face Inference Providers.

Configuración

Referencia completa de configuración.