---
title: "Ollama no OpenClaw não executa ferramentas: como corrigir"
url: "https://openclaw.ia.br/blog/ollama-openclaw-nao-executa-ferramentas/"
markdown_url: "https://openclaw.ia.br/blog/ollama-openclaw-nao-executa-ferramentas.MD"
description: "Ollama responde com JSON em vez de executar ações no OpenClaw? Verifique a API nativa, o suporte a tools do modelo e as permissões com testes seguros."
date: "2026-10-01"
author: "OpenClaw Brasil"
---

# Ollama no OpenClaw não executa ferramentas: como corrigir

Ollama responde com JSON em vez de executar ações no OpenClaw? Verifique a API nativa, o suporte a tools do modelo e as permissões com testes seguros.


**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](/glossario/tool-use/).

## 1. Confirme qual Ollama o Gateway está acessando

Comece com verificações sem alterações no sistema:

```bash
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](/local/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](/troubleshooting/ollama-modelo-nao-carrega/) e [Gateway não inicia](/troubleshooting/gateway-nao-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 é:

```json
{
  "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:

1. `baseUrl` termina na porta, sem `/v1` e sem `/api/chat`.
2. `api: "ollama"` seleciona o protocolo nativo; o cliente constrói a chamada para `/api/chat`.
3. Corrigir uma entrada chamada `ollama` nã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.

```bash
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](/blog/privacidade-ia-local-openclaw/) 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"` e `baseUrl` sem `/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](/modelos/ollama/). Para entender a divisão de responsabilidades entre os produtos, leia [OpenClaw vs Ollama](/blog/openclaw-vs-ollama-comparativo/).

## 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](https://docs.openclaw.ai/providers/ollama): API nativa e alerta sobre o endpoint `/v1`.
- [Troubleshooting do provedor Ollama](https://docs.openclaw.ai/providers/ollama/troubleshooting): conectividade, JSON como texto e limitação de ferramentas.
- [Configuração do provedor Ollama](https://docs.openclaw.ai/providers/ollama/configuration): entradas do provedor e endereço personalizado.
- [Tool calling na documentação do Ollama](https://docs.ollama.com/capabilities/tool-calling): 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](/instalacao/); se já o usa, valide a leitura antes de avançar para automações.