Modelos locais

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.

​

Piso de hardware

​

Escolha um backend

​

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

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

• 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 mostrado no LM Studio.
• Mantenha o modelo carregado; carregamento a frio adiciona latência de inicialização.
• Ajuste contextWindow/maxTokens se a sua build do LM Studio for diferente.
• Para WhatsApp, mantenha a API Responses para que somente o texto final seja enviado.

​

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

​

Hospedagem regional / roteamento de dados

• Variantes MiniMax/Kimi/GLM hospedadas 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, ainda usando models.mode: "merge" para fallbacks da Anthropic/OpenAI.
• Somente local continua sendo o caminho mais forte de privacidade; 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

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

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

• O OpenClaw trata esses backends como rotas compatíveis com OpenAI no estilo proxy, não como endpoints nativos da OpenAI
• a formatação de requisições exclusiva da OpenAI nativa não se aplica aqui: sem service_tier, sem store de 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 nesses URLs de proxy personalizados

• Alguns servidores aceitam apenas messages[].content em 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 entre colchetes independentes como texto, como [tool_name] seguido por JSON e [END_TOOL_REQUEST]. O OpenClaw promove isso para chamadas de ferramenta reais somente quando o nome corresponde exatamente a uma ferramenta registrada para a rodada; 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 no estilo ReAct que pareça uma chamada de ferramenta, mas o provedor não tiver emitido 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. 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 assistente em vez de executarem, 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 chamada de ferramenta. Para backends Chat Completions compatíveis com OpenAI cujo parser funciona apenas quando o uso de ferramenta é forçado, defina uma substituição de requisição por modelo em vez de depender de parsing de texto:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Use isso apenas para modelos/sessões em que toda rodada normal deve chamar uma ferramenta. Isso substitui o valor padrão de proxy do OpenClaw de tool_choice: "auto". Substitua local/my-local-model pela ref 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 ref de provedor/modelo configurada:
  {
    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 estritos

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 incluídos, 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) para que o formato do prompt seja menor e menos frágil. Consulte Recursos experimentais → Modo enxuto para modelo local para a explicação completa, quando usá-lo e como confirmar que ele está ativado.
4. Desabilite completamente 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. Além disso, o gargalo está no upstream. Se o backend ainda falhar apenas em execuções maiores do OpenClaw depois do modo enxuto e de supportsTools: false, o problema restante geralmente é capacidade do modelo ou servidor upstream — janela de contexto, memória da GPU, remoção de kv-cache ou um bug no backend. Nesse ponto, não é a camada de transporte do OpenClaw.

​

Solução de problemas

• O Gateway consegue alcançar o proxy? curl http://127.0.0.1:1234/v1/models.
• Modelo do LM Studio descarregado? Recarregue; inicialização fria é uma causa comum de “travamento”.
• O servidor local diz terminated, ECONNRESET ou fecha o stream no meio do turno? O OpenClaw registra um model.call.error.failureKind de baixa cardinalidade, além do snapshot de RSS/heap do processo do 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 do modelo foi encerrado.
• O OpenClaw deriva os limites de preflight da janela de contexto a partir da janela detectada do modelo, ou da janela do modelo sem limite quando agents.defaults.contextTokens reduz a janela efetiva. Ele avisa abaixo de 20% com um piso de 8k. Bloqueios rígidos usam o limite de 10% com um 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 esse preflight, 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 só permitem role e content? Adicione compat.strictMessageKeys: true nessa entrada de modelo.
• Chamadas diretas pequenas 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 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 todos os turnos.
• Segurança: modelos locais ignoram filtros do lado do provedor; mantenha agentes restritos e Compaction ativada para limitar o raio de impacto de injeções de prompt.

​

Relacionado

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