Ollama e OpenClaw: Como executar o OpenClaw em um modelo local

O OpenClaw é um assistente de IA auto-hospedado que conversa com você por aplicativos de mensagens e aciona ferramentas em sua máquina. Ele não possui nenhuma integração específica com o Ollama; você conecta os dois apontando o provedor de modelos do OpenClaw para o endpoint compatível com OpenAI do Ollama, http://localhost:11434/v1. Funciona, mas apenas com um modelo capaz de chamar ferramentas de forma confiável e com uma janela de contexto bem maior que o padrão do Ollama.

O que o OpenClaw realmente é

O OpenClaw é um assistente pessoal de código aberto que roda como um processo de gateway de longa duração em seu próprio hardware. Ele atua como ponte entre canais de mensagens — WhatsApp, Telegram, Discord, Signal e iMessage — e um loop de agente com acesso a ferramentas: comandos de shell, operações com arquivos, buscas na web, calendário e memória. O projeto começou como Clawdbot, foi brevemente renomeado para Moltbot, e acabou adotando o nome OpenClaw. Seu cérebro padrão era um modelo da Anthropic, mas, como ele usa o protocolo de conclusões de chat da OpenAI para provedores de terceiros, qualquer serviço compatível com esse protocolo pode ser usado como substituto — incluindo o Ollama.

Uma observação para evitar ambiguidades: há um projeto não relacionado também chamado OpenClaw, que é uma reimplementação em C++ do jogo de plataforma de 1997 Captain Claw. Esse projeto não tem nenhuma relação com LLMs. Se você pesquisou "ollama openclaw", quase certamente está procurando o assistente.

Por que esse emparelhamento é mais difícil do que uma interface de chat

Apontar uma interface frontal de chat para o Ollama é trivial. Já um framework de agente não é, por três motivos:

• As chamadas de ferramentas devem ser estruturalmente corretas. O OpenClaw envia definições de ferramentas e espera receber objetos JSON de chamadas de ferramentas em resposta. Modelos sem um modelo de chat adaptado para ferramentas geram texto em prosa como "Agora vou executar ls", fazendo com que o loop pare.
• O prompt já é grande antes mesmo de você digitar algo. Instruções do sistema somadas aos esquemas das ferramentas consomem rotineiramente vários milhares de tokens. O contexto padrão do Ollama trunca isso, e a truncagem no início do prompt remove exatamente as instruções das quais o agente depende.
• Erros se acumulam ao longo das interações. Um modelo com 90% de precisão por etapa em chamadas de ferramentas conclui uma tarefa de seis etapas apenas cerca de metade das vezes.

Etapa 1: Configure o Ollama para servir em um endereço acessível

Se o Ollama ainda não estiver instalado, siga as instruções do Guia de instalação do Ollama primeiro. Confirme se o servidor responde:

curl http://localhost:11434/api/version
curl http://localhost:11434/v1/models

Se o OpenClaw for executado na mesma máquina e fora de um contêiner, a vinculação padrão de loopback é suficiente e você pode pular para a Etapa 2. Se o OpenClaw for executado em um contêiner Docker ou em outra máquina, o Ollama deve vincular-se além do loopback por meio de OLLAMA_HOST. A forma de configurar isso varia conforme a plataforma.

macOS

O aplicativo da barra de menus não lê seu perfil de shell. Defina a variável no ambiente de inicialização e reinicie o aplicativo a partir do ícone na bandeja:

launchctl setenv OLLAMA_HOST "0.0.0.0:11434"

Os modelos ficam em ~/.ollama/models. Os logs do servidor estão em ~/.ollama/logs/. De um contêiner na mesma Mac, acesse o host em http://host.docker.internal:11434.

Linux

O instalador registra uma unidade systemd. Substitua seu ambiente em vez de editar diretamente o arquivo da unidade fornecido:

sudo systemctl edit ollama.service

Adicione:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_KEEP_ALIVE=-1"

Em seguida, execute sudo systemctl daemon-reload && sudo systemctl restart ollama. Os logs vêm de journalctl -u ollama -fSob a conta de serviço, os modelos usam como padrão /usr/share/ollama/.ollama/models, não seu diretório pessoal — uma surpresa comum quando ollama list parece vazio ao acessar como administrador (root).

Windows

Defina a variável pela interface gráfica: Iniciar → «Editar as variáveis de ambiente do sistema» → Variáveis de ambiente → Novo em Variáveis do usuário, nome OLLAMA_HOST, valor 0.0.0.0:11434. Saia do Ollama na bandeja do sistema e reinicie-o; o processo da bandeja lê as variáveis de ambiente apenas na inicialização. Os modelos ficam em %USERPROFILE%\.ollama\models; os logs, em %LOCALAPPDATA%\Ollama.

