Saltar al contenido principal

​
Hugging Face (Inference)

Los Hugging Face Inference Providers ofrecen chat completions compatibles con OpenAI mediante una sola API de enrutador. Obtienes acceso a muchos modelos (DeepSeek, Llama y más) con un único token. OpenClaw usa el endpoint compatible con OpenAI (solo chat completions); para texto a imagen, embeddings o voz, usa directamente los clientes de inferencia de HF.
  • Proveedor: huggingface
  • Autenticación: HUGGINGFACE_HUB_TOKEN o HF_TOKEN (token de granularidad fina con Make calls to Inference Providers)
  • API: compatible con OpenAI (https://router.huggingface.co/v1)
  • Facturación: un único token de HF; el precio sigue las tarifas del proveedor con un nivel gratuito.

​
Inicio rápido

  1. Crea un token de granularidad fina en Hugging Face → Settings → Tokens con el permiso Make calls to Inference Providers.
  2. Ejecuta el onboarding y elige Hugging Face en el desplegable del proveedor; luego introduce tu clave API cuando se te solicite:
openclaw onboard --auth-choice huggingface-api-key
  1. En el desplegable Default Hugging Face model, elige el modelo que quieras (la lista se carga desde la API de Inference cuando tienes un token válido; de lo contrario, se muestra una lista integrada). Tu elección se guarda como modelo predeterminado.
  2. También puedes establecer o cambiar el modelo predeterminado más adelante en la configuración:
{
  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 establecerá huggingface/deepseek-ai/DeepSeek-R1 como modelo predeterminado.

​
Nota sobre el entorno

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

​
Descubrimiento de modelos y desplegable del onboarding

OpenClaw descubre modelos llamando directamente al endpoint de Inference: 
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 API de Hugging Face (mediante onboarding, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), OpenClaw usa este GET para descubrir los modelos de chat-completion disponibles. Durante la configuración interactiva, después de introducir tu token ves un desplegable Default Hugging Face model rellenado a partir de esa lista (o del 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 ventana de contexto y costo). Si la solicitud falla o no hay ninguna clave configurada, solo se usa el catálogo integrado.

​
Nombres de modelos y opciones editables

  • Nombre desde la API: El nombre para mostrar del modelo se hidrata desde GET /v1/models cuando la API devuelve name, title o display_name; en caso contrario, se deriva del id del modelo (por ejemplo, deepseek-ai/DeepSeek-R1 → “DeepSeek R1”).
  • Anular el nombre para mostrar: Puedes establecer una etiqueta personalizada por modelo en la configuración para que aparezca como quieras en la CLI y la IU:
{
  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 los helpers integrados de OpenClaw para Hugging Face tratan actualmente estos dos sufijos como variantes de política integradas:
    • :fastest — máximo rendimiento.
    • :cheapest — menor costo por token de salida.
    Puedes añadirlos como entradas separadas en models.providers.huggingface.models o establecer model.primary con el sufijo. También puedes definir tu orden predeterminado de proveedor en Inference Provider settings (sin sufijo = usar ese orden).
  • Fusión de configuración: Las entradas existentes en models.providers.huggingface.models (por ejemplo, en models.json) se conservan cuando se fusiona la configuración. Así que cualquier name, alias u opción de modelo personalizada que establezcas allí se preserva.

​
IDs de modelo y ejemplos de configuración

Las referencias de modelo usan la forma huggingface/<org>/<model> (IDs de estilo Hub). La lista siguiente procede de GET https://router.huggingface.co/v1/models; tu catálogo puede incluir más. IDs de ejemplo (del endpoint de inferencia):
ModeloRef (anteponer huggingface/)
DeepSeek R1deepseek-ai/DeepSeek-R1
DeepSeek V3.2deepseek-ai/DeepSeek-V3.2
Qwen3 8BQwen/Qwen3-8B
Qwen2.5 7B InstructQwen/Qwen2.5-7B-Instruct
Qwen3 32BQwen/Qwen3-32B
Llama 3.3 70B Instructmeta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instructmeta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120Bopenai/gpt-oss-120b
GLM 4.7zai-org/GLM-4.7
Kimi K2.5moonshotai/Kimi-K2.5
Puedes añadir :fastest o :cheapest al id del 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.

​
Ejemplos completos de configuración

DeepSeek R1 como primario con respaldo de 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" },
      },
    },
  },
}
Qwen como predeterminado, 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" },
      },
    },
  },
}
Varios modelos 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" },
      },
    },
  },
}