Ollama

URLs do Ollama em loopback, rede privada, .local e nomes de host simples não precisam de um token bearer real. O OpenClaw usa o marcador ollama-local nesses casos.

Hosts remotos públicos e https://ollama.com exigem uma credencial real: OLLAMA_API_KEY, um perfil de autenticação ou o apiKey do provedor. Para uso hospedado direto, prefira o provedor ollama-cloud.

Um provedor personalizado com api: "ollama" segue as mesmas regras. Por exemplo, um provedor ollama-remote apontado para um host em uma LAN privada pode usar apiKey: "ollama-local"; os subagentes resolvem esse marcador pelo hook do provedor Ollama, em vez de tratá-lo como uma credencial ausente. agents.defaults.memorySearch.provider também pode apontar para um ID de provedor personalizado para que os embeddings usem esse endpoint do Ollama.

auth-profiles.json armazena a credencial de um ID de provedor; coloque as configurações do endpoint (baseUrl, api, modelos, cabeçalhos e tempos limite) em models.providers.<id>. Arquivos simples antigos, como { "ollama-windows": { "apiKey": "ollama-local" } }, não são um formato de execução; openclaw doctor --fix os reescreve em um perfil canônico de chave de API ollama-windows:default e cria um backup. Um valor baseUrl nesse arquivo legado é ruído e deve ser movido para a configuração do provedor.

A autenticação bearer para embeddings de memória do Ollama fica restrita ao host para o qual foi declarada:

• Uma chave no nível do provedor é enviada somente ao host desse provedor.
• agents.*.memorySearch.remote.apiKey é enviada somente ao host remoto de embeddings correspondente.
• Um valor definido apenas na variável de ambiente OLLAMA_API_KEY é tratado como a convenção do Ollama Cloud e, por padrão, não é enviado a hosts locais ou auto-hospedados.

Ollama na mesma máquina que o Gateway, descoberto automaticamente:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

Não adicione um bloco models.providers.ollama, a menos que você precise de modelos manuais.

{  models: {    providers: {      ollama: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            reasoning: true,            input: ["text"],            params: {              num_ctx: 32768,              thinking: false,              keep_alive: "15m",            },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/qwen3.5:9b" },    },  },}

contextWindow é o orçamento de contexto do OpenClaw; params.num_ctx é enviado ao Ollama. Mantenha-os alinhados quando o hardware não puder executar todo o contexto anunciado pelo modelo.

Sem daemon local, com modelos hospedados diretamente:

export OLLAMA_API_KEY="your-ollama-api-key"

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            contextWindow: 128000,            maxTokens: 8192,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/kimi-k2.5:cloud" },    },  },}

Para usar o id de provedor dedicado ollama-cloud em vez desse formato, consulte Ollama Cloud.

Use IDs de provedor personalizados ao executar mais de um servidor Ollama; cada um recebe seu próprio host, modelos, autenticação e tempo limite.

{  models: {    providers: {      "ollama-fast": {        baseUrl: "http://mini.local:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],      },      "ollama-large": {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 420,        contextWindow: 131072,        maxTokens: 16384,        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama-fast/gemma4",        fallbacks: ["ollama-large/qwen3.5:27b"],      },    },  },}

O OpenClaw remove o prefixo do provedor ativo (recorrendo a um prefixo ollama/ simples) antes de chamar o Ollama; portanto, ollama-large/qwen3.5:27b chega ao Ollama como qwen3.5:27b.

Alguns modelos locais lidam com prompts simples, mas têm dificuldades com o conjunto completo de ferramentas do agente. Limite as ferramentas e o contexto antes de alterar as configurações globais de execução:

{  agents: {    list: [      {        id: "local",        experimental: {          localModelLean: true,        },        model: { primary: "ollama/gemma4" },      },    ],  },  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [          {            id: "gemma4",            name: "gemma4",            input: ["text"],            params: { num_ctx: 32768 },            compat: { supportsTools: false },          },        ],      },    },  },}

Use compat.supportsTools: false somente quando o modelo ou servidor falhar de forma consistente com esquemas de ferramentas — isso troca capacidade do agente por estabilidade. localModelLean remove as ferramentas pesadas de navegador, Cron, mensagens, geração de mídia, voz e PDF da superfície direta do agente, salvo quando forem explicitamente necessárias, e coloca catálogos maiores por trás da Busca de Ferramentas. Isso não altera o contexto de execução nem o modo de raciocínio do Ollama. Combine-o com params.num_ctx e params.thinking: false para modelos pequenos de raciocínio no estilo Qwen que entram em loop ou gastam seu orçamento com raciocínio oculto.

Defina api: "openai-completions" explicitamente para um proxy por trás de /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // default: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Este modo pode não oferecer suporte simultâneo a transmissão e chamada de ferramentas; talvez seja necessário usar params: { streaming: false } no modelo.