O OpenClaw em si é uma aplicação Node.js e funciona de forma mais confiável no Linux ou no macOS. No Windows, execute-o dentro do WSL2. Nesse caso, o Ollama pode permanecer instalado nativamente no Windows — o WSL2 acessa o host Windows por meio do endereço de gateway espelhado ou NAT, portanto verifique com curl dentro do WSL antes de configurar qualquer coisa.

Aviso de segurança: O Ollama não possui autenticação. Associar 0.0.0.0 expõe a inferência de modelos a todos os hosts capazes de rotear para essa porta. Mantenha-o em uma LAN ou VPN confiável, ou use um proxy reverso que exija um token. Nunca o exponha à internet pública.

Etapa 2: Baixe um modelo capaz de chamar ferramentas

A chamada de ferramentas no Ollama depende do modelo de conversação (chat template) do modelo, não de uma flag passada como parâmetro. Os tamanhos indicados abaixo são aproximações para tags comuns em 4 bits e podem variar entre versões — consulte ollama list e a lista atual de tags para obter valores exatos.

Baixe um modelo e verifique se ele aceita ferramentas antes de integrá-lo ao OpenClaw:

ollama pull qwen3:14b

Para uma comparação mais ampla de candidatos e seu comportamento sob cargas de trabalho de agentes, consulte os melhores modelos locais para Ollama.

Etapa 3: Amplie a janela de contexto

Este é o passo que muitos ignoram, e é a causa mais comum de uma configuração OpenClaw + Ollama que «quase funciona». O Ollama aplica um contexto padrão modesto (historicamente 2048, aumentado em versões posteriores), independentemente do suporte do modelo. Versões recentes aceitam uma variável de ambiente global do servidor, mas o método independente de versão é incorporá-la a um modelo derivado: OLLAMA_CONTEXT_LENGTH FROM qwen3:14b PARAMETER num_ctx 32768

Salve como

ollama create qwen3-14b-32k -f Modelfile Modelfile, então:

qwen3-14b-32k

O melhor editor completo como nome do modelo no OpenClaw. Contextos maiores consomem VRAM para o cache KV, que é distinto dos pesos — use o para verificar quanto VRAM um determinado modelo e comprimento de contexto realmente exigem, antes de descobrir isso por meio de um erro de memória insuficiente (OOM). Em versões recentes do Ollama, Calculadora de VRAM ver o que um determinado modelo e comprimento de contexto realmente exigem antes de descobrir por meio de um erro de memória insuficiente (OOM). Em versões recentes do Ollama, OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0) reduzem significativamente essa sobrecarga.O OpenClaw armazena sua configuração em um diretório oculto sob seu diretório pessoal (

Etapa 4: Aponte o OpenClaw para o Ollama

O OpenClaw armazena a configuração em um diretório oculto (ponto-diretório) sob o seu diretório home () e permite substituições via variáveis de ambiente. Os três valores necessários são sempre, essencialmente, os mesmos:) e permite substituições por variáveis de ambiente. Os três valores que você precisa são sempre os mesmos em essência:

A configuração exata nomes das chaves mudaram ao longo das renomeações do projeto e de seu ritmo acelerado de lançamentos. Em vez de copiar um bloco de configuração de um post de blog, execute a saída de ajuda da CLI e inspecione o arquivo de configuração gerado na versão instalada em seu sistema:

openclaw --help

Na prática, você deve procurar o bloco genérico de provedor compatível com OpenAI — o mesmo usado para OpenRouter, vLLM ou LM Studio — e definir nele a URL base, a chave e o modelo. Se o OpenClaw oferecer seleção de provedor durante a configuração inicial, escolha a opção compatível com OpenAI, em vez de um fornecedor nomeado.

Antes de depurar o OpenClaw, confirme se o endpoint responde diretamente a uma solicitação de chamada de ferramenta com curl contra /v1/chat/completions. Se isso falhar, o problema está no Ollama, não no OpenClaw.

Verificação da realidade de hardware

O OpenClaw é um serviço em segundo plano. O modelo é carregado e recarregado à medida que as mensagens chegam, e cada recarregamento acrescenta vários segundos de latência; portanto, você deseja manter os pesos carregados permanentemente — daí o uso de OLLAMA_KEEP_ALIVE=-1. Isso significa que a VRAM fica alocada pelo tempo em que o assistente estiver em execução, e não apenas durante uma solicitação específica. Planeje sua capacidade de acordo: uma placa de vídeo de 24 GB executando qwen3:32b com contexto de 32K praticamente não deixa memória livre para qualquer outra tarefa.

Uma GPU de 16 GB é o ponto de entrada razoável para um modelo de 14B–20B com um contexto utilizável. Abaixo de 12 GB, você fica restrito a modelos de 8B, nos quais a confiabilidade em múltiplas etapas cai acentuadamente. Os chips Apple Silicon com 32 GB ou mais de memória unificada funcionam bem, pois a memória é compartilhada, embora o processamento de prompts seja mais lento do que em uma placa NVIDIA dedicada. Consulte o guia de GPUs para LLMs locais para saber quais placas específicas valem a pena comprar em cada faixa de desempenho.

A configuração híbrida adotada pela maioria das pessoas

O resultado realista: um modelo local de 14B lida perfeitamente com mensagens rotineiras, resumos, lembretes e consultas únicas a ferramentas. Cadeias de pesquisa extensas, alterações de código em diversos arquivos e qualquer tarefa que exija seguir instruções com precisão apresentam uma degradação perceptível. Por isso, muitos usuários do OpenClaw mantêm configurado um provedor em nuvem para o ciclo principal do agente e usam o Ollama para tarefas de alto volume e baixa criticidade, ou para conteúdos sensíveis à privacidade que não devem deixar a máquina.

Se essa divisão gera economia depende do volume de mensagens e do custo da eletricidade. Faça suas contas usando a calculadora de ponto de equilíbrio entre hospedagem local e uso de API antes de comprar uma GPU especificamente para esse fim; em volumes baixos, a API geralmente sai mais barata do que a amortização do hardware.

Solução de problemas

Perguntas frequentes

O OpenClaw oferece suporte oficial ao Ollama?

Não como uma integração nomeada. O suporte é indireto: o OpenClaw pode usar qualquer endpoint de chat-completions compatível com OpenAI, e o Ollama fornece um nesse endereço /v1. Esse caminho é estável e improvável de mudar, mas o próprio esquema de configuração do OpenClaw evolui rapidamente; portanto, verifique sempre sua documentação atual para conhecer as chaves exatas do provedor, em vez de presumir.

Qual é o menor modelo que realmente funciona?

Um modelo de 8B com suporte a chamadas de ferramentas, como o qwen3:8b , representa o limite realista — e somente para interações curtas e com uma única ferramenta. Abaixo disso, os argumentos das ferramentas tornam-se frequentemente malformados a ponto de tornar o ciclo do agente mais frustrante do que útil. A partir de 14B é que o comportamento começa a parecer confiável.

Posso executar isso no Windows?

Sim, com o OpenClaw dentro do WSL2 e o Ollama instalado nativamente no Windows, para que utilize diretamente seu driver de GPU. Verifique a conectividade a partir do shell do WSL com curl antes de configurar o OpenClaw. Observe que o canal iMessage é exclusivo do macOS, independentemente da plataforma, pois depende do banco de dados local do aplicativo Mensagens.

Por que o OpenClaw local é tão pior do que a versão com suporte em nuvem?

Dois fatores cumulativos. Primeiro, a precisão nas chamadas de ferramentas por etapa é menor, e os erros se multiplicam ao longo de uma tarefa com várias etapas. Segundo, os modelos locais degradam-se mais rapidamente à medida que o contexto vai sendo preenchido, e o prompt do OpenClaw já é grande antes mesmo de sua mensagem ser adicionada. Ambos são limites inerentes às capacidades do modelo, não problemas de configuração.

O Ollama pode ser executado em uma máquina diferente do OpenClaw?

Sim, e é um bom padrão — instale o Ollama na máquina com a GPU e execute o gateway em um dispositivo sempre ativo e de baixo consumo. Defina OLLAMA_HOST=0.0.0.0:11434 no host com GPU e use seu endereço LAN na URL base do OpenClaw. Como o Ollama não possui autenticação, restrinja esse acesso a uma rede confiável ou a uma VPN.

Esse é o mesmo OpenClaw do projeto do jogo Captain Claw?

Não. Esse OpenClaw é uma reimplementação em C++, sem relação alguma, de uma plataforma de jogos DOS de 1997 e compartilha apenas o nome. Se um resultado de busca mencionar arquivos de nível ou renderização de sprites, você acessou o projeto do jogo.

Conclusão

A integração entre Ollama e OpenClaw é uma tarefa de configuração de cinco minutos: o endpoint compatível com OpenAI, uma chave não vazia e uma tag de modelo exata. O trabalho que determina se ela será utilizável ocorre antes disso — escolher um modelo com suporte real a chamadas de ferramentas, garantir-lhe uma janela de contexto suficientemente grande para o prompt do agente e dispor de VRAM suficiente para mantê-lo carregado permanentemente. Compare modelos candidatos na banco de dados de modelos, e, se você for novo na superfície de configuração do Ollama, o guia completo do Ollama aborda com mais profundidade as variáveis de ambiente e os mecanismos do Modelfile.