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)

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.

  • Ejecutar la incorporación

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

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

    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.

    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

    Configuración avanzada

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

    OpenClaw detecta los modelos mediante:

    bash
    GET https://router.huggingface.co/v1/modelsAuthorization: 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:

    bash
    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:
    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í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).

    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 + GPT-OSS con alias
    json5
    {  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.
    Was this useful?
    On this page

    On this page