Por padrão, o OpenClaw injeta options.num_ctx neste modo para que o Ollama não retorne silenciosamente a um contexto de 4.096 tokens. Se o seu proxy rejeitar campos options desconhecidos, desative esse comportamento:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

Para modelos detectados automaticamente, o OpenClaw usa a janela de contexto informada por /api/show, incluindo valores maiores de PARAMETER num_ctx provenientes de Modelfiles personalizados; caso contrário, recorre à janela de contexto padrão do Ollama no OpenClaw.

contextWindow, contextTokens e maxTokens no nível do provedor definem padrões para todos os modelos desse provedor e podem ser substituídos individualmente por modelo. contextWindow é o orçamento de prompt/Compaction do próprio OpenClaw. As requisições nativas a /api/chat deixam options.num_ctx sem definição, a menos que você defina params.num_ctx explicitamente; assim, o Ollama aplica o padrão do próprio modelo, de OLLAMA_CONTEXT_LENGTH ou baseado em VRAM. Valores inválidos, iguais a zero, negativos ou não finitos de params.num_ctx são ignorados. Se uma configuração mais antiga usava somente contextWindow/maxTokens para forçar o contexto da requisição nativa, execute openclaw doctor --fix para copiá-los para params.num_ctx. O adaptador compatível com OpenAI ainda injeta options.num_ctx por padrão a partir de params.num_ctx ou contextWindow configurado; desative com injectNumCtxForOpenAICompat: false se o serviço upstream rejeitar options.

As entradas de modelos nativos também aceitam opções comuns de execução do Ollama em params, encaminhadas como options nativas de /api/chat: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap e num_thread. Algumas chaves (format, keep_alive, truncate, shift) são encaminhadas como campos de nível superior da requisição, em vez de options aninhadas. O OpenClaw encaminha somente essas chaves de requisição do Ollama; portanto, parâmetros exclusivos da execução, como streaming, nunca são enviados ao Ollama. Use params.think (ou params.thinking) para definir think no nível superior; false desativa o raciocínio no nível da API para modelos de raciocínio no estilo Qwen.

{  models: {    providers: {      ollama: {        contextWindow: 32768,        models: [          {            id: "llama3.3",            contextWindow: 131072,            maxTokens: 65536,            params: {              num_ctx: 32768,              temperature: 0.7,              top_p: 0.9,              thinking: false,            },          }        ]      }    }  }}

agents.defaults.models["ollama/<model>"].params.num_ctx por modelo também funciona; a entrada explícita do modelo no provedor prevalece se ambos estiverem definidos.

O OpenClaw encaminha o raciocínio como o Ollama espera: think no nível superior, e não options.think. Modelos detectados automaticamente cujo /api/show informa uma capacidade thinking oferecem /think low, /think medium, /think high e /think max; modelos sem raciocínio oferecem apenas /think off.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

Ou defina um padrão para o modelo:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

params.think/params.thinking por modelo pode desativar ou forçar o pensamento da API para um modelo específico. O OpenClaw preserva essa configuração explícita quando a execução ativa tem apenas o padrão implícito off; um comando de execução diferente de off, como /think medium, ainda a substitui. Uma solicitação de pensamento verdadeira nunca é enviada a um modelo marcado explicitamente com reasoning: false; uma solicitação think: false é sempre enviada, independentemente disso.

Modelos chamados deepseek-r1, reasoning, reason ou think são tratados como compatíveis com raciocínio por padrão — nenhuma configuração adicional é necessária:

ollama pull deepseek-r1:32b

O Ollama é executado localmente e é gratuito, portanto todos os custos dos modelos são 0, tanto para modelos descobertos automaticamente quanto para os definidos manualmente.

O Plugin Ollama incluído registra um provedor de embeddings de memória para a busca na memória. Ele usa a URL-base e a chave de API configuradas do Ollama, chama /api/embed e agrupa vários fragmentos de memória em uma única solicitação input quando possível.

Quando proxy.enabled=true, as solicitações de embedding para a origem exata de local loopback do host derivada da baseUrl configurada usam o caminho direto protegido do OpenClaw em vez do proxy de encaminhamento gerenciado. O nome de host configurado deve ser localhost ou um literal de IP de loopback — nomes DNS que apenas resolvem para loopback ainda usam o caminho do proxy gerenciado. Hosts Ollama da LAN, da tailnet, de rede privada e públicos sempre permanecem no caminho do proxy gerenciado, e redirecionamentos para outro host/porta não herdam confiança. proxy.loopbackMode: "proxy" encaminha o tráfego de loopback pelo proxy mesmo assim; proxy.loopbackMode: "block" o nega antes da conexão — consulte Proxy gerenciado.

Os embeddings durante a consulta usam prefixos de recuperação para modelos que os exigem ou recomendam: nomic-embed-text, qwen3-embedding e mxbai-embed-large. Os lotes de documentos permanecem brutos, portanto os índices existentes não precisam de migração de formato.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default for Ollama. Raise on larger hosts if reindexing is too slow.          nonBatchConcurrency: 1,        },      },    },  },}

Para um host remoto de embeddings, mantenha a autenticação restrita a esse host:

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        model: "nomic-embed-text",        remote: {          baseUrl: "http://gpu-box.local:11434",          apiKey: "ollama-local",          nonBatchConcurrency: 2,        },      },    },  },}

O Ollama usa a API nativa (/api/chat) por padrão, que oferece suporte simultâneo a streaming e chamadas de ferramentas — nenhuma configuração especial é necessária.

Para solicitações nativas, o controle de pensamento é encaminhado diretamente: /think off e openclaw agent --thinking off enviam think: false no nível superior, a menos que params.think/params.thinking esteja configurado explicitamente; /think low|medium|high envia a string de esforço correspondente; /think max é mapeado para o maior esforço do Ollama, think: "high".

No WSL2 com NVIDIA/CUDA, o instalador oficial do Ollama para Linux cria uma unidade systemd ollama.service com Restart=always. Se esse serviço iniciar automaticamente e carregar um modelo apoiado por GPU durante a inicialização do WSL2, o Ollama poderá reter a memória do host durante o carregamento; a recuperação de memória do Hyper-V nem sempre consegue recuperar essas páginas, portanto o Windows pode encerrar a VM do WSL2, o systemd reinicia o Ollama e o ciclo se repete.

Evidências: reinicializações/encerramentos repetidos do WSL2, uso elevado de CPU em app.slice ou ollama.service logo após a inicialização do WSL2 e SIGTERM enviado pelo systemd, em vez do eliminador de processos por falta de memória do Linux.

O OpenClaw registra um aviso de inicialização quando detecta o WSL2, ollama.service habilitado com Restart=always e marcadores CUDA visíveis.

Mitigação:

sudo systemctl disable ollama

No Windows, adicione o seguinte a %USERPROFILE%\.wslconfig e execute wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Como alternativa, reduza o tempo de manutenção da conexão/inicie o Ollama manualmente apenas quando necessário:

export OLLAMA_KEEP_ALIVE=5mollama serve

Consulte ollama/ollama#11317.

Confirme que o Ollama está em execução, que OLLAMA_API_KEY (ou um perfil de autenticação) está definido e que models.providers.ollama não está definido explicitamente:

ollama servecurl http://localhost:11434/api/tags

Baixe o modelo localmente ou defina-o explicitamente em models.providers.ollama:

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Verifique na mesma máquina e no mesmo ambiente de execução que executa o Gateway:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

Causas comuns:

• baseUrl aponta para localhost, mas o Gateway é executado no Docker ou em outro host.
• A URL usa /v1, selecionando o comportamento compatível com OpenAI em vez do Ollama nativo.
• O host remoto precisa de alterações no firewall ou no vínculo da LAN.
• O modelo está no daemon do seu notebook, mas não no remoto.

Normalmente, o provedor está no modo compatível com OpenAI ou o modelo não consegue processar esquemas de ferramentas. Prefira o modo nativo:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

Se um modelo local pequeno ainda falhar com esquemas de ferramentas, defina compat.supportsTools: false na entrada desse modelo e teste novamente.

Respostas hospedadas do Kimi/GLM que consistem em sequências longas de símbolos não linguísticos são tratadas como uma chamada de provedor com falha, em vez de uma resposta bem-sucedida, para que o tratamento normal de repetição/fallback/erro assuma o controle, em vez de persistir texto corrompido na sessão.

Se ocorrer novamente, capture o nome do modelo, o arquivo da sessão atual e se a execução usou Cloud + Local ou Cloud only; em seguida, tente uma nova sessão e um modelo de fallback:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

Modelos locais grandes podem precisar de muito tempo no primeiro carregamento. Restrinja o tempo limite ao provedor Ollama e, opcionalmente, mantenha o modelo carregado entre as interações:

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

Se o próprio host demorar para aceitar conexões, timeoutSeconds também estenderá o tempo limite protegido de conexão desse provedor.

Muitos modelos anunciam contextos maiores do que seu hardware consegue executar confortavelmente. O Ollama nativo usa seu próprio padrão de ambiente de execução, a menos que params.num_ctx esteja definido. Limite tanto o orçamento do OpenClaw quanto o contexto da solicitação do Ollama para obter uma latência previsível até o primeiro token:

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

Reduza contextWindow se o OpenClaw enviar conteúdo demais no prompt. Reduza params.num_ctx se o contexto do ambiente de execução do Ollama for grande demais para a máquina. Reduza maxTokens se a geração demorar demais.