Ollama

Hosts Ollama locais e em LAN não precisam de um token bearer real. OpenClaw usa o marcador local ollama-local apenas para URLs base do Ollama de loopback, rede privada, .local e nomes de host simples.

Hosts públicos remotos e Ollama Cloud (https://ollama.com) exigem uma credencial real por meio de 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 que definem api: "ollama" seguem as mesmas regras. Por exemplo, um provedor ollama-remote que aponta para um host Ollama em uma LAN privada pode usar apiKey: "ollama-local" e subagentes resolverão esse marcador por meio do hook do provedor Ollama em vez de tratá-lo como uma credencial ausente. A busca de memória também pode definir agents.defaults.memorySearch.provider para esse id de provedor personalizado, para que os embeddings usem o endpoint Ollama correspondente.

auth-profiles.json armazena a credencial para um id de provedor. Coloque configurações de endpoint (baseUrl, api, ids de modelo, cabeçalhos, tempos limite) em models.providers.<id>. Arquivos antigos de perfil de autenticação planos, como { "ollama-windows": { "apiKey": "ollama-local" } }, não são um formato de runtime; execute openclaw doctor --fix para reescrevê-los para o perfil de chave de API canônico ollama-windows:default com um backup. baseUrl nesse arquivo é ruído de compatibilidade e deve ser movido para a configuração do provedor.

Quando o Ollama é usado para embeddings de memória, a autenticação bearer é escopada ao host onde foi declarada:

• Uma chave no nível do provedor é enviada somente para o host Ollama desse provedor.
• agents.*.memorySearch.remote.apiKey é enviado somente para seu host remoto de embeddings.
• Um valor de env puro OLLAMA_API_KEY é tratado como a convenção do Ollama Cloud, não enviado por padrão a hosts locais ou auto-hospedados.

Use isto quando o Ollama estiver em execução na mesma máquina que o Gateway e você quiser que o OpenClaw descubra os modelos instalados automaticamente.

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

Este caminho mantém a configuração mínima. Não adicione um bloco models.providers.ollama a menos que você queira definir modelos manualmente.

Use URLs nativas do Ollama para hosts na LAN. Não adicione /v1.

{  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 lado do OpenClaw. params.num_ctx é enviado ao Ollama para a solicitação. Mantenha-os alinhados quando seu hardware não conseguir executar todo o contexto anunciado do modelo.

Use isto quando você não executa um daemon local e quer modelos hospedados do Ollama 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" },    },  },}

Use isto quando um daemon Ollama local ou na LAN estiver autenticado com ollama signin e deve servir tanto modelos locais quanto modelos :cloud.

ollama signinollama pull gemma4

{  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        models: [          { id: "gemma4", name: "gemma4", input: ["text"] },          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },        ],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama/gemma4",        fallbacks: ["ollama/kimi-k2.5:cloud"],      },    },  },}

Use IDs de provedor personalizados quando você tiver mais de um servidor Ollama. Cada provedor recebe seu próprio host, modelos, autenticação, tempo limite e referências de modelo.

{  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"],      },    },  },}

Quando o OpenClaw envia a solicitação, o prefixo do provedor ativo é removido para que ollama-large/qwen3.5:27b chegue ao Ollama como qwen3.5:27b.

Alguns modelos locais conseguem responder a prompts simples, mas têm dificuldade com toda a superfície de ferramentas do agente. Comece limitando ferramentas e contexto antes de alterar 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 em esquemas de ferramentas. Isso troca capacidade do agente por estabilidade. localModelLean remove as ferramentas de navegador, cron e mensagens da superfície direta do agente e coloca catálogos maiores por padrão atrás de controles estruturados de Busca de Ferramentas, exceto quando uma execução precisa manter semântica de entrega direta de mensagens, mas não altera o contexto de runtime nem o modo de pensamento do Ollama. Combine com params.num_ctx explícito e params.thinking: false para pequenos modelos de pensamento no estilo Qwen que entram em loop ou gastam o orçamento de resposta em raciocínio oculto.

Se você precisar usar o endpoint compatível com OpenAI (por exemplo, atrás de um proxy que só aceita o formato OpenAI), defina api: "openai-completions" explicitamente:

{  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 ser compatível com streaming e chamadas de ferramenta simultaneamente. Talvez seja necessário desativar o streaming com params: { streaming: false } na configuração do modelo.

Quando api: "openai-completions" é usado com Ollama, o OpenClaw injeta options.num_ctx por padrão para que o Ollama não reverta silenciosamente para uma janela de contexto de 4096. Se seu proxy/upstream rejeitar campos options desconhecidos, desative este comportamento:

{  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 relatada pelo Ollama quando disponível, incluindo valores maiores de PARAMETER num_ctx de Modelfiles personalizados. Caso contrário, ele recorre à janela de contexto padrão do Ollama usada pelo OpenClaw.

Você pode definir padrões contextWindow, contextTokens e maxTokens em nível de provedor para todos os modelos sob esse provedor Ollama e, em seguida, substituí-los por modelo quando necessário. contextWindow é o orçamento de prompt e Compaction do OpenClaw. Solicitações nativas do Ollama deixam options.num_ctx indefinido, a menos que você configure explicitamente params.num_ctx, para que o Ollama possa aplicar seu próprio padrão baseado no modelo, em OLLAMA_CONTEXT_LENGTH ou na VRAM. Para limitar ou forçar o contexto de runtime por solicitação do Ollama sem reconstruir um Modelfile, defina params.num_ctx; valores inválidos, zero, negativos e não finitos são ignorados. Se você atualizou uma configuração antiga que usava apenas contextWindow ou maxTokens para forçar um contexto de solicitação nativa do Ollama, execute openclaw doctor --fix para copiar esses orçamentos explícitos de provedor ou modelo para params.num_ctx. O adaptador compatível com OpenAI do Ollama ainda injeta options.num_ctx por padrão a partir de params.num_ctx ou contextWindow configurado; desabilite isso com injectNumCtxForOpenAICompat: false se seu upstream rejeitar options.

Entradas de modelos nativos do Ollama também aceitam as opções comuns de runtime do Ollama em params, incluindo temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread e use_mmap. O OpenClaw encaminha apenas chaves de solicitação do Ollama, portanto parâmetros de runtime do OpenClaw, como streaming, não vazam para o Ollama. Use params.think ou params.thinking para enviar think de nível superior do Ollama; false desabilita o pensamento em nível de API para modelos de pensamento 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. Se ambos estiverem configurados, a entrada explícita de modelo do provedor vence sobre o padrão do agente.

Para modelos nativos do Ollama, o OpenClaw encaminha o controle de pensamento como o Ollama espera: think de nível superior, não options.think. Modelos descobertos automaticamente cuja resposta de /api/show inclui a capacidade thinking expõem /think low, /think medium, /think high e /think max; modelos sem pensamento expõem apenas /think off.

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

Você também pode definir um padrão de modelo:

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

params.think ou params.thinking por modelo pode desabilitar ou forçar o pensamento da API do Ollama para um modelo configurado específico. O OpenClaw preserva esses parâmetros explícitos de modelo quando a execução ativa tem apenas o padrão implícito off; comandos de runtime diferentes de off, como /think medium, ainda substituem a execução ativa.

O OpenClaw trata modelos com nomes como deepseek-r1, reasoning ou think como capazes de raciocínio por padrão.

ollama pull deepseek-r1:32b

Nenhuma configuração adicional é necessária. O OpenClaw os marca automaticamente.

O Ollama é gratuito e executa localmente, portanto todos os custos de modelo são definidos como US$ 0. Isso se aplica tanto a modelos descobertos automaticamente quanto a modelos definidos manualmente.

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

Quando proxy.enabled=true, solicitações de embedding de memória do Ollama para a origem host-local loopback exata derivada do baseUrl configurado usam o caminho direto protegido do OpenClaw em vez do proxy encaminhado gerenciado. O nome de host configurado deve ser ele próprio localhost ou um literal de IP loopback; nomes DNS que apenas resolvem para loopback ainda usam o caminho de proxy gerenciado. Hosts Ollama em LAN, tailnet, rede privada e públicos também permanecem no caminho de proxy gerenciado. Redirecionamentos para outro host ou porta não herdam confiança. Operadores ainda podem definir a configuração global proxy.loopbackMode: "proxy" para enviar tráfego loopback pelo proxy, ou proxy.loopbackMode: "block" para negar conexões loopback antes de abrir uma conexão; consulte Proxy gerenciado para o efeito dessa configuração em todo o processo.

Embeddings em tempo de consulta usam prefixos de recuperação para modelos que os exigem ou recomendam, incluindo nomic-embed-text, qwen3-embedding e mxbai-embed-large. Lotes de documentos de memória permanecem brutos para que índices existentes não precisem de uma migração de formato.

Para selecionar o Ollama como provedor de embedding de busca de memória:

{  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 embedding, mantenha a autenticação limitada a esse host:

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

A integração do Ollama no OpenClaw usa a API nativa do Ollama (/api/chat) por padrão, que oferece suporte completo a streaming e chamadas de ferramentas simultaneamente. Nenhuma configuração especial é necessária.

Para solicitações nativas de /api/chat, o OpenClaw também encaminha o controle de pensamento diretamente ao Ollama: /think off e openclaw agent --thinking off enviam think: false de nível superior, a menos que um valor explícito de modelo params.think/params.thinking esteja configurado, enquanto /think low|medium|high envia a string de esforço think de nível superior correspondente. /think max mapeia para o maior esforço nativo 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 pode fixar a memória do host enquanto o modelo carrega. A recuperação de memória do Hyper-V nem sempre consegue recuperar essas páginas fixadas, então o Windows pode encerrar a VM WSL2, o systemd inicia o Ollama novamente, e o loop se repete.

Evidências comuns:

• reinicializações ou encerramentos repetidos do WSL2 pelo lado do Windows
• CPU alta em app.slice ou ollama.service pouco após a inicialização do WSL2
• SIGTERM do systemd em vez de um evento do OOM-killer do Linux

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

Mitigação:

sudo systemctl disable ollama

Adicione isto a %USERPROFILE%\.wslconfig no lado do Windows e execute wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Defina um keep-alive mais curto no ambiente de serviço do Ollama ou inicie o Ollama manualmente apenas quando precisar dele:

export OLLAMA_KEEP_ALIVE=5mollama serve

Consulte ollama/ollama#11317.

Verifique se o Ollama está em execução, se você definiu OLLAMA_API_KEY (ou um perfil de autenticação) e se você não definiu uma entrada explícita models.providers.ollama:

ollama serve

Verifique se a API está acessível:

curl http://localhost:11434/api/tags

Se seu modelo não estiver listado, 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 se o Ollama está em execução na porta correta:

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

Verifique a partir da mesma máquina e runtime que executa o Gateway:

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

Causas comuns:

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

Isso geralmente significa que o provedor está usando o modo compatível com OpenAI ou que o modelo não consegue lidar com esquemas de ferramentas.

Prefira o modo nativo do Ollama:

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

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

Respostas hospedadas do Kimi/GLM que são longas sequências de símbolos não linguísticos são tratadas como saída de provedor com falha em vez de uma resposta bem-sucedida do assistente. Isso permite que nova tentativa, fallback ou tratamento de erro normal assuma sem persistir o texto corrompido na sessão.

Se isso acontecer repetidamente, capture o nome bruto do modelo, o arquivo de sessão atual e se a execução usou Cloud + Local ou Cloud only; então 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 um primeiro carregamento longo antes que o streaming comece. Mantenha o timeout limitado ao provedor Ollama e, opcionalmente, peça ao Ollama para manter o modelo carregado entre turnos:

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

Se o próprio host estiver lento para aceitar conexões, timeoutSeconds também estende o tempo limite protegido de conexão do Undici para este provedor.

Muitos modelos Ollama anunciam contextos maiores do que seu hardware consegue executar confortavelmente. O Ollama nativo usa o padrão de contexto de runtime próprio do Ollama, a menos que você defina params.num_ctx. Limite tanto o orçamento do OpenClaw quanto o contexto da solicitação do Ollama quando quiser uma latência previsível do 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 primeiro se o OpenClaw estiver enviando prompt demais. Reduza params.num_ctx se o Ollama estiver carregando um contexto de runtime grande demais para a máquina. Reduza maxTokens se a geração demorar demais.