Ollama

URLs do Ollama de loopback, rede privada, .local e nome 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 direcionado a um host privado da LAN pode usar apiKey: "ollama-local"; os subagentes resolvem esse marcador por meio do 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 mais antigos, como { "ollama-windows": { "apiKey": "ollama-local" } }, não são um formato de runtime; openclaw doctor --fix os reescreve como um perfil canônico de chave de API ollama-windows:default, com um backup. Um valor baseUrl nesse arquivo legado é irrelevante e deve ser movido para a configuração do provedor.

A autenticação bearer para embeddings de memória do Ollama é limitada 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 seu host remoto de embeddings.
• Um valor de ambiente exclusivamente 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 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 limite de contexto do OpenClaw; params.num_ctx é enviado ao Ollama. Mantenha-os alinhados quando o hardware não conseguir executar todo o contexto anunciado pelo modelo.

Sem daemon local, usando diretamente modelos hospedados:

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 deste formato, consulte Ollama Cloud.

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 (usando como alternativa 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 processam prompts simples, mas têm dificuldades com toda a superfície de ferramentas do agente. Limite as ferramentas e o contexto antes de alterar as configurações globais de runtime:

{  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 confiável com esquemas de ferramentas — isso troca a 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 disponibiliza catálogos maiores por meio da busca de ferramentas. Isso não altera o contexto de runtime nem o modo de raciocínio do Ollama. Combine-o com params.num_ctx e params.thinking: false para pequenos modelos de raciocínio no estilo Qwen que entram em loop ou consomem 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, // padrão: true        apiKey: "ollama-local",        models: [...]      }    }  }}

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

O OpenClaw injeta options.num_ctx por padrão neste modo para que o Ollama não use silenciosamente como alternativa um contexto de 4096 tokens. Se o proxy rejeitar campos options desconhecidos, desative-o:

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

Para modelos descobertos 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, ele usa como alternativa a janela de contexto padrão do Ollama no OpenClaw.

contextWindow, contextTokens e maxTokens no nível do provedor definem os padrões de todos os modelos desse provedor e podem ser substituídos por modelo. contextWindow é o orçamento de prompt/Compaction do próprio OpenClaw. Solicitações nativas /api/chat deixam options.num_ctx indefinido, a menos que params.num_ctx seja definido explicitamente; assim, o Ollama aplica seu próprio padrão baseado no modelo, em OLLAMA_CONTEXT_LENGTH ou na VRAM; valores params.num_ctx inválidos, iguais a zero, negativos ou não finitos são ignorados. Se uma configuração mais antiga usava apenas contextWindow/maxTokens para forçar o contexto de solicitações nativas, 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 com base no 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 runtime 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 solicitação de nível superior, em vez de ficarem aninhadas em options. O OpenClaw encaminha somente essas chaves de solicitação do Ollama, portanto parâmetros exclusivos do runtime, 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 conforme esperado pelo Ollama: think no nível superior, e não options.think. Modelos descobertos automaticamente cujo /api/show informa uma capacidade thinking expõem /think low, /think medium, /think high e /think max; modelos sem raciocínio expõem somente /think off.

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

Ou defina um padrão de modelo:

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

As configurações params.think/params.thinking por modelo podem desativar ou forçar o raciocínio 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 runtime que não seja de desativação, como /think medium, ainda a substitui. Uma solicitação de raciocínio verdadeira nunca é enviada a um modelo explicitamente marcado como reasoning: false; uma solicitação think: false é sempre enviada, independentemente disso.

Modelos chamados deepseek-r1, reasoning, reason ou think são tratados por padrão como compatíveis com raciocínio — 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 pesquisa de memória. Ele usa a URL base e a chave de API configuradas do Ollama, chama /api/embed e agrupa vários trechos de memória em uma única solicitação input quando possível.

Quando proxy.enabled=true, as solicitações de embedding para a origem de loopback local exata derivada do baseUrl configurado usam o caminho direto protegido do OpenClaw em vez do proxy de encaminhamento gerenciado. O nome do 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 na LAN, tailnet, rede privada e internet pública sempre permanecem no caminho do proxy gerenciado, e redirecionamentos para outro host/porta não herdam a confiança. proxy.loopbackMode: "proxy" encaminha o tráfego de loopback pelo proxy mesmo assim; proxy.loopbackMode: "block" o rejeita 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 sem alterações, portanto os índices existentes não precisam de migração de formato.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Padrão do Ollama. Aumente em hosts maiores se a reindexação estiver muito lenta.          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 permite streaming e chamadas de ferramentas em conjunto — nenhuma configuração especial é necessária.

Para solicitações nativas, o controle de raciocínio é encaminhado diretamente: /think off e openclaw agent --thinking off enviam think: false no nível superior, a menos que um params.think/params.thinking explícito esteja configurado; /think low|medium|high enviam a string de esforço correspondente; /think max corresponde ao esforço máximo 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 for iniciado automaticamente e carregar um modelo apoiado por GPU durante a inicialização do WSL2, o Ollama poderá fixar memória do host durante o carregamento; a recuperação de memória do Hyper-V nem sempre consegue recuperar essas páginas, então 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, alto uso de CPU em app.slice ou ollama.service logo após a inicialização do WSL2 e SIGTERM enviado pelo systemd em vez do OOM killer do Linux.

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

Mitigação:

sudo systemctl disable ollama

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

[experimental]autoMemoryReclaim=disabled

Ou reduza o tempo de keep-alive/inicie o Ollama manualmente apenas quando necessário:

export OLLAMA_KEEP_ALIVE=5mollama serve

Consulte ollama/ollama#11317.

Confirme se o Ollama está em execução, se OLLAMA_API_KEY (ou um perfil de autenticação) está definido e se 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  # Veja o que está instaladoollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Ou outro modelo

Verifique na mesma máquina e no mesmo runtime 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 na vinculação à LAN.
• O modelo está no daemon do seu laptop, 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, não como 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 isso ocorrer novamente, capture o nome do modelo, o arquivo da sessão atual e se a execução usou Cloud + Local ou Cloud only; depois, tente uma nova sessão e um modelo de fallback:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Responda exatamente: 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 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 amplia o tempo limite de conexão protegido para esse provedor.

Muitos modelos anunciam contextos maiores do que seu hardware consegue executar confortavelmente. O Ollama nativo usa seu próprio padrão de runtime, 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 um prompt grande demais. Reduza params.num_ctx se o contexto de runtime do Ollama for grande demais para a máquina. Reduza maxTokens se a geração demorar demais.