Hugging Face (inference)

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 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 incorporación, HUGGINGFACE_HUB_TOKEN o HF_TOKEN), OpenClaw usa este GET para descubrir modelos disponibles de chat completion. Durante la configuración interactiva, después de introducir tu token ves un desplegable Default Hugging Face model rellenado con esa lista (o con 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 ventana de contexto y coste). Si la solicitud falla o no se establece ninguna clave, solo se usa el catálogo integrado.

• Nombre desde API: el nombre visible 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 pasa a ser "DeepSeek R1").
• Sobrescribir nombre visible: 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 (rápido)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (barato)" },
      },
    },
  },
}

• Sufijos de política: la documentación y las ayudas integradas de Hugging Face en OpenClaw actualmente tratan estos dos sufijos como variantes integradas de política:

  • :fastest — mayor rendimiento.
  • :cheapest — menor coste por token de salida.

  Puedes agregarlos 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 ahí se preserva.

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

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

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen3-8B" },
      models: {
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
        "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (más barato)" },
        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (más rápido)" },
      },
    },
  },
}

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

{
  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 (barato)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (rápido)" },
        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
      },
    },
  },
}