◆ Agentes Locais — Agentes que agem na sua máquina, sem nuvem · 24 € · ou todos os kits 49 € →

#OpenClaw e Ollama: quem faz o quê

O OpenClaw é uma ponte: um processo que recebe suas mensagens de um aplicativo de mensagens, encaminha-as para um modelo de linguagem e executa as ações solicitadas por esse modelo. Ollama é um servidor de modelos: ele carrega um modelo na memória e responde na porta 11434 da máquina, no endereço http://localhost:11434 por padrão. Conectar um ao outro significa declarar Ollama como provedor no OpenClaw e, em seguida, designar um modelo local como o modelo principal do agente.

De acordo com a documentação do OpenClaw, essa conexão passa pela API nativa do Ollama (o endpoint /api/chat), que oferece suporte à resposta em fluxo contínuo e à chamada de ferramentas. Esse detalhe é mais importante do que parece: veremos que um endereço escrito incorretamente basta para fazer o gateway mudar para outro modo, no qual as ferramentas deixam de funcionar.

Ollama: Carrega o modelo, aloca para ele uma janela de contexto e gera o texto. É ele que decide a memória consumida.
OpenClaw: Envia a cada rodada a instrução do sistema, a descrição das ferramentas disponíveis e o histórico da conversa, depois executa as ferramentas solicitadas pelo modelo.
O modelo: Precisa manter em mente uma instrução longa e saber solicitar uma ferramenta no formato esperado. Nem todos os modelos locais são capazes disso.
O que não muda: As mensagens, a memória do assistente, o token e a segurança do gateway continuam configurados no OpenClaw, independentemente do fornecedor do modelo.

Essa integração é mais delicada do que a de uma interface de conversa. Um chat envia algumas linhas ao modelo; um agente envia a ele imediatamente vários milhares de tokens de instruções e definições de ferramentas, antes mesmo da sua primeira mensagem. As configurações padrão do Ollama foram pensadas para o primeiro caso, não para o segundo.

Local não significa sem risco

Um modelo local evita enviar suas conversas a um fornecedor online. Ele não elimina nenhum dos riscos próprios de um agente: o OpenClaw lê conteúdos vindos de fora e pode executar comandos. Em geral, um modelo pequeno é mais facilmente desviado por um texto malicioso do que um grande, e a documentação de segurança do projeto recomenda cautela nesse ponto. Mantenha o gateway em uma máquina dedicada, com o menor número possível de ferramentas, e execute novamente openclaw security audit --deep depois de mudar de modelo.

#Pré-requisitos

O kit Agentes Locais

Agentes que agem na sua máquina: Cline agêntico, MCP, n8n + Ollama, automações locais.

Espaço online vitalício
PDF + arquivos
Atualizações vitalícias

O kit Agentes Locais →ou todos os kits vitalícios — 49 € →

OpenClaw instalado: Uma ponte que inicia e cujo diagnóstico é aprovado. A instalação não é abordada aqui: consulte nosso guia “Instalar o OpenClaw com Docker”.
Ollama instalado e atualizado: O comando ollama launch usado mais abaixo só existe nas versões recentes. A instalação é abordada em nosso guia «Instalar Ollama».
Memória para o modelo e seu contexto: Referências em Q4_K_M apenas para os pesos: aproximadamente 5 GB para um modelo de 7 bilhões de parâmetros, 9 GB para 14 bilhões, 19 GB para 32 bilhões. A janela de contexto solicitada por um agente é adicionada a esse valor.
Acesso ao terminal: Na máquina que hospeda o gateway e naquela que hospeda Ollama, se não forem a mesma.

Terminal — verificar as duas ferramentas

ollama --version
openclaw --version

# Le serveur Ollama répond-il ?
curl http://localhost:11434/api/tags

O último comando deve retornar a lista dos modelos instalados no formato JSON. Uma conexão recusada significa que o Ollama não está iniciado: inicie o aplicativo ou execute ollama serve em um terminal. Não adianta prosseguir enquanto essa resposta não chegar.

#Etapa 1: reservar 64 000 tokens de contexto

Essa é a configuração que mais faz instalações falharem, e ela é feita no lado do Ollama, não no lado do OpenClaw. A página que Ollama dedica ao OpenClaw informa que o assistente precisa de uma janela de contexto grande e recomenda pelo menos 64 000 tokens com um modelo local. A página sobre o comprimento do contexto fornece o mesmo valor para agentes, pesquisa na web e ferramentas de código.

Agora, Ollama escolhe sua janela padrão de acordo com a memória de vídeo disponível: segundo essa mesma documentação, cerca de 4 000 tokens com menos de 24 GiB de VRAM, 32 000 entre 24 e 48 GiB, 256 000 a partir de 48 GiB. Em uma placa de 12 ou 16 GB, portanto, o servidor inicia com uma janela dezesseis vezes menor que a recomendada. Nada indica isso: Ollama trunca o que excede, sem mensagem de erro.

Terminal — Ollama iniciado manualmente (Linux, macOS)

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Se Ollama já estiver sendo executado como aplicativo (macOS, Windows), não execute este comando: um segundo servidor entraria em conflito na porta 11434. Ajuste o tamanho do contexto nas configurações do aplicativo. No Linux, quando Ollama tiver sido instalado como serviço systemd, a variável deve ser declarada no próprio serviço.

Terminal — Ollama instalado como serviço (Linux)

sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_CONTEXT_LENGTH=64000"

sudo systemctl daemon-reload
sudo systemctl restart ollama

64 000 tokens custam memória

A janela de contexto reserva memória além dos pesos do modelo. Um modelo que funciona confortavelmente em uma conversa pode passar a usar o processador quando o contexto aumenta, e o agente fica muito lento. Não fornecemos um número, pois ele depende do modelo: o comando ollama ps, visto na etapa 4, mostra o que foi realmente alocado. Se ultrapassar o limite, use um modelo menor em vez de reduzir o contexto. Duas variáveis documentadas no FAQ do Ollama reduzem o consumo: OLLAMA_FLASH_ATTENTION=1 e OLLAMA_KV_CACHE_TYPE=q8_0.

#Etapa 2: escolher um modelo que saiba chamar ferramentas

Um agente só age por meio de suas ferramentas: ler um arquivo, executar um comando, pesquisar na web. Um modelo que não sabe formular uma solicitação de ferramenta responderá educadamente às suas mensagens, mas nunca fará nada. Esta página não classifica os modelos; ela apresenta os critérios a verificar antes de conectar um deles.

A capacidade de « tools »: O comando ollama show affiche uma seção Capabilities. Ela deve conter tools. Na biblioteca de Ollama, o filtro correspondente está no endereço https://ollama.com/search?c=tools.
Uma janela nativa suficiente: O mesmo comando exibe o comprimento máximo de contexto do modelo. Um modelo projetado para 8.000 ou 32.000 tokens não poderá seguir a recomendação de 64.000, independentemente da configuração do servidor.
Um orçamento de memória realista: Os pesos e o contexto precisam caber juntos na VRAM, ou na memória unificada de um Mac. Em uma placa de 12 GB (RTX 3060, RTX 4070), isso orienta para modelos bem menores do que aqueles que a placa aceita em uma simples conversa; 16 GB (RTX 4080) e 24 GB (RTX 4090) deixam mais margem.
Desempenho ao longo do tempo: Um agente encadeia várias chamadas de ferramentas por solicitação. Os modelos muito pequenos erram com mais frequência o formato ou a ferramenta. Nenhuma ficha substitui um teste com suas próprias solicitações, começando pelas de baixo risco.

Terminal — baixar e depois inspecionar um modelo

ollama pull gpt-oss:20b
ollama show gpt-oss:20b

O nome gpt-oss:20b serve de exemplo no restante deste guia: substitua-o pelo modelo escolhido. A página de integração do Ollama mantém atualizada uma lista de modelos sugeridos para o OpenClaw, que muda conforme novos lançamentos; é melhor consultá-la do que confiar em uma lista fixa aqui.

Um modelo “na nuvem” não é um modelo local

A biblioteca de Ollama e o seletor do comando ollama launch também oferecem modelos cuja etiqueta termina em cloud. Eles são executados nos servidores de Ollama, não na sua máquina: suas mensagens saem do seu computador. Para uma instalação realmente local, escolha um modelo baixado, visível em ollama list.

#Etapa 3: configurar o fornecedor Ollama no OpenClaw

Existem duas opções. A primeira é um comando de Ollama que grava a configuração para você. A segunda consiste em declarar o provedor manualmente na configuração do OpenClaw; ela é indispensável assim que o gateway roda no Docker ou quando Ollama está em outra máquina.

#Caminho rápido: ollama launch openclaw

Terminal

# Configurer OpenClaw pour Ollama et démarrer la passerelle
ollama launch openclaw

# Configurer sans rien lancer
ollama launch openclaw --config

Segundo a documentação de Ollama, este comando faz você escolher um modelo, configura o OpenClaw para usar Ollama e inicia o gateway; se ele já estiver em execução, recarrega a nova configuração por conta própria. O nome antigo do projeto continua sendo aceito: ollama launch clawdbot é um alias. O comando se destina a um OpenClaw instalado diretamente na máquina, com o comando openclaw disponível no terminal. Ele não elimina a etapa 1: a mesma página pede que você registre o contexto do servidor.

#Método manual: declarar o provedor por conta própria

A documentação do OpenClaw descreve primeiro um modo de descoberta automática. Fornecemos uma chave fictícia, pois Ollama não exige nenhuma, e o OpenClaw consulta a instância local no endereço http://127.0.0.1:11434 para encontrar os modelos instalados.

Terminal — ativar o provedor e escolher o modelo

# N'importe quelle valeur convient : Ollama ne vérifie pas de clé
export OLLAMA_API_KEY="ollama-local"

# Ou l'inscrire dans la configuration d'OpenClaw
openclaw config set models.providers.ollama.apiKey "ollama-local"

# Lister les modèles vus par OpenClaw, puis fixer le modèle principal
openclaw models list
openclaw models set ollama/gpt-oss:20b

Um modelo é indicado no formato ollama/ seguido do nome exato exibido por ollama list, incluindo a etiqueta. Prefira registrá-lo na configuração em vez de usar a variável de ambiente quando o gateway funciona como serviço: uma variável exportada no seu terminal não é transmitida a um processo iniciado pelo sistema. Em uma instalação Docker, cada comando openclaw recebe o prefixo docker compose run --rm openclaw-cli.

O segundo modo é a declaração explícita, no arquivo ~/.openclaw/openclaw.json, escrito em JSON5. Ele é usado quando Ollama roda em outro lugar que não seja a máquina do gateway, quando um modelo não aparece na lista ou quando você quer definir por conta própria a janela anunciada ao agente.

~/.openclaw/openclaw.json — declaração explícita (JSON5)

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "gpt-oss:20b",
            name: "GPT-OSS 20B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 64000,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "ollama/gpt-oss:20b" }
    }
  }
}

baseUrl: O endereço do servidor Ollama, incluindo a porta, sem nada depois. É a única linha a alterar quando Ollama está sendo executado em outra máquina.
api: "ollama": Solicita explicitamente a API nativa de Ollama, aquela que gerencia a chamada de ferramentas.
apiKey: Um valor fictício. Ele serve apenas para ativar o provedor.
contextWindow: A janela anunciada ao OpenClaw, que a utiliza para gerenciar o tamanho do histórico. Ela deve corresponder ao que Ollama realmente carrega, não ao que o modelo aceitaria em teoria.
maxTokens: O limite máximo de comprimento de uma resposta.
cost: Zeros: um modelo local não é cobrado por token.
agents.defaults.model.primary: O modelo usado por padrão pelo agente, no formato ollama/nome-do-modelo.

Este exemplo retoma a estrutura fornecida pela documentação do OpenClaw; os valores de contextWindow e maxTokens são nossos e devem ser ajustados ao seu modelo. Duas coisas para lembrar. Primeiro, defina reasoning como true para um modelo de raciocínio. Depois, de acordo com a mesma documentação, a descoberta automática é desativada assim que existe uma entrada models.providers.ollama explícita: cada modelo que você quiser usar deve então constar na lista models.

Não coloque /v1 no final do endereço

Muitas ferramentas se conectam ao Ollama por sua interface compatível com OpenAI, no endereço http://localhost:11434/v1. A documentação do OpenClaw pede explicitamente que ele não seja usado: nesse modo, a chamada de ferramentas deixa de ser confiável e o modelo pode retornar o JSON da ferramenta como texto simples. O endereço correto termina na porta: http://localhost:11434.

Terminal — aplicar e verificar

openclaw gateway restart
openclaw doctor

#Gateway no Docker ou Ollama em outra máquina

Dentro de um contêiner, localhost designa o próprio contêiner. Portanto, um gateway OpenClaw iniciado com Docker não consegue ver o Ollama da máquina host no endereço http://localhost:11434: a conexão é recusada, embora tudo funcione no seu terminal. A solução depende de onde Ollama está sendo executado.

Docker Desktop (macOS, Windows): O nome host.docker.internal designa a máquina host a partir do contêiner. Indique http://host.docker.internal:11434 como baseUrl na declaração explícita.
Docker Engine no Linux: Esse nome não existe por padrão: é preciso adicioná-lo ao serviço com extra_hosts, como abaixo. Além disso, Ollama precisa escutar em uma interface que o contêiner consiga acessar, o que não ocorre com sua configuração original, limitada ao loopback.
Ollama em outra máquina: Coloque o endereço desta máquina na sua rede local ou VPN em baseUrl e configure também a escuta de Ollama nesta máquina.

docker-compose.override.yml — exemplo a ser adaptado (Linux)

services:
  openclaw-gateway:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Terminal — fazer Ollama escutar além do loopback (serviço Linux)

sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0:11434"

sudo systemctl daemon-reload
sudo systemctl restart ollama

O arquivo Compose é um exemplo nosso, não um trecho da documentação do OpenClaw: compare o nome do serviço com o docker-compose.yml da sua versão. A variável OLLAMA_HOST, por sua vez, é descrita na FAQ do Ollama. Avalie suas implicações: com 0.0.0.0, o servidor escuta em todas as interfaces da máquina, e a API do Ollama não exige autenticação. Um firewall deve limitar a porta 11434 à rede Docker ou à rede local, e essa porta nunca deve ficar acessível pela Internet. Nosso guia sobre como proteger um servidor Ollama detalha essas regras.

#Etapa 4: verificar a conexão de ponta a ponta

Um agente que responde « olá » não prova nada: essa resposta não exige ferramenta nem contexto. A verificação útil avança camada por camada, do servidor de modelos até a mensageria.

01
Testar a chamada de ferramentas apenas em Ollama
Envie ao servidor uma pergunta acompanhada de uma ferramenta fictícia, usando o comando abaixo. A resposta deve conter um campo tool_calls que nomeie a ferramenta e passe um argumento a ela. Se o modelo responder com uma frase, ele não é adequado para um agente.
02
Controlar o que o OpenClaw vê
O comando openclaw models list deve exibir seu modelo no formato ollama/nome-do-modelo, e openclaw doctor não deve indicar erro de provedor.
03
Pedir uma ação, não uma resposta
Na interface de controle ou no seu mensageiro, envie uma solicitação que obrigue o agente a usar uma ferramenta, por exemplo, listar os arquivos do espaço de trabalho dele. Ele deve fazer isso de verdade, não descrever o que faria.
04
Ver o que Ollama carregou
Logo após essa troca, execute ollama ps na máquina do servidor e leia as colunas CONTEXT e PROCESSOR.

Terminal — 1. uma chamada de ferramentas diretamente em Ollama

curl http://localhost:11434/api/chat -d '{
  "model": "gpt-oss:20b",
  "stream": false,
  "messages": [{"role": "user", "content": "Quel temps fait-il à Lyon ?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Donne la météo actuelle pour une ville",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}'

Terminal — 2 e 4. do lado do OpenClaw, depois do lado do Ollama

openclaw models list
openclaw doctor

# Après un échange avec l'agent
ollama ps

Na saída do ollama ps, a coluna CONTEXT informa a janela realmente alocada para o modelo carregado. Se ela exibir 4096 quando você pretendia usar 64 000, a configuração da etapa 1 não foi aplicada, independentemente do que indique a configuração do OpenClaw. A coluna PROCESSOR informa a distribuição entre a placa de vídeo e o processador: a indicação 100% GPU é o que procuramos; uma distribuição mista indica que o modelo e seu contexto excedem a memória de vídeo.

→

Isolar a camada com defeito

Se o teste direto em Ollama (o primeiro dos quatro controles) falhar, o problema vem do modelo ou de Ollama, e nenhuma configuração do OpenClaw irá corrigi-lo. Se ele for bem-sucedido, mas o agente não agir, procure na conexão: endereço do servidor, modo de API, janela de contexto. Essa triagem evita modificar a configuração ao acaso.

#Falhas silenciosas: sintomas e causas

Os erros claros (conexão recusada, modelo não encontrado) aparecem nos logs. As falhas abaixo são mais custosas, porque o assistente continua respondendo: ele apenas responde errado.

O assistente ignora suas instruções ou responde algo que não vem ao caso: Causa mais provável: o contexto foi truncado. A instrução do sistema e as definições das ferramentas excedem a janela carregada pelo Ollama, que corta parte dela sem avisar. Verifique a coluna CONTEXT do ollama ps e refaça a etapa 1.
JSON é exibido no lugar da ação: O modelo formulou corretamente uma chamada de ferramenta, mas o gateway a recebeu como texto. Isso indica um endereço em /v1 ou um provedor declarado no modo compatível com OpenAI. Volte ao endereço nativo e a api: "ollama".
Ele descreve o que faria, sem fazer nada: O modelo não declara a capacidade tools ou é limitado demais para usá-la no meio de uma instrução longa. Refaça o teste direto em Ollama descrito na etapa 4; se falhar, troque de modelo.
O modelo não aparece em openclaw models list: Três possibilidades. O provedor não está ativado (a chave fictícia está ausente ou a variável não foi transmitida ao serviço). Existe uma entrada models.providers.ollama explícita que não lista esse modelo. Ou o modelo não declara a chamada de ferramentas: segundo a documentação que conhecemos, a descoberta automática considera apenas os que a declaram, um comportamento que pode ter evoluído conforme as versões.
O ajuste do contexto continua sem efeito: A variável OLLAMA_CONTEXT_LENGTH foi exportada em um terminal, enquanto o Ollama é executado como serviço ou aplicativo: o servidor nunca a viu. Declare-a no serviço ou nas configurações do aplicativo e depois reinicie o Ollama.
As respostas demoram muito para chegar ou não chegam: Ou o modelo está transbordando para o processador (coluna PROCESSOR do ollama ps), ou foi descarregado após um período de inatividade e é recarregado a cada mensagem: por padrão, Ollama mantém um modelo na memória por cinco minutos. A variável OLLAMA_KEEP_ALIVE prolonga esse período.
Tudo funciona no terminal, nada pela interface de gateway: O gateway é executado em um contêiner e procura Ollama no próprio localhost. Consulte a seção sobre Docker.
« Model context window too small »: Esta não é silenciosa, mas confunde: as versões do OpenClaw que conhecemos recusam um modelo cuja janela anunciada é pequena demais. Aumente contextWindow na declaração explícita e ajuste o contexto de Ollama de acordo.

Terminal — acompanhar os logs dos dois lados

# Passerelle OpenClaw
openclaw logs --follow

# Serveur Ollama installé comme service (Linux)
journalctl -u ollama -f

Uma limitação para ter em mente depois que a conexão estiver estabelecida: um modelo local conectado corretamente não necessariamente se comportará como um grande modelo online em tarefas longas ou ambíguas. Não publicamos aqui nenhuma comparação nem nenhuma taxa de transferência. Comece com solicitações simples e sem riscos, observe onde o modelo falha e mantenha um provedor online como modelo de reserva se o assistente fizer parte do seu dia a dia.

#Fontes oficiais para ter à mão

Este guia não se baseia em nenhum teste próprio: não contém duração, taxa de transferência nem pontuação. Os comandos e os nomes dos campos reproduzem a documentação dos dois projetos, que muda de uma versão para outra: opções de ollama launch, comportamento da descoberta automática, valores padrão. Em caso de divergência entre esta página e a documentação, vale a documentação.

Ollama: integração com OpenClaw

https://docs.ollama.com/integrations/openclaw

OpenClaw: provedor Ollama

https://docs.openclaw.ai/providers/ollama

Ollama: comprimento do contexto

https://docs.ollama.com/context-length

Ollama: FAQ (variáveis do servidor)

https://docs.ollama.com/faq

OpenClaw: segurança do gateway

https://docs.openclaw.ai/gateway/security

#Para se aprofundar

A conexão se baseia em três conceitos tratados em detalhes em outras páginas do site: o servidor Ollama, a janela de contexto e a chamada de ferramentas.

Instalar Ollama: A instalação do servidor de modelos, suas configurações básicas e o que pode sair da máquina. https://quelllm.fr/guide/installer-ollama
Compreender a janela de contexto: O que um token mede, por que o contexto consome memória e como dimensioná-lo. https://quelllm.fr/guide/comprendre-fenetre-contexte
A chamada de ferramentas com Ollama: O formato das solicitações de ferramentas e como testá-las fora de qualquer agente. https://quelllm.fr/guide/appel-outil-ollama-tutoriel
Hermes Agent com Ollama: Outro agente auto-hospedado conectado a um modelo local, para comparar as abordagens. https://quelllm.fr/guide/hermes-agent-ollama-guide
Instalar o OpenClaw com Docker: A instalação do gateway, sua atualização e as regras de exposição em um VPS. https://quelllm.fr/guide/installer-openclaw-docker

Este guia ajudou você?

Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.

Os kits QuelLLMO guia de referência por uso

Agentes Locais Copiloto Local IA local RAG Local IA Empresarial IA Sem Filtros Mac Imagens IA

Todos os kits vitalícios — 49 €