Nesta página
Nesta página
Providers
Hugging Face (inferência)
O Hugging Face Inference Providers disponibiliza um roteador de conclusões de chat compatível com a OpenAI para diversos modelos hospedados (DeepSeek, Llama e outros), usando um único token. O OpenClaw se comunica somente com o endpoint de conclusões de chat; para conversão de texto em imagem, embeddings ou fala, use diretamente os clientes de inferência da HF.
| Propriedade | Valor |
|---|---|
| ID do provedor | huggingface |
| Plugin | incluído (habilitado por padrão, sem etapa de instalação) |
| Variável de ambiente de autenticação | HUGGINGFACE_HUB_TOKEN ou HF_TOKEN (token de granularidade fina) |
| API | Compatível com a OpenAI (https://router.huggingface.co/v1) |
| Cobrança | Um único token da HF; os preços seguem as tarifas do provedor, com uma faixa gratuita |
Primeiros passos
Create a fine-grained token
Acesse Hugging Face Settings Tokens e crie um novo token de granularidade fina.
Run onboarding
Escolha Hugging Face no menu suspenso de provedores e insira sua chave de API quando solicitado:
Select a default model
No menu suspenso Modelo padrão do Hugging Face, escolha um modelo. A lista é carregada pela API de inferência quando seu token é válido; caso contrário, o OpenClaw exibe o catálogo integrado abaixo. Sua escolha é salva como agents.defaults.model.primary:
Verify the model is available
Configuração não interativa
Define huggingface/deepseek-ai/DeepSeek-R1 como o modelo padrão.
IDs de modelos
As referências de modelos usam o formato huggingface/<org>/<model> (IDs no estilo do Hub). Catálogo integrado do OpenClaw:
| Modelo | Referência (com o prefixo huggingface/) |
|---|---|
| DeepSeek R1 | deepseek-ai/DeepSeek-R1 |
| DeepSeek V3.1 | deepseek-ai/DeepSeek-V3.1 |
| GPT-OSS 120B | openai/gpt-oss-120b |
| Llama 3.3 70B Instruct Turbo | meta-llama/Llama-3.3-70B-Instruct-Turbo |
Configuração avançada
Model discovery and onboarding dropdown
O OpenClaw descobre modelos com:
A resposta segue o estilo da OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.
Com uma chave configurada (na integração inicial, em HUGGINGFACE_HUB_TOKEN ou em HF_TOKEN), o menu suspenso Modelo padrão do Hugging Face durante a configuração interativa é preenchido por esse endpoint. A inicialização do Gateway repete a mesma chamada para atualizar o catálogo. Os modelos descobertos são combinados com o catálogo integrado acima (usado para metadados como janela de contexto e custo quando há correspondência de ID). Se a solicitação falhar, não retornar dados ou nenhuma chave estiver definida, o OpenClaw usará somente o catálogo integrado.
Desabilite a descoberta sem remover o provedor:
Model names, aliases, and policy suffixes
- Nome da API: os modelos descobertos usam
name,titleoudisplay_nameda API quando disponíveis; caso contrário, o OpenClaw deriva um nome do ID do modelo (por exemplo,deepseek-ai/DeepSeek-R1se torna "DeepSeek R1"). - Substituir o nome de exibição: defina um rótulo personalizado por modelo na configuração:
- Sufixos de política:
:fasteste:cheapestsão convenções do roteador da HF, não algo que o OpenClaw reescreva: o sufixo é enviado literalmente como parte do ID do modelo, e o roteador da HF escolhe o provedor de inferência correspondente. Adicione cada variante como uma entrada própria emmodels.providers.huggingface.models(ou emmodel.primary) caso queira um alias diferente para cada sufixo. - Mesclagem da configuração: as entradas existentes em
models.providers.huggingface.models(por exemplo, emmodels.json) são mantidas durante a mesclagem da configuração, portanto qualquername,aliasou opção de modelo personalizada definida ali persiste entre reinicializações.
Environment and daemon setup
Se o Gateway for executado como um daemon (launchd/systemd), verifique se HUGGINGFACE_HUB_TOKEN ou HF_TOKEN está disponível para esse processo (por exemplo, em ~/.openclaw/.env ou por meio de env.shellEnv).
