Hugging Face (inferência)

O OpenClaw descobre modelos chamando diretamente o endpoint de Inference:

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

(Opcional: envie Authorization: Bearer $HUGGINGFACE_HUB_TOKEN ou $HF_TOKEN para a lista completa; alguns endpoints retornam um subconjunto sem autenticação.) A resposta é no estilo OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

Quando você configura uma chave de API do Hugging Face (via onboarding, HUGGINGFACE_HUB_TOKEN ou HF_TOKEN), o OpenClaw usa esse GET para descobrir os modelos de chat completion disponíveis. Durante a configuração interativa, depois que você informa seu token, aparece um dropdown Default Hugging Face model preenchido com essa lista (ou com o catálogo integrado se a requisição falhar). Em runtime (por exemplo, na inicialização do Gateway), quando uma chave está presente, o OpenClaw chama novamente GET https://router.huggingface.co/v1/models para atualizar o catálogo. A lista é mesclada com um catálogo integrado (para metadados como janela de contexto e custo). Se a requisição falhar ou nenhuma chave estiver definida, apenas o catálogo integrado é usado.

• Nome da API: o nome de exibição do modelo é hidratado a partir de GET /v1/models quando a API retorna name, title ou display_name; caso contrário, ele é derivado do ID do modelo (por exemplo, deepseek-ai/DeepSeek-R1 se torna "DeepSeek R1").
• Substituir nome de exibição: você pode definir um rótulo personalizado por modelo na configuração para que ele apareça da forma que quiser na CLI e na UI:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (rápido)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (barato)" },
      },
    },
  },
}

• Sufixos de política: a documentação e os helpers integrados do OpenClaw para Hugging Face atualmente tratam estes dois sufixos como variantes integradas de política:

  • :fastest — maior throughput.
  • :cheapest — menor custo por token de saída.

  Você pode adicioná-los como entradas separadas em models.providers.huggingface.models ou definir model.primary com o sufixo. Você também pode definir sua ordem padrão de provedor em Inference Provider settings (sem sufixo = usar essa ordem).

• Mesclagem de configuração: entradas existentes em models.providers.huggingface.models (por exemplo, em models.json) são mantidas quando a configuração é mesclada. Portanto, quaisquer name, alias ou opções de modelo personalizadas que você definir ali são preservadas.

Se o Gateway estiver em execução como daemon (launchd/systemd), certifique-se de que HUGGINGFACE_HUB_TOKEN ou HF_TOKEN esteja disponível para esse processo (por exemplo, em ~/.openclaw/.env ou via 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 (mais barato)" },
        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (mais 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" },
      },
    },
  },
}