Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Os Hugging Face Inference Providers oferecem chat completions compatíveis com OpenAI por meio de uma única API de roteamento. Você obtém acesso a muitos modelos (DeepSeek, Llama e mais) com um único token. O OpenClaw usa o endpoint compatível com OpenAI (apenas chat completions); para texto-para-imagem, embeddings ou fala, use diretamente os clientes de inferência da HF.
  • Provedor: huggingface
  • Auth: 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)
  • Cobrança: um único token HF; os preços seguem as tarifas do provedor com uma camada gratuita.

​
Primeiros passos

1

Criar um token de granularidade fina

Vá para Hugging Face Settings Tokens e crie um novo token de granularidade fina.
O token deve ter a permissão Make calls to Inference Providers habilitada, ou as requisições da API serão rejeitadas.
2

Executar o onboarding

Escolha Hugging Face no dropdown de provedor e então informe sua chave de API quando solicitado:
openclaw onboard --auth-choice huggingface-api-key
3

Selecionar um modelo padrão

No dropdown Default Hugging Face model, escolha o modelo que você quer. A lista é carregada da API de Inference quando você tem um token válido; caso contrário, uma lista integrada é mostrada. Sua escolha é salva como o modelo padrão.Você também pode definir ou alterar o modelo padrão depois na configuração:
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}
4

Verificar se o modelo está disponível

openclaw models list --provider huggingface

​
Configuração não interativa

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.

​
IDs de modelo

Refs 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.
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 anexar :fastest ou :cheapest a qualquer ID de 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.

​
Configuração avançada

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).
O OpenClaw aceita tanto HUGGINGFACE_HUB_TOKEN quanto HF_TOKEN como aliases de variável de ambiente. Qualquer um dos dois funciona; se ambos estiverem definidos, HUGGINGFACE_HUB_TOKEN tem precedência.
{
  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" },
      },
    },
  },
}

​
Relacionado

Seleção de modelo

Visão geral de todos os provedores, refs de modelo e comportamento de failover.

Seleção de modelo

Como escolher e configurar modelos.

Documentação de Inference Providers

Documentação oficial do Hugging Face Inference Providers.

Configuração

Referência completa de configuração.