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

Providers

Hugging Face (inferencia)

Hugging Face Inference Providers ofrece un enrutador de finalizaciones de chat compatible con OpenAI para numerosos modelos alojados (DeepSeek, Llama y otros) mediante un único token. OpenClaw se comunica únicamente con el endpoint de finalizaciones de chat; para texto a imagen, embeddings o voz, utiliza 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 con permisos específicos)
API Compatible con OpenAI (https://router.huggingface.co/v1)
Facturación Un único token de HF; los precios siguen las tarifas del proveedor e incluyen un nivel gratuito

Primeros pasos

  • Crear un token con permisos específicos

    Ve a Hugging Face Settings Tokens y crea un nuevo token con permisos específicos.

  • Ejecutar la incorporación

    Elige Hugging Face en la lista desplegable de proveedores y, cuando se te solicite, introduce tu clave de API:

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

  • Seleccionar un modelo predeterminado

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

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

  • Verificar que el modelo esté disponible

    bash
    openclaw models list --provider huggingface

    • Configuración no interactiva

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

    Identificadores de modelos

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

    Modelo Referencia (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
    Llama 3.3 70B Instruct Turbo meta-llama/Llama-3.3-70B-Instruct-Turbo

    Configuración avanzada

    Descubrimiento de modelos y lista desplegable de incorporación

    OpenClaw descubre modelos mediante:

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

    La respuesta sigue el formato de OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

    Con una clave configurada (mediante la incorporación, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), la lista desplegable Default Hugging Face model de la configuración interactiva se rellena desde este endpoint. Al iniciarse, el Gateway repite la misma llamada para actualizar el catálogo. Los modelos descubiertos se combinan con el catálogo integrado anterior (que se utiliza para metadatos como la ventana de contexto y el coste cuando coincide un identificador). Si la solicitud falla, no devuelve datos o no se ha definido ninguna clave, OpenClaw utiliza únicamente el catálogo integrado.

    Deshabilita el descubrimiento sin eliminar el proveedor:

    bash
    openclaw config set plugins.entries.huggingface.config.discovery.enabled false
    Nombres de modelos, alias y sufijos de política
    • Nombre procedente de la API: los modelos descubiertos utilizan el valor name, title o display_name de la API cuando está disponible; de lo contrario, OpenClaw deriva un nombre del identificador del modelo (por ejemplo, deepseek-ai/DeepSeek-R1 se convierte en "DeepSeek R1").
    • Sobrescribir el nombre mostrado: define una etiqueta personalizada para cada modelo en la configuración:
    json5
    {  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: :fastest y :cheapest son convenciones del enrutador de HF, no elementos que OpenClaw reescriba: el sufijo se envía literalmente como parte del identificador del modelo y el enrutador de HF selecciona el proveedor de inferencia correspondiente. Añade cada variante como una entrada independiente en models.providers.huggingface.models (o en model.primary) si quieres 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 valor personalizado de name, alias u opción de modelo que definas allí persiste entre reinicios.
    Configuración del entorno y del daemon

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

    Configuración: DeepSeek R1 con modelo 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" },      },    },  },}
    Configuración: DeepSeek con las variantes más barata y más rápida
    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)" },      },    },  },}
    Configuración: 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" },      },    },  },}

    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 Inference Providers

    Documentación oficial de Hugging Face Inference Providers.
    Configuración

    Referencia completa de la configuración.
    Was this useful?
    On this page

    On this page