Ollama e OpenClaw: Como Executar OpenClaw em um Modelo Local

OpenClaw é um assistente de IA auto-hospedado que conversa com você por aplicativos de mensagens e controla ferramentas em sua máquina. Não tem integração específica com Ollama; você conecta o provedor de modelo do OpenClaw ao endpoint compatível com OpenAI da Ollama, http://localhost:11434/v1. Funciona, mas apenas com um modelo que chama ferramentas de forma confiável e uma janela de contexto bem acima do padrão da Ollama.

O que OpenClaw realmente é

OpenClaw é um assistente pessoal de código aberto que funciona como um processo gateway de longa duração em seu próprio hardware. Conecta canais de mensagens — WhatsApp, Telegram, Discord, Signal, iMessage — a um loop de agente com acesso a ferramentas: comandos de shell, operações de arquivo, buscas na web, calendário e memória. O projeto começou como Clawdbot, foi brevemente renomeado para Moltbot, e se estabeleceu em OpenClaw. Seu cérebro padrão era um modelo Anthropic, mas porque fala o protocolo de conclusões de chat OpenAI para provedores de terceiros, qualquer coisa que sirva esse protocolo pode substituir — incluindo Ollama.

Uma observação: um projeto não relacionado chamado OpenClaw é uma reimplementação em C++ do platformer de 1997 Captain Claw. Não tem nada a ver com LLMs. Se você pesquisou «ollama openclaw», quase certamente quer o assistente.

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

Apontar uma interface de chat para Ollama é trivial. Um framework de agente não é, por três razões:

• As chamadas de ferramentas devem ser estruturalmente corretas. OpenClaw envia definições de ferramentas e espera objetos de chamada de ferramenta JSON em retorno. Modelos sem um template de chat ciente de ferramentas produzem prosa como «vou executar ls» e o loop trava.
• O prompt é grande antes de você digitar qualquer coisa. Instruções do sistema mais esquemas de ferramentas rotineiramente consomem vários milhares de tokens. O contexto padrão da Ollama trunca isso, e truncação no início do prompt remove exatamente as instruções que o agente depende.
• Os erros se acumulam entre turnos. Um modelo com 90% de precisão de ferramenta por etapa completa uma tarefa de seis etapas aproximadamente metade das vezes.

Passo 1: Coloque Ollama servindo em um endereço acessível

Se Ollama ainda não está instalado, siga o 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 OpenClaw é executado no mesmo host e fora de um container, a vinculação padrão de loopback funciona e você pode pular para a Etapa 2. Se OpenClaw é executado em Docker ou em outra máquina, Ollama deve se vincular além do loopback através de OLLAMA_HOST. Como você configura isso varia por plataforma.

macOS

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

launchctl setenv OLLAMA_HOST "0.0.0.0:11434"

Os modelos vivem em ~/.ollama/models. Os logs do servidor ficam em ~/.ollama/logs/. De um container no mesmo Mac, alcance o host em http://host.docker.internal:11434.

Linux

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

sudo systemctl edit ollama.service

Adicione:

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

Depois sudo systemctl daemon-reload && sudo systemctl restart ollama. Os logs vêm de journalctl -u ollama -f. Na 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 como root.

Windows

Defina a variável através da GUI: Iniciar → «Editar as variáveis de ambiente do sistema» → Variáveis de Ambiente → Novo sob Variáveis de usuário, nome OLLAMA_HOST, valor 0.0.0.0:11434. Saia de Ollama na bandeja do sistema e relance-o; o processo da bandeja lê variáveis de ambiente apenas na inicialização. Os modelos ficam em %USERPROFILE%\.ollamamodels; logs em %LOCALAPPDATA%Ollama.

OpenClaw em si é uma aplicação Node e é mais confiável em Linux ou macOS. No Windows, execute dentro de WSL2. Nesse caso, Ollama pode permanecer como uma instalação Windows nativa — WSL2 alcança o host Windows sobre o endereço de gateway espelhado ou NAT, então verifique com curl de dentro de WSL antes de configurar qualquer coisa.

Nota de segurança: Ollama não possui autenticação. Vincular 0.0.0.0 expõe a inferência de modelo para cada host que pode rotear para essa porta. Mantenha em uma LAN ou VPN confiável, ou coloque na frente com um proxy reverso que exija um token. Nunca o exponha à internet pública.

Passo 2: Baixe um modelo que possa chamar ferramentas

A chamada de ferramentas em Ollama depende do template de chat do modelo, não de um sinalizador que você passar. Os tamanhos abaixo são aproximados para tags 4-bit comuns e variam entre versões — verifique ollama list e a listagem de tags atual para figuras exatas.

Tag de modelo	Parâmetros	Download aprox.	VRAM prático em contexto 32K	Adequado para OpenClaw
llama3.1:8b	8B	~4,7 GB	8–10 GB	Mínimo. Apenas tarefas simples de ferramenta única.
qwen3:8b	8B	~5 GB	8–10 GB	Melhor disciplina de ferramentas que Llama 3.1 8B.
qwen3:14b	14B	~9 GB	12–16 GB	Bom equilíbrio em uma placa de 16 GB.
gpt-oss:20b	20B MoE	~14 GB	16 GB	Uso forte de ferramentas; rápido devido à ativação esparsa.
mistral-small	24B	~14 GB	16–20 GB	Chamada de função confiável.
qwen3:32b	32B	~20 GB	24 GB+	Melhor experiência local realista.

Puxe uma e verifique se aceita ferramentas antes de tocar em OpenClaw:

ollama pull qwen3:14b

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

Passo 3: Aumente a janela de contexto

Este é o passo que as pessoas pulam, e é a causa mais comum de uma configuração OpenClaw-on-Ollama que «quase funciona». Ollama aplica um contexto padrão modesto (historicamente 2048, aumentado em versões posteriores) independentemente do que o modelo suporta. Versões recentes aceitam uma OLLAMA_CONTEXT_LENGTH variável de ambiente em nível de servidor, mas o método independente de versão é incorporá-la em um modelo derivado:

FROM qwen3:14b
PARAMETER num_ctx 32768

Guardar como Modelfile, então:

ollama create qwen3-14b-32k -f Modelfile

Use qwen3-14b-32k como o nome do modelo no OpenClaw. Contextos maiores consomem VRAM para o KV cache, que é separado dos pesos — use o calculadora de VRAM para ver o que um determinado modelo e comprimento de contexto realmente precisa antes de descobrir por OOM. Em builds recentes do Ollama, OLLAMA_FLASH_ATTENTION=1 e um KV cache quantizado (OLLAMA_KV_CACHE_TYPE=q8_0) reduzem significativamente esse overhead.

Passo 4: Aponte OpenClaw para Ollama

OpenClaw armazena a configuração em um diretório oculto em seu home (~/.openclaw/) e permite overrides de variáveis de ambiente. Os três valores que você precisa são sempre os mesmos em essência:

Configuração	Valor
URL Base	http://localhost:11434/v1 — o /v1 sufixo é obrigatório
Chave API	Qualquer string não vazia, p. ex. ollama. O valor é ignorado, mas muitos clientes rejeitam um valor vazio.
Modelo	:tag ollama list, incluindo a rota na porção porção

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 de realidade do 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 GPU para LLMs locais para saber quais placas específicas valem a pena comprar em cada faixa de desempenho.

A configuração híbrida que a maioria das pessoas acaba usando

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

Sintoma	Causa e solução
ECONNREFUSED / conexão recusada	Servidor não está em execução ou está vinculado ao loopback enquanto o OpenClaw está em um contêiner. Teste curl http://localhost:11434/api/version a partir do namespace de rede do contêiner.
404 nas requisições	URL base ausente /v1, ou apontada para o caminho nativo do /api/chat em vez do caminho compatível com OpenAI.
401 / chave de API ausente	Defina o campo 'key' como qualquer string não vazia.
modelo não encontrado	Incompatibilidade de tag. Copie o nome exatamente conforme aparece em ollama list.
O agente descreve o uso da ferramenta em vez de executá-la	O modelo não possui um template para chamadas de ferramentas. Mude para um dos modelos listados na tabela acima.
O agente esquece suas instruções no meio de uma tarefa	Truncamento de contexto. Reconstrua com um valor maior de num_ctx.
A primeira resposta após um período de inatividade leva 30+ segundos	O modelo foi descarregado após o tempo limite de keep-alive. Defina OLLAMA_KEEP_ALIVE=-1.

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.