/api/chat), não com o endpoint compatível com OpenAI
/v1. Há suporte a três modos:
ollama-cloud, consulte
Ollama Cloud. Use referências ollama-cloud/<model> quando
quiser manter o roteamento pela nuvem separado de um provedor local ollama.
A chave de configuração canônica é baseUrl. baseURL também é aceita para
exemplos no estilo do SDK da OpenAI, mas novas configurações devem usar baseUrl.
Regras de autenticação
Hosts locais e da LAN
Hosts locais e da LAN
.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 e do Ollama Cloud
Hosts remotos e do Ollama Cloud
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.IDs de provedor personalizados
IDs de provedor personalizados
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.Perfis de autenticação
Perfis de autenticação
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.Escopo dos embeddings de memória
Escopo dos embeddings de memória
- 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.
Primeiros passos
- Integração inicial (recomendado)
- Configuração manual
Execute a integração inicial
Selecione um modelo
Cloud only solicita OLLAMA_API_KEY e sugere padrões hospedados na nuvem. Cloud + Local e Local only solicitam uma URL base do Ollama, descobrem os modelos disponíveis e baixam automaticamente o modelo local selecionado, caso esteja ausente. Uma tag :latest instalada, como gemma4:latest, é exibida uma vez em vez de duplicar gemma4. Cloud + Local também verifica se o host está conectado para acesso à nuvem.Verifique
--custom-base-url e --custom-model-id são opcionais; omiti-los usa o host local padrão e o modelo sugerido gemma4.Modelos de nuvem por meio de um host local
Cloud + Local roteia tanto os modelos locais quanto os modelos :cloud por meio de um único
host Ollama acessível — esse é o fluxo híbrido do Ollama e o modo que deve ser escolhido durante a configuração
quando se deseja usar ambos.
O OpenClaw solicita a URL base, descobre modelos locais e verifica o
status de ollama signin. Quando conectado, ele sugere padrões hospedados
(kimi-k2.5:cloud, minimax-m2.7:cloud, glm-5.1:cloud, glm-5.2:cloud). Quando
não está conectado, a configuração permanece somente local até que se execute ollama signin.
Para acesso somente à nuvem sem um daemon local, use openclaw onboard --auth-choice ollama-cloud e consulte Ollama Cloud — esse caminho não precisa de ollama signin nem de um servidor em execução:
openclaw onboard é preenchida em tempo real a partir de
https://ollama.com/api/tags, limitada a 500 entradas, para que o seletor reflita
o catálogo hospedado atual. Se ollama.com estiver inacessível ou não retornar
modelos no momento da configuração, o OpenClaw recorre à sua lista de sugestões codificada, para que
a integração inicial ainda seja concluída.
Descoberta de modelos (provedor implícito)
QuandoOLLAMA_API_KEY (ou um perfil de autenticação) está definido e nem
models.providers.ollama nem outro provedor personalizado com api: "ollama" está
definido, o OpenClaw descobre modelos em http://127.0.0.1:11434:
models.providers.ollama com um array models explícito ou um
provedor personalizado com api: "ollama" e uma baseUrl que não seja de loopback desativa
a descoberta automática; nesse caso, os modelos devem ser definidos manualmente (consulte
Configuração). Uma entrada models.providers.ollama direcionada ao
https://ollama.com hospedado também ignora a descoberta, pois os modelos do Ollama Cloud
são gerenciados pelo provedor. Provedores personalizados de loopback, como
http://127.0.0.2:11434, ainda são considerados locais e mantêm a descoberta automática.
É possível usar uma referência completa, como ollama/<pulled-model>:latest, sem uma
entrada models.json escrita manualmente; o OpenClaw a resolve em tempo real. Para hosts conectados,
selecionar uma referência ollama/<model>:cloud não listada valida esse modelo exato
com /api/show e o adiciona ao catálogo do runtime somente se o Ollama
confirmar os metadados — erros de digitação ainda falham como modelos desconhecidos.
Testes de fumaça
Para uma verificação de texto restrita que ignora toda a superfície de ferramentas do agente:--file com uma imagem para uma verificação enxuta de modelo de visão (aceita PNG/JPEG/WebP;
arquivos que não sejam imagens são rejeitados antes que o Ollama seja chamado — use
openclaw infer audio transcribe para áudio):
/model ollama/<model> é uma escolha exata do usuário: se o
baseUrl configurado estiver inacessível, a próxima resposta falhará com o erro do provedor,
em vez de recorrer silenciosamente a outro modelo configurado.
Os trabalhos Cron isolados adicionam uma verificação de segurança local antes de iniciar o turno do agente:
se o modelo selecionado for resolvido para um provedor Ollama de rede
local/privada/.local e /api/tags estiver inacessível, o OpenClaw
registrará essa execução como skipped, com o modelo no texto do erro.
Essa verificação do endpoint é armazenada em cache por 5 minutos por host, para que
trabalhos Cron repetidos direcionados a um daemon interrompido não iniciem todos
solicitações que falharão.
Verificação ao vivo:
OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1, pois uma
chave da nuvem pode não autorizar /api/embed):
Inferência local no Node
Os agentes podem delegar uma tarefa curta a um modelo Ollama em um desktop ou Node de servidor pareado. O prompt e a resposta passam pela conexão autenticada existente entre o Gateway e o Node; a solicitação é executada no endpoint Ollama de loopback do próprio Node (http://127.0.0.1:11434).
Inicie o Ollama no Node
Conecte o host do Node
ollama.models e ollama.chat, verifique openclaw nodes pending novamente.Use-o por meio de um agente
node_inference. Os agentes
chamam primeiro action: "discover" e depois action: "run", com um Node
e um modelo desse resultado (run pode omitir o Node quando
exatamente um Node compatível estiver conectado). Por exemplo: “Descubra os
modelos Ollama nos meus Nodes e use o modelo carregado mais rápido para
resumir este texto.”/api/tags, verifica os recursos de /api/show e,
quando disponível, usa /api/ps para priorizar modelos já carregados.
Ela retorna somente modelos locais que o Ollama informa serem compatíveis com
chat (recurso completion) — as linhas do Ollama Cloud e os modelos
exclusivos para embeddings são excluídos. Cada execução desativa o raciocínio
do modelo e limita a saída a 512 tokens por padrão (limite máximo de 8192), a
menos que a chamada da ferramenta solicite um maxTokens diferente;
alguns modelos (por exemplo, GPT-OSS) não permitem desativar o raciocínio e
ainda podem emitir tokens de raciocínio.
Para manter o Ollama em execução em um Node sem expô-lo aos agentes:
openclaw node restart ou interrompa e execute novamente
openclaw node run para uma sessão em primeiro plano). O Node deixa de anunciar
ollama.models e ollama.chat; o próprio Ollama e o provedor Ollama
do Gateway não são afetados. Defina o valor novamente como
true e reinicie para reativar; uma alteração na superfície de
comandos pode exigir novamente a aprovação de openclaw nodes pending após a reconexão.
Verifique os comandos do Node diretamente, sem um turno do agente:
--invoke-timeout limita o tempo que o Node tem para executar o comando;
--timeout limita a chamada geral do Gateway e deve ser maior.
A inferência local no Node sempre usa o endpoint de loopback do próprio Node —
ela não reutiliza um models.providers.ollama.baseUrl remoto/na nuvem configurado. Os
comandos do Node estão disponíveis por padrão em hosts de Node macOS, Linux e
Windows e continuam sujeitos à política normal de pareamento/comandos do Node.
Visão e descrição de imagens
O Plugin Ollama incluído registra o Ollama como um provedor de compreensão de mídia compatível com imagens, permitindo que o OpenClaw encaminhe solicitações explícitas de descrição de imagens e padrões configurados de modelos de imagem por meio de modelos de visão Ollama locais ou hospedados.--model deve ser uma referência <provider/model> completa; quando
definido, infer image describe tenta primeiro esse modelo, em vez de ignorar a
descrição para modelos que já oferecem suporte nativo à visão. Se a chamada
falhar, o OpenClaw poderá continuar por meio de agents.defaults.imageModel.fallbacks; erros de
preparação de arquivos/URLs falham antes que o fallback seja tentado. Use
infer image describe para o fluxo de compreensão de imagens do OpenClaw e
imageModel configurado; use infer model run --file para uma sondagem
multimodal bruta com um prompt personalizado.
Para tornar o Ollama o provedor padrão de compreensão de imagens para mídias recebidas:
ollama/<model> completa. Uma referência
imageModel simples, como qwen2.5vl:7b, será normalizada como
ollama/qwen2.5vl:7b somente quando esse modelo exato estiver listado em
models.providers.ollama.models com input: ["text", "image"] e nenhum outro provedor de imagens
configurado expuser o mesmo ID simples; caso contrário, use explicitamente o
prefixo do provedor.
Modelos locais de visão lentos podem exigir um tempo limite de compreensão de
imagens maior que o dos modelos na nuvem e podem falhar em hardware com recursos
limitados se o Ollama tentar alocar todo o contexto de visão anunciado pelo
modelo. Defina um tempo limite para o recurso e limite num_ctx:
image. models.providers.ollama.timeoutSeconds ainda controla a proteção da
solicitação HTTP subjacente ao Ollama para chamadas normais de modelos.
Verificação ao vivo:
models.providers.ollama.models manualmente, marque explicitamente os modelos
de visão:
/api/show.
Configuração
- Básica (descoberta implícita)
- Explícita (modelos manuais)
- URL base personalizada
Receitas comuns
Substitua os IDs dos modelos pelos nomes exatos deollama list ou
openclaw models list --provider ollama.
Modelo local com descoberta automática
Modelo local com descoberta automática
models.providers.ollama a menos que precise de modelos manuais.Host Ollama na LAN com modelos manuais
Host Ollama na LAN com modelos manuais
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.Somente Ollama Cloud
Somente Ollama Cloud
ollama-cloud em vez deste formato, consulte
Ollama Cloud.Nuvem e ambiente local por meio de um daemon autenticado
Nuvem e ambiente local por meio de um daemon autenticado
Vários hosts do Ollama
Vários hosts do Ollama
ollama/ simples) antes de chamar o Ollama, portanto ollama-large/qwen3.5:27b
chega ao Ollama como qwen3.5:27b.Perfil enxuto de modelo local
Perfil enxuto de modelo local
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.Seleção de modelo
ollama-spark/qwen3:32b, o OpenClaw remove esse prefixo antes de
chamar o Ollama, enviando qwen3:32b.
Para modelos locais lentos, prefira ajustes no escopo do provedor antes de aumentar o tempo limite
de todo o runtime do agente:
timeoutSeconds abrange a solicitação HTTP do modelo: estabelecimento da conexão, cabeçalhos,
streaming do corpo e a interrupção total da busca protegida. params.keep_alive é
encaminhado como keep_alive de nível superior nas solicitações nativas /api/chat; defina-o por
modelo quando o tempo de carregamento na primeira interação for o gargalo.
Verificação rápida
127.0.0.1 pelo host baseUrl. Se curl
funcionar, mas o OpenClaw não, verifique se o Gateway é executado em outra
máquina, contêiner ou conta de serviço.
Pesquisa na Web do Ollama
O OpenClaw inclui a Pesquisa na Web do Ollama como provedorweb_search.
openclaw onboard ou openclaw configure --section web, ou defina:
/api/experimental/web_search
e, em seguida, usa como alternativa o caminho hospedado /api/web_search no mesmo host; normalmente, um
daemon local autenticado responde por meio do proxy local. Chamadas diretas
a https://ollama.com sempre usam o endpoint hospedado /api/web_search.
Configuração avançada
Modo legado compatível com OpenAI
Modo legado compatível com OpenAI
api: "openai-completions" explicitamente para um proxy por trás de
/v1/chat/completions: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:Janelas de contexto
Janelas de contexto
/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.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.Controle de raciocínio
Controle de raciocínio
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.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 de raciocínio
Modelos de raciocínio
deepseek-r1, reasoning, reason ou think são tratados
por padrão como compatíveis com raciocínio — nenhuma configuração adicional é necessária:Custos dos modelos
Custos dos modelos
0 tanto para
modelos descobertos automaticamente quanto para os definidos manualmente.Embeddings de memória
Embeddings de memória
/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.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.Configuração de streaming
Configuração de streaming
/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".Solução de problemas
Loop de falhas no WSL2 (reinicializações repetidas)
Loop de falhas no WSL2 (reinicializações repetidas)
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:%USERPROFILE%\.wslconfig e execute
wsl --shutdown:Ollama não detectado
Ollama não detectado
OLLAMA_API_KEY (ou um perfil de autenticação) está definido
e se models.providers.ollama não está definido explicitamente:Nenhum modelo disponível
Nenhum modelo disponível
models.providers.ollama:Conexão recusada
Conexão recusada
O host remoto funciona com curl, mas não com o OpenClaw
O host remoto funciona com curl, mas não com o OpenClaw
baseUrlaponta paralocalhost, 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.
O modelo gera JSON de ferramenta como texto
O modelo gera JSON de ferramenta como texto
compat.supportsTools: false na entrada desse modelo e teste novamente.Kimi ou GLM retorna símbolos ilegíveis
Kimi ou GLM retorna símbolos ilegíveis
Cloud + Local ou Cloud only; depois, tente uma nova
sessão e um modelo de fallback:O modelo local inativo excede o tempo limite
O modelo local inativo excede o tempo limite
timeoutSeconds também
amplia o tempo limite de conexão protegido para esse provedor.O modelo de contexto amplo está muito lento ou fica sem memória
O modelo de contexto amplo está muito lento ou fica sem memória
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: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.Relacionados
Ollama Cloud
ollama-cloud.