Modelos locais

Modelos locais são viáveis. Eles também elevam a exigência de hardware, tamanho de contexto e defesa contra injeção de prompt — placas pequenas ou agressivamente quantizadas truncam o contexto e comprometem a segurança. Esta página é o guia opinativo para stacks locais de alto desempenho e servidores locais personalizados compatíveis com OpenAI. Para o onboarding com menos atrito, comece com LM Studio ou Ollama e openclaw onboard.

Para servidores locais que devem iniciar somente quando um modelo selecionado precisar deles, consulte Serviços de modelos locais.

Piso de hardware

Mire alto: ≥2 Mac Studios no máximo ou um rig de GPU equivalente (~US$ 30 mil+) para um loop de agente confortável. Uma única GPU de 24 GB funciona apenas para prompts mais leves com maior latência. Sempre execute a maior variante / variante em tamanho completo que você conseguir hospedar; checkpoints pequenos ou fortemente quantizados aumentam o risco de injeção de prompt (consulte Segurança).

Escolha um backend

Use Responses API (api: "openai-responses") quando o backend oferecer suporte a ela (o LM Studio oferece). Caso contrário, use Chat Completions (api: "openai-completions").

Recomendado: LM Studio + modelo local grande (Responses API)

Melhor stack local atual. Carregue um modelo grande no LM Studio (por exemplo, uma build em tamanho completo do Qwen, DeepSeek ou Llama), habilite o servidor local (padrão http://127.0.0.1:1234) e use Responses API para manter o raciocínio separado do texto final.

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "lmstudio/my-local-model": { alias: "Local" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Checklist de configuração

• Instale o LM Studio: https://lmstudio.ai
• No LM Studio, baixe a maior build de modelo disponível (evite variantes "small"/fortemente quantizadas), inicie o servidor e confirme que http://127.0.0.1:1234/v1/models a lista.
• Substitua my-local-model pelo ID real do modelo exibido no LM Studio.
• Mantenha o modelo carregado; o carregamento a frio adiciona latência de inicialização.
• Ajuste contextWindow/maxTokens se sua build do LM Studio for diferente.
• Para WhatsApp, mantenha Responses API para que somente o texto final seja enviado.

Mantenha modelos hospedados configurados mesmo ao executar localmente; use models.mode: "merge" para que fallbacks continuem disponíveis.

Configuração híbrida: primário hospedado, fallback local

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "lmstudio/my-local-model": { alias: "Local" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Local primeiro com rede de segurança hospedada

Troque a ordem do primário e do fallback; mantenha o mesmo bloco de provedores e models.mode: "merge" para poder recorrer ao Sonnet ou ao Opus quando a máquina local estiver fora do ar.

Hospedagem regional / roteamento de dados

• Variantes hospedadas do MiniMax/Kimi/GLM também existem no OpenRouter com endpoints fixados por região (por exemplo, hospedados nos EUA). Escolha a variante regional lá para manter o tráfego na jurisdição escolhida enquanto ainda usa models.mode: "merge" para fallbacks da Anthropic/OpenAI.
• Somente local continua sendo o caminho de privacidade mais forte; roteamento regional hospedado é o meio-termo quando você precisa de recursos do provedor, mas quer controle sobre o fluxo de dados.

Outros proxies locais compatíveis com OpenAI

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um endpoint /v1/chat/completions no estilo OpenAI. Use o adaptador de Chat Completions a menos que o backend documente explicitamente suporte a /v1/responses. Substitua o bloco de provedor acima pelo seu endpoint e ID de modelo:

{  agents: {    defaults: {      model: { primary: "local/my-local-model" },    },  },  models: {    mode: "merge",    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 120000,            maxTokens: 8192,          },        ],      },    },  },}

Se api for omitido em um provedor personalizado com um baseUrl, o OpenClaw usa openai-completions por padrão. Entradas de provedor personalizadas/locais confiam na origem baseUrl exata configurada para solicitações de modelo protegidas, incluindo loopback, LAN, tailnet e hosts DNS privados. Solicitações para outras origens privadas ainda precisam de request.allowPrivateNetwork: true; origens de metadados/link-local continuam bloqueadas sem opt-in explícito. Defina como false para sair da confiança por origem exata.

O valor models.providers.<id>.models[].id é local ao provedor. Não inclua o prefixo do provedor ali. Por exemplo, um servidor MLX iniciado com mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit deve usar este ID de catálogo e referência de modelo:

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

Defina input: ["text", "image"] em modelos de visão locais ou intermediados por proxy para que anexos de imagem sejam injetados nas interações do agente. O onboarding interativo de provedor personalizado infere IDs comuns de modelos de visão e pergunta somente sobre nomes desconhecidos. O onboarding não interativo usa a mesma inferência; use --custom-image-input para IDs de visão desconhecidos ou --custom-text-input quando um modelo com aparência conhecida for somente texto atrás do seu endpoint.

Mantenha models.mode: "merge" para que modelos hospedados continuem disponíveis como fallbacks. Use models.providers.<id>.timeoutSeconds para servidores de modelo locais ou remotos lentos antes de aumentar agents.defaults.timeoutSeconds. O timeout do provedor se aplica apenas a solicitações HTTP do modelo, incluindo conexão, cabeçalhos, streaming do corpo e o abort total do guarded-fetch. Se o timeout do agente ou da execução for menor, aumente esse teto também, porque timeouts de provedor não conseguem estender toda a execução do agente.

Nota de comportamento para backends /v1 locais/intermediados por proxy:

• O OpenClaw trata esses endpoints como rotas compatíveis com OpenAI em estilo proxy, não como endpoints nativos da OpenAI
• a modelagem de solicitação exclusiva da OpenAI nativa não se aplica aqui: sem service_tier, sem Responses store, sem modelagem de payload de compatibilidade com raciocínio da OpenAI e sem dicas de cache de prompt
• cabeçalhos ocultos de atribuição do OpenClaw (originator, version, User-Agent) não são injetados nesses URLs de proxy personalizados

Notas de compatibilidade para backends compatíveis com OpenAI mais rigorosos:

• Alguns servidores aceitam apenas messages[].content como string em Chat Completions, não arrays estruturados de partes de conteúdo. Defina models.providers.<provider>.models[].compat.requiresStringContent: true para esses endpoints.

• Alguns modelos locais emitem solicitações de ferramenta autônomas entre colchetes como texto, como [tool_name] seguido por JSON e [END_TOOL_REQUEST]. O OpenClaw promove essas solicitações para chamadas de ferramenta reais somente quando o nome corresponde exatamente a uma ferramenta registrada para a interação; caso contrário, o bloco é tratado como texto sem suporte e fica oculto das respostas visíveis ao usuário.

• Se um modelo emitir JSON, XML ou texto em estilo ReAct que pareça uma chamada de ferramenta, mas o provedor não emitiu uma invocação estruturada, o OpenClaw o deixa como texto e registra um aviso com o ID da execução, provedor/modelo, padrão detectado e nome da ferramenta quando disponível. Trate isso como incompatibilidade de chamada de ferramenta do provedor/modelo, não como uma execução de ferramenta concluída.

• Se ferramentas aparecerem como texto do assistant em vez de serem executadas, por exemplo JSON bruto, XML, sintaxe ReAct ou um array tool_calls vazio na resposta do provedor, primeiro verifique se o servidor está usando um template/parser de chat compatível com chamadas de ferramenta. Para backends de Chat Completions compatíveis com OpenAI cujo parser funciona somente quando o uso de ferramentas é forçado, defina uma substituição de solicitação por modelo em vez de depender da análise de texto:

  {  agents: {    defaults: {      models: {        "local/my-local-model": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

  Use isso somente para modelos/sessões em que toda interação normal deve chamar uma ferramenta. Isso substitui o valor proxy padrão do OpenClaw de tool_choice: "auto". Substitua local/my-local-model pela referência exata de provedor/modelo mostrada por openclaw models list.

  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

• Se um modelo personalizado compatível com OpenAI aceitar esforços de raciocínio da OpenAI além do perfil integrado, declare-os no bloco de compatibilidade do modelo. Adicionar "xhigh" aqui faz com que /think xhigh, seletores de sessão, validação do Gateway e validação de llm-task exponham o nível para essa referência configurada de provedor/modelo:

  {  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-responses",        models: [          {            id: "gpt-5.4",            name: "GPT 5.4 via local proxy",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,            compat: {              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],              reasoningEffortMap: { xhigh: "xhigh" },            },          },        ],      },    },  },}

Backends menores ou mais rigorosos

Se o modelo carregar corretamente, mas turnos completos do agente se comportarem mal, trabalhe de cima para baixo: confirme o transporte primeiro e depois reduza a superfície.

1. Confirme que o próprio modelo local responde. Sem ferramentas, sem contexto de agente:

   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json

2. Confirme o roteamento do Gateway. Envia apenas o prompt fornecido: ignora transcrição, bootstrap de AGENTS, montagem do mecanismo de contexto, ferramentas e servidores MCP empacotados, mas ainda exercita o roteamento do Gateway, autenticação e seleção de provedor:

   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json

3. Experimente o modo enxuto. Se ambas as sondagens passarem, mas turnos reais do agente falharem com chamadas de ferramenta malformadas ou prompts grandes demais, habilite agents.defaults.experimental.localModelLean: true. Ele remove as três ferramentas padrão mais pesadas (browser, cron, message) e coloca catálogos de ferramentas maiores atrás de controles estruturados de Busca de ferramentas, exceto em execuções que precisam manter a semântica de entrega direta de message. Consulte Recursos experimentais → Modo enxuto para modelo local para a explicação completa, quando usá-lo e como confirmar que ele está ativo.

4. Desabilite totalmente as ferramentas como último recurso. Se o modo enxuto não for suficiente, defina models.providers.<provider>.models[].compat.supportsTools: false para essa entrada de modelo. O agente então operará sem chamadas de ferramenta nesse modelo.

5. Depois disso, o gargalo está no upstream. Se o backend ainda falhar apenas em execuções maiores do OpenClaw após o modo enxuto e supportsTools: false, o problema restante geralmente é capacidade do modelo ou servidor upstream: janela de contexto, memória de GPU, remoção de kv-cache ou um bug do backend. Nesse ponto, não é a camada de transporte do OpenClaw.

Solução de problemas

• O Gateway consegue acessar o proxy? curl http://127.0.0.1:1234/v1/models.
• Modelo do LM Studio descarregado? Recarregue; inicialização a frio é uma causa comum de “travamento”.
• O servidor local informa terminated, ECONNRESET ou fecha o stream no meio do turno? O OpenClaw registra um model.call.error.failureKind de baixa cardinalidade mais o snapshot de RSS/heap do processo OpenClaw nos diagnósticos. Para pressão de memória no LM Studio/Ollama, compare esse timestamp com o log do servidor ou o log de crash / jetsam do macOS para confirmar se o servidor de modelo foi encerrado.
• O OpenClaw deriva os limites de pré-verificação da janela de contexto a partir da janela detectada do modelo, ou da janela de modelo sem limite quando agents.defaults.contextTokens reduz a janela efetiva. Ele avisa abaixo de 20%, com piso de 8k. Bloqueios rígidos usam o limite de 10%, com piso de 4k, limitado à janela de contexto efetiva para que metadados de modelo grandes demais não rejeitem um limite de usuário que seria válido. Se você atingir essa pré-verificação, aumente o limite de contexto do servidor/modelo ou escolha um modelo maior.
• Erros de contexto? Reduza contextWindow ou aumente o limite do seu servidor.
• Servidor compatível com OpenAI retorna messages[].content ... expected a string? Adicione compat.requiresStringContent: true nessa entrada de modelo.
• Servidor compatível com OpenAI retorna validation.keys ou diz que entradas de mensagem permitem apenas role e content? Adicione compat.strictMessageKeys: true nessa entrada de modelo.
• Chamadas diretas minúsculas para /v1/chat/completions funcionam, mas openclaw infer model run --local falha no Gemma ou em outro modelo local? Verifique primeiro a URL do provedor, a referência do modelo, o marcador de autenticação e os logs do servidor; model run local não inclui ferramentas de agente. Se o model run local tiver sucesso, mas turnos maiores do agente falharem, reduza a superfície de ferramentas do agente com localModelLean ou compat.supportsTools: false.
• Chamadas de ferramenta aparecem como texto JSON/XML/ReAct bruto, ou o provedor retorna um array tool_calls vazio? Não adicione um proxy que converta cegamente texto do assistente em execução de ferramenta. Corrija primeiro o template/parser de chat do servidor. Se o modelo só funcionar quando o uso de ferramentas for forçado, adicione a substituição por modelo params.extra_body.tool_choice: "required" acima e use essa entrada de modelo apenas para sessões em que uma chamada de ferramenta é esperada em todo turno.
• Segurança: modelos locais pulam filtros do lado do provedor; mantenha agentes restritos e Compaction ativada para limitar o raio de impacto de injeção de prompt.

Relacionados

• Referência de configuração
• Failover de modelo