Providers
Infere
inferrs disponibiliza modelos locais por meio de uma API /v1 compatível com a OpenAI. O OpenClaw se comunica com ele por meio do adaptador genérico openai-completions.
| Propriedade | Valor |
|---|---|
| ID do provedor | inferrs (personalizado; configure em models.providers.inferrs) |
| Plugin | nenhum — não é um plugin de provedor incluído no OpenClaw |
| Var. de amb. de autenticação | nenhuma obrigatória; qualquer valor funciona se o servidor inferrs não tiver autenticação |
| API | compatível com a OpenAI (openai-completions) |
| URL base sugerida | http://127.0.0.1:8080/v1 (ou onde quer que o servidor inferrs esteja escutando) |
Primeiros passos
Inicie o inferrs com um modelo
inferrs serve google/gemma-4-E2B-it \ --host 127.0.0.1 \ --port 8080 \ --device metalVerifique se o servidor está acessível
curl http://127.0.0.1:8080/healthcurl http://127.0.0.1:8080/v1/modelsAdicione uma entrada de provedor do OpenClaw
Adicione uma entrada explícita de provedor e aponte seu modelo padrão para ela. Consulte o exemplo de configuração abaixo.
Exemplo de configuração completa
Gemma 4 em um servidor inferrs local:
{ agents: { defaults: { model: { primary: "inferrs/google/gemma-4-E2B-it" }, models: { "inferrs/google/gemma-4-E2B-it": { alias: "Gemma 4 (inferrs)", }, }, }, }, models: { mode: "merge", providers: { inferrs: { baseUrl: "http://127.0.0.1:8080/v1", apiKey: "inferrs-local", api: "openai-completions", models: [ { id: "google/gemma-4-E2B-it", name: "Gemma 4 E2B (inferrs)", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 4096, compat: { requiresStringContent: true, }, }, ], }, }, },}Inicialização sob demanda
O OpenClaw pode iniciar o próprio inferrs somente quando um modelo inferrs/... estiver selecionado. Adicione localService à mesma entrada de provedor:
{ models: { providers: { inferrs: { baseUrl: "http://127.0.0.1:8080/v1", apiKey: "inferrs-local", api: "openai-completions", timeoutSeconds: 300, localService: { command: "/opt/homebrew/bin/inferrs", args: [ "serve", "google/gemma-4-E2B-it", "--host", "127.0.0.1", "--port", "8080", "--device", "metal", ], healthUrl: "http://127.0.0.1:8080/v1/models", readyTimeoutMs: 180000, idleStopMs: 0, }, models: [ { id: "google/gemma-4-E2B-it", name: "Gemma 4 E2B (inferrs)", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 131072, maxTokens: 4096, compat: { requiresStringContent: true, }, }, ], }, }, },}command deve ser um caminho absoluto. Execute which inferrs no host do Gateway e use esse caminho. Referência completa dos campos: Serviços de modelos locais.
Configuração avançada
Por que requiresStringContent é importante
Algumas rotas de Chat Completions do inferrs aceitam apenas valores de string em messages[].content, e não matrizes estruturadas de partes de conteúdo.
Ressalva sobre o Gemma e o esquema de ferramentas
Algumas combinações de inferrs + Gemma aceitam pequenas solicitações diretas para /v1/chat/completions, mas falham em turnos completos do runtime de agentes do OpenClaw. Primeiro, tente desabilitar a superfície do esquema de ferramentas:
compat: { requiresStringContent: true, supportsTools: false}Isso reduz a pressão do prompt sobre backends locais mais rigorosos. Se pequenas solicitações diretas ainda funcionarem, mas turnos normais de agentes do OpenClaw continuarem causando falhas no inferrs, considere isso uma limitação do modelo ou servidor upstream, e não um problema de transporte do OpenClaw.
Teste de fumaça manual
Teste as duas camadas após a configuração:
curl http://127.0.0.1:8080/v1/chat/completions \ -H 'content-type: application/json' \ -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'openclaw infer model run \ --model inferrs/google/gemma-4-E2B-it \ --prompt "What is 2 + 2? Reply with one short sentence." \ --jsonSe o primeiro comando funcionar, mas o segundo falhar, consulte a seção Solução de problemas abaixo.
Comportamento semelhante a proxy
Como o inferrs usa o adaptador genérico openai-completions (e não openai-responses), a formatação de solicitações exclusiva da OpenAI nativa nunca é aplicada: nenhum service_tier, nenhum store da Responses, nenhuma dica de cache de prompt e nenhuma formatação de payload de compatibilidade de raciocínio da OpenAI são enviados.
Solução de problemas
curl /v1/models falha
O inferrs não está em execução, não está acessível ou não está vinculado ao host/porta que você configurou. Confirme se o servidor foi iniciado e está escutando nesse endereço.
messages[].content esperava uma string
Defina compat.requiresStringContent: true na entrada do modelo (consulte acima).
Chamadas diretas para /v1/chat/completions funcionam, mas openclaw infer model run falha
Defina compat.supportsTools: false para desabilitar a superfície do esquema de ferramentas (consulte a ressalva sobre o Gemma acima).
O inferrs ainda falha em turnos maiores de agentes
Se os erros de esquema desaparecerem, mas o inferrs ainda falhar em turnos maiores de agentes, considere isso uma limitação upstream do inferrs ou do modelo. Reduza a pressão do prompt ou troque de backend/modelo.
Relacionados
Execução do OpenClaw com servidores de modelos locais.
Inicialização sob demanda de servidores de modelos locais para provedores configurados.
Depuração de backends locais compatíveis com a OpenAI que passam nas verificações, mas falham nas execuções de agentes.
Visão geral de todos os provedores, referências de modelos e comportamento de failover.
