Modelos locais

Modelos locais funcionam, mas elevam os requisitos de hardware, tamanho de contexto e defesa contra injeção de prompt: modelos pequenos ou quantizados de forma agressiva truncam o contexto e ignoram filtros de segurança do provedor. Esta página aborda pilhas locais de alto desempenho e servidores personalizados compatíveis com OpenAI. Para o caminho mais simples, 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.

Requisitos mínimos de hardware

Procure usar 2 ou mais Mac Studios com configuração máxima ou uma plataforma de GPU equivalente (cerca de US$ 30 mil ou mais) para obter um ciclo de agente confortável. Uma única GPU de 24 GB comporta apenas prompts mais leves, com maior latência. Sempre execute a maior variante ou a variante de tamanho completo que você puder hospedar — checkpoints pequenos ou fortemente quantizados aumentam o risco de injeção de prompt (consulte Segurança).

Escolha um backend

Use api: "openai-responses" quando o backend oferecer suporte a isso (o LM Studio oferece). Caso contrário, use api: "openai-completions". Se api for omitido em um provedor personalizado com um baseUrl, o OpenClaw usará openai-completions por padrão.

LM Studio + modelo local grande (API Responses)

Esta é a melhor pilha local disponível atualmente. Carregue um modelo grande no LM Studio (uma versão de tamanho completo do Qwen, DeepSeek ou Llama), habilite o servidor local (padrão: http://127.0.0.1:1234) e use a API Responses 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,          },        ],      },    },  },}

Lista de verificação da configuração:

• Instale o LM Studio: https://lmstudio.ai
• Baixe a maior versão de modelo disponível (evite variantes "small" ou fortemente quantizadas), inicie o servidor e confirme que http://127.0.0.1:1234/v1/models lista o modelo.
• Substitua my-local-model pelo ID real do modelo exibido no LM Studio.
• Mantenha o modelo carregado; o carregamento a frio aumenta a latência de inicialização.
• Ajuste contextWindow/maxTokens se a sua versão do LM Studio usar valores diferentes.
• Para WhatsApp, use a API Responses para que somente o texto final seja enviado.
• Mantenha models.mode: "merge" para que os modelos hospedados continuem disponíveis como alternativas.

Configuração híbrida: modelo hospedado principal e modelo local alternativo

{  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,          },        ],      },    },  },}

Para priorizar o modelo local com uma proteção hospedada, troque a ordem de primary/fallbacks e mantenha o mesmo bloco providers e models.mode: "merge".

Hospedagem regional / roteamento de dados

Variantes hospedadas do MiniMax/Kimi/GLM também estão disponíveis no OpenRouter com endpoints vinculados a regiões específicas (por exemplo, hospedados nos EUA). Escolha a variante regional para manter o tráfego na jurisdição desejada, mantendo models.mode: "merge" para alternativas da Anthropic/OpenAI. O uso exclusivamente local ainda é o caminho com maior privacidade; o roteamento regional hospedado é a opção intermediária quando você precisa dos recursos do provedor, mas deseja controlar o fluxo de dados.

Outros proxies locais compatíveis com OpenAI

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy ou qualquer Gateway personalizado funciona se expuser um endpoint /v1/chat/completions no estilo da OpenAI. Use openai-completions, a menos que o backend documente explicitamente o suporte a /v1/responses.

{  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,          },        ],      },    },  },}

As entradas de provedores personalizados/locais confiam na origem exata do baseUrl configurado para solicitações protegidas de modelos, incluindo hosts de loopback, LAN, tailnet e DNS privado. Origens de metadados/link-local são sempre bloqueadas, independentemente da configuração. Solicitações para outras origens privadas ainda exigem models.providers.<id>.request.allowPrivateNetwork: true; defina o sinalizador de confiança como false para desativar a confiança na origem exata.

models.providers.<id>.models[].id é local ao provedor — não inclua o prefixo do provedor. Para um servidor MLX iniciado com mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit:

• 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 acessados por proxy para que anexos de imagem sejam injetados nos turnos do agente. A integração interativa de provedores personalizados infere IDs comuns de modelos de visão e pergunta apenas sobre nomes desconhecidos; a integração não interativa usa a mesma inferência, com --custom-image-input / --custom-text-input para substituí-la.

Use models.providers.<id>.timeoutSeconds para servidores de modelos locais/remotos lentos antes de aumentar agents.defaults.timeoutSeconds. O tempo limite do provedor abrange a conexão, os cabeçalhos, o streaming do corpo e o cancelamento total da busca protegida somente para solicitações HTTP de modelos — se o tempo limite do agente/da execução for menor, aumente-o também, pois o tempo limite do provedor não pode estender toda a execução.

Observações sobre o comportamento de backends /v1 locais/acessados por proxy:

• O OpenClaw trata essas rotas como proxies compatíveis com OpenAI, não como endpoints nativos da OpenAI.
• A formatação de solicitações exclusiva da OpenAI nativa não se aplica: sem service_tier, sem store da API Responses, sem formatação de payload de compatibilidade de 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 em URLs de proxies personalizados.

Substituições de compatibilidade para backends compatíveis com OpenAI mais rigorosos:

• Conteúdo somente como string: alguns servidores aceitam apenas messages[].content como string, não matrizes estruturadas de partes de conteúdo. Defina models.providers.<provider>.models[].compat.requiresStringContent: true.

• Chaves de mensagem estritas: se o servidor rejeitar entradas de mensagem com mais que role/content, defina compat.strictMessageKeys: true.

• Texto de ferramenta entre colchetes: alguns modelos locais emitem solicitações de ferramenta independentes como texto entre colchetes, como [tool_name], seguido de JSON e [END_TOOL_REQUEST]. O OpenClaw as promove a chamadas reais de ferramenta somente quando o nome corresponde exatamente a uma ferramenta registrada para o turno; caso contrário, o conteúdo permanece como texto oculto e não compatível.

• Texto não estruturado semelhante a uma chamada de ferramenta: se um modelo emitir texto no estilo JSON/XML/ReAct que pareça uma chamada de ferramenta, mas não seja uma invocação estruturada, o OpenClaw o mantém como texto e registra um aviso com o ID da execução, provedor/modelo, padrão detectado e nome da ferramenta, quando disponível. Isso representa uma incompatibilidade do provedor/modelo, não uma execução de ferramenta concluída.

• Obrigatoriedade do uso de ferramentas: se as ferramentas aparecerem como texto do assistente (JSON/XML/ReAct bruto ou uma matriz tool_calls vazia), primeiro confirme se o modelo de chat/analisador do servidor oferece suporte a chamadas de ferramenta. Se o analisador funcionar somente quando o uso de ferramentas for obrigatório, substitua o valor padrão do proxy, tool_choice: "auto", por modelo:

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

  Use isso somente quando todos os turnos normais precisarem chamar uma ferramenta. Substitua local/my-local-model pela referência exata obtida em openclaw models list ou defina-a pela CLI:

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

• Níveis adicionais de esforço de raciocínio: se um modelo personalizado compatível com OpenAI aceitar níveis de esforço de raciocínio da OpenAI além do perfil integrado, declare-os no bloco de compatibilidade do modelo. Adicionar "xhigh" o disponibiliza para essa referência de modelo em /think xhigh, seletores de sessão, validação do Gateway e validação de llm-task:

  {  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 for carregado corretamente, mas os turnos completos do agente apresentarem comportamento incorreto, trabalhe de cima para baixo: primeiro confirme o transporte e depois restrinja a superfície.

1. Confirme que o modelo local responde — sem ferramentas, sem contexto do 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, ignorando a transcrição, a inicialização de AGENTS, a montagem do mecanismo de contexto, as ferramentas e os servidores MCP incluídos, mas ainda testa o roteamento do Gateway, a autenticação e a seleção do provedor:

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

3. Experimente o modo enxuto se ambas as sondagens forem bem-sucedidas, mas as interações reais do agente falharem com chamadas de ferramenta malformadas ou prompts grandes demais: defina agents.defaults.experimental.localModelLean: true. Ele remove ferramentas pesadas de navegador, cron, mensagens, geração de mídia, voz e PDF, a menos que sejam explicitamente necessárias, e coloca por padrão catálogos maiores de ferramentas atrás de controles estruturados de Pesquisa de Ferramentas, mantendo exec diretamente visível. Consulte Recursos experimentais -> Modo enxuto para modelos locais para obter detalhes e saber como confirmar que ele está ativado.

4. Desative completamente as ferramentas como último recurso definindo models.providers.<provider>.models[].compat.supportsTools: false para esse modelo — o agente então será executado sem chamadas de ferramenta.

5. Além disso, o gargalo está no sistema 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 está no próprio modelo ou servidor — janela de contexto, memória da GPU, remoção do cache KV ou um bug no backend — e não na camada de transporte do OpenClaw.

Solução de problemas

• O Gateway não consegue acessar o proxy? curl http://127.0.0.1:1234/v1/models.
• O modelo do LM Studio foi descarregado? Recarregue-o; uma inicialização a frio é uma causa comum de “travamento”.
• O servidor local informa terminated, ECONNRESET ou fecha o fluxo no meio da interação? O OpenClaw registra nos diagnósticos um model.call.error.failureKind de baixa cardinalidade, além de um instantâneo de RSS/heap do processo do OpenClaw. Para pressão de memória no LM Studio/Ollama, compare esse registro de data e hora com o log do servidor ou com um log de falha/jetsam do macOS para confirmar se o servidor do modelo foi encerrado.
• Erros de contexto? O OpenClaw deriva os limites da verificação preliminar da janela de contexto a partir da janela detectada do modelo (ou da janela limitada quando agents.defaults.contextTokens a reduz), emitindo um aviso abaixo de 20%, com um piso de 8k, e impondo um bloqueio abaixo de 10%, com um piso de 4k (limitado à janela de contexto efetiva para que metadados superdimensionados do modelo não rejeitem um limite válido definido pelo usuário). Reduza contextWindow ou aumente o limite de contexto do servidor/modelo.
• messages[].content ... expected a string? Adicione compat.requiresStringContent: true à entrada desse modelo.
• validation.keys ou “message entries only allow role and content”? Adicione compat.strictMessageKeys: true à entrada desse modelo.
• As chamadas diretas a /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 ignora completamente as ferramentas do agente. Se model run for bem-sucedido, mas interações maiores do agente falharem, reduza a superfície de ferramentas com localModelLean ou compat.supportsTools: false.
• As chamadas de ferramenta aparecem como texto JSON/XML/ReAct bruto ou o provedor retorna uma matriz tool_calls vazia? Não adicione um proxy que converta indiscriminadamente o texto do assistente em execução de ferramentas — primeiro corrija o modelo de chat/analisador do servidor. Se o modelo funcionar apenas quando o uso de ferramentas for obrigatório, adicione a substituição params.extra_body.tool_choice: "required" acima e use essa entrada de modelo somente em sessões nas quais se espera uma chamada de ferramenta em cada interação.
• Segurança: modelos locais ignoram os filtros do provedor. Mantenha os agentes com escopo restrito e a Compaction ativada para limitar o raio de impacto de injeções de prompt.

Conteúdo relacionado

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