Pular para o conteúdo principal

​
Hugging Face (Inference)

Os Hugging Face Inference Providers oferecem conclusões de chat compatíveis com OpenAI por meio de uma única API de roteador. Você tem acesso a muitos modelos (DeepSeek, Llama e mais) com um único token. O OpenClaw usa o endpoint compatível com OpenAI (apenas conclusões de chat); para texto para imagem, embeddings ou fala, use os clientes de inferência do HF diretamente.
  • Provedor: huggingface
  • Autenticação: HUGGINGFACE_HUB_TOKEN ou HF_TOKEN (token de granularidade fina com Make calls to Inference Providers)
  • API: compatível com OpenAI (https://router.huggingface.co/v1)
  • Faturamento: um único token HF; o preço segue as tarifas do provedor com uma camada gratuita.

​
Início rápido

  1. Crie um token de granularidade fina em Hugging Face → Settings → Tokens com a permissão Make calls to Inference Providers.
  2. Execute o onboarding e escolha Hugging Face no menu suspenso de provedor, depois informe sua chave de API quando solicitado:
openclaw onboard --auth-choice huggingface-api-key
  1. No menu suspenso Default Hugging Face model, escolha o modelo desejado (a lista é carregada da Inference API quando você tem um token válido; caso contrário, uma lista integrada é exibida). Sua escolha é salva como modelo padrão.
  2. Você também pode definir ou alterar o modelo padrão depois na configuração:
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

​
Exemplo não interativo

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
Isso definirá huggingface/deepseek-ai/DeepSeek-R1 como o modelo padrão.

​
Observação sobre ambiente

Se o Gateway for executado como daemon (launchd/systemd), verifique se HUGGINGFACE_HUB_TOKEN ou HF_TOKEN está disponível para esse processo (por exemplo, em ~/.openclaw/.env ou via env.shellEnv).

​
Descoberta de modelo e menu suspenso do onboarding

O OpenClaw descobre modelos chamando o endpoint de Inference diretamente: 
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 segue o 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 conclusão de chat disponíveis. Durante a configuração interativa, depois de informar seu token, você vê um menu suspenso 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 será usado.

​
Nomes de modelo e opções editáveis

  • Nome da API: O nome de exibição do modelo é preenchido 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 → “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 desejada na CLI e na UI:
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}
  • Sufixos de política: A documentação e os auxiliares empacotados do Hugging Face no OpenClaw atualmente tratam estes dois sufixos como variantes de política integradas:
    • :fastest — maior taxa de transferência.
    • :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, qualquer name, alias ou opção de modelo personalizada definida ali é preservada.

​
IDs de modelo e exemplos de configuração

As referências de modelo usam o formato huggingface/<org>/<model> (IDs no estilo Hub). A lista abaixo vem de GET https://router.huggingface.co/v1/models; seu catálogo pode incluir mais. Exemplos de IDs (do endpoint de inferência):
ModeloRef (prefixe com 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
Você pode acrescentar :fastest ou :cheapest ao id do modelo. Defina sua ordem padrão em Inference Provider settings; consulte Inference Providers e GET https://router.huggingface.co/v1/models para a lista completa.

​
Exemplos completos de configuração

DeepSeek R1 principal com fallback para 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 padrão, com variantes :cheapest e :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 com aliases: 
{
  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" },
      },
    },
  },
}
Vários modelos Qwen e DeepSeek com sufixos 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" },
      },
    },
  },
}