Se o Ollama conversa no OpenClaw, mas não executa ferramentas — ou devolve um JSON de ação como mensagem — verifique primeiro o protocolo do provedor. A documentação atual do OpenClaw recomenda a API nativa do Ollama: api: "ollama" e baseUrl: "http://HOST:11434", sem /v1. Depois, confirme que o modelo aceita ferramentas e que a ação está permitida. Responder texto não prova que a integração de tool calling está funcionando.
Este guia separa falha de conexão, incompatibilidade do modelo e bloqueio de execução. O objetivo é corrigir a camada certa sem apagar sessões, reinstalar tudo ou liberar permissões perigosas.
Diagnóstico rápido: o que você está vendo
| Sintoma | Camada a investigar primeiro | Teste útil |
|---|---|---|
O assistente imprime {"name": ..., "arguments": ...} | Protocolo do provedor ou formato de ferramentas | Conferir api e remover /v1 do endpoint nativo |
| Conversa normalmente, mas nunca tenta uma ação | Capacidade do modelo e ferramentas disponíveis | Testar uma chamada estruturada diretamente no Ollama |
| Aparece pedido de aprovação | Política de execução | Revisar e aprovar somente a ação esperada |
| A ferramenta é chamada, mas retorna erro | Ferramenta, credencial ou serviço de destino | Inspecionar o erro da execução, não trocar o modelo de imediato |
Connection refused ou nenhum modelo disponível | Rede e serviço Ollama | Consultar /api/tags a partir do ambiente do Gateway |
| Funciona no terminal do host, mas falha no Docker | Endereço visto pelo container | Verificar o destino real de localhost |
Tool calling é a geração de uma chamada estruturada que o assistente consegue interpretar e encaminhar a uma ferramenta. Um texto dizendo “vou consultar seus arquivos” não é uma chamada; um texto dizendo “concluído” também não comprova execução. Para entender a diferença, consulte o glossário de tool use.
1. Confirme qual Ollama o Gateway está acessando
Comece com verificações sem alterações no sistema:
openclaw --version
ollama --version
openclaw gateway status --deep
curl --fail --show-error http://localhost:11434/api/tags
O último comando deve retornar JSON com os modelos disponíveis. Use localhost somente se o Ollama estiver no mesmo ambiente de rede de onde você executou o comando. Se o Gateway acessa outro host, troque o endereço pelo host real.
Faça o teste a partir do mesmo ambiente que roda o Gateway. Consultar o Ollama no notebook não comprova que um Gateway instalado em VPS, container ou outro computador alcança esse serviço. A lista de modelos do notebook também pode ser diferente da lista do servidor.
Em Docker, localhost normalmente aponta para o próprio container, não para o sistema hospedeiro. O endereço correto depende da sua rede: nome do serviço no Compose, IP alcançável do host ou mecanismo de acesso ao host suportado pela instalação. Não copie um endereço universal. O guia de Docker Compose ajuda a organizar essa topologia.
Se a API nem responde, resolva conexão e carregamento antes de investigar ferramentas. Veja Ollama não carrega o modelo e Gateway não inicia.
2. Use o provedor nativo, não uma URL com /v1
O Ollama oferece uma API nativa e uma interface compatível com OpenAI. Essa compatibilidade pode ser útil para outros clientes, mas a documentação do provedor Ollama no OpenClaw alerta que usar a URL /v1 quebra o tool calling e pode fazer o modelo emitir o JSON da ferramenta como texto.
No provedor nativo, o trecho relevante é:
{
"models": {
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434",
"api": "ollama"
}
}
}
}
Esse é um fragmento de configuração, não um arquivo completo para substituir sua configuração atual. Preserve a seleção de modelo, as credenciais, os canais e as demais opções. Ajuste o host e mescle somente os campos pertinentes no provedor que seu agente realmente utiliza.
Observe três detalhes:
baseUrltermina na porta, sem/v1e sem/api/chat.api: "ollama"seleciona o protocolo nativo; o cliente constrói a chamada para/api/chat.- Corrigir uma entrada chamada
ollamanão resolve nada se o agente continua apontando para outro provedor ou modelo.
Antes de editar, faça uma cópia da configuração em local privado. Aplique a alteração pelo procedimento suportado pela sua versão e confira se o Gateway a aceitou. Se sua instalação exige reinício, programe-o fora de uma tarefa em andamento. Abra uma conversa de teste e repita o pedido de leitura; não use uma ação de produção como primeiro teste.
Não é necessário reinstalar o Ollama para corrigir uma URL. Tampouco é necessário desativar o sandbox ou liberar todos os comandos.
3. Teste o suporte a ferramentas diretamente no Ollama
Nem todo modelo que gera bom português consegue produzir chamadas de ferramentas confiáveis. A tag exata importa: nome da família, versão e variante não são intercambiáveis.
Escolha em ollama list um modelo instalado que documente suporte a ferramentas. No exemplo abaixo, substitua MODELO_INSTALADO pelo nome exato. Se o serviço não estiver local, ajuste também a URL.
curl --fail --show-error http://localhost:11434/api/chat \
-H 'Content-Type: application/json' \
-d '{
"model": "MODELO_INSTALADO",
"stream": false,
"messages": [
{
"role": "user",
"content": "Use a ferramenta consultar_status para verificar o serviço demo."
}
],
"tools": [
{
"type": "function",
"function": {
"name": "consultar_status",
"description": "Consulta o status de um serviço de demonstração.",
"parameters": {
"type": "object",
"properties": {
"servico": { "type": "string" }
},
"required": ["servico"]
}
}
}
]
}'
Esse teste não consulta nenhum serviço real. Ele fornece uma descrição de ferramenta fictícia para observar a resposta do modelo. Não há implementação da função nem execução de comando nesse exemplo.
Procure message.tool_calls na resposta. A chamada esperada identifica consultar_status e inclui o argumento servico. Se o modelo apenas escrever essa estrutura dentro de message.content, ainda não houve uma chamada estruturada utilizável.
Interprete o resultado com cuidado:
- Erro explícito de suporte a tools: confira a variante e escolha um modelo compatível.
- Texto sem chamada: repita com um pedido simples e consulte a documentação do modelo; uma tentativa isolada não mede confiabilidade.
- Chamada estruturada correta: o Ollama passou neste teste básico. A integração no OpenClaw e a execução da ferramenta ainda precisam ser verificadas.
- Timeout ou erro de memória: investigue recursos e carregamento, não permissões.
Não existe um tamanho de modelo que garanta tool calling. Um modelo maior pode continuar incompatível; um modelo menor pode passar um teste simples e falhar em uma sequência longa. Compare com a mesma tarefa e o mesmo esquema de ferramenta, sem declarar um vencedor por uma única resposta.
4. Separe chamada de ferramenta de autorização para executar
Se o teste direto funciona e o OpenClaw ainda não age, verifique a ferramenta oferecida ao agente e a política aplicável à sessão. Há três situações diferentes:
| Etapa | Evidência a procurar | Significado |
|---|---|---|
| O modelo solicita a ferramenta | Chamada estruturada no histórico ou diagnóstico | A intenção foi reconhecida |
| O OpenClaw autoriza ou pede aprovação | Decisão de política ou solicitação visível | A execução está sob controle de acesso |
| A ferramenta retorna um resultado | Saída real, erro ou recibo de execução | A ação chegou à implementação |
Um pedido de aprovação não é falha do Ollama. Revise o comando ou a ação proposta e autorize somente o que você pretendia fazer. Se houver bloqueio, investigue o motivo e altere apenas a regra necessária, caso a ação seja legítima.
Para o primeiro teste integrado, escolha uma ferramenta de leitura já habilitada: consultar status ou ler um arquivo de demonstração sem dados pessoais. Não comece com envio de mensagem, exclusão de arquivo, alteração de agenda ou operação externa.
Use um pedido específico, por exemplo:
Use a ferramenta de leitura disponível para consultar o arquivo de demonstração que autorizei. Mostre o resultado real. Se a ferramenta não estiver disponível ou exigir aprovação, informe isso; não invente o conteúdo.
Ajuste o pedido à ferramenta que existe na sua instalação. Um prompt não instala uma integração ausente nem concede acesso a um arquivo fora do escopo permitido.
5. Se o modelo não suporta tools, não esconda a limitação
A documentação oficial de troubleshooting sugere compat.supportsTools: false na entrada do modelo quando um modelo local pequeno continua falhando com esquemas de ferramentas. Isso desativa o suporte anunciado, não adiciona a capacidade que falta.
Essa opção pode ser adequada para um perfil de conversa ou resumo sem ações. Não é a correção para quem precisa que o assistente execute automações. Nesse caso, escolha um modelo com suporte adequado e valide o fluxo completo.
Antes de copiar a opção, confira o formato da entrada do modelo na documentação correspondente à sua versão. Evite misturar fragmentos antigos de configuração com exemplos atuais.
Se o objetivo é operação local, trocar automaticamente para um provedor de nuvem muda o destino dos dados. Faça essa escolha conscientemente, considerando privacidade e custos. O guia de privacidade na IA local explica por que “OpenClaw instalado no computador” e “inferência totalmente local” não são sinônimos.
Checklist para considerar o problema resolvido
- O Gateway alcança o host Ollama correto.
- O modelo selecionado existe nesse host.
- O provedor ativo usa
api: "ollama"ebaseUrlsem/v1. - O teste direto retorna
message.tool_calls, não apenas texto parecido com JSON. - A ferramenta de teste está disponível para o agente.
- A política permite a leitura ou pede a aprovação esperada.
- O histórico mostra um resultado real da ferramenta.
- A mesma tarefa funciona novamente em uma sessão de teste.
Só depois acrescente mais ferramentas ou ações com efeitos externos. Para configurar a integração desde o começo, siga o guia de Ollama no OpenClaw. Para entender a divisão de responsabilidades entre os produtos, leia OpenClaw vs Ollama.
O que incluir ao pedir ajuda
Registre versões do OpenClaw e Ollama, tag exata do modelo, tipo de instalação, host acessado e resultado do teste direto. Inclua o fragmento de configuração do provedor e o erro pertinente, removendo tokens, senhas, dados pessoais e conteúdo privado das conversas.
Diga se o problema é “não gera chamada”, “gera JSON como texto”, “aguarda aprovação” ou “a ferramenta retorna erro”. Essa classificação evita que alguém recomende trocar GPU para resolver uma política ou reinstalar o modelo para corrigir uma URL.
Perguntas frequentes
Por que o Ollama responde com JSON em vez de executar a ferramenta?
A documentação do OpenClaw aponta o modo compatível com OpenAI e a incapacidade do modelo de lidar com esquemas de ferramentas como causas comuns. Confira o protocolo nativo, a URL sem /v1 e o suporte a tools da variante instalada.
Qual URL devo usar para Ollama no OpenClaw?
No provedor nativo, use a raiz do host, como http://localhost:11434, com api: "ollama". Não acrescente /v1 nem /api/chat ao baseUrl. Em container ou servidor remoto, substitua localhost pelo endereço alcançável pelo Gateway.
Um modelo que conversa bem também executa ferramentas?
Não necessariamente. Conversação e geração de chamadas estruturadas são capacidades diferentes. Verifique o suporte declarado do modelo e teste a tag exata com uma ferramenta simples antes de confiar em automações.
O teste com curl executa alguma ação no meu computador?
O exemplo deste guia envia um pedido de inferência e um esquema fictício ao Ollama. Ele não implementa nem executa a ferramenta descrita. A execução real depende de um cliente, como o OpenClaw, que interprete a chamada e invoque a ferramenta autorizada.
Preciso desativar as aprovações para o Ollama funcionar?
Não. Aprovações pertencem à política de execução, não ao suporte a tool calling do modelo. Mantenha as proteções e valide primeiro uma ferramenta de leitura com autorização restrita.
supportsTools false corrige a execução de ferramentas?
Não. A opção informa que aquele modelo não deve ser tratado como compatível com ferramentas. Serve para uso sem tools; para automações, escolha um modelo compatível e teste a integração completa.
Fontes e próximos passos
Referências oficiais consultadas em 1º de outubro de 2026:
- Provedor Ollama no OpenClaw: API nativa e alerta sobre o endpoint
/v1. - Troubleshooting do provedor Ollama: conectividade, JSON como texto e limitação de ferramentas.
- Configuração do provedor Ollama: entradas do provedor e endereço personalizado.
- Tool calling na documentação do Ollama: esquemas de ferramentas e ciclo de chamada e resultado.
Os campos e comandos podem evoluir. Confirme a documentação da sua versão antes de aplicar alterações. Se você ainda não instalou o assistente, comece pelo passo a passo de instalação do OpenClaw; se já o usa, valide a leitura antes de avançar para automações.