Ollama

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

Hosts públicos remotos e o 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.

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 gancho 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 de perfil de autenticação planos mais antigos, 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 fica restrita ao host em que foi declarada:

• Uma chave em nível de provedor é enviada somente para o host Ollama desse provedor.
• agents.*.memorySearch.remote.apiKey é enviada 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 para hosts locais ou auto-hospedados.

Use isto quando o Ollama roda na mesma máquina que o Gateway e você quer que o OpenClaw descubra automaticamente os modelos instalados.

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

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

Use URLs nativas do Ollama para hosts de 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 no lado do OpenClaw. params.num_ctx é enviado ao Ollama para a solicitação. Mantenha-os alinhados quando seu hardware não conseguir rodar o contexto completo anunciado do modelo.

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

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

ollama signin
ollama 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 provedores personalizados quando tiver mais de um servidor Ollama. Cada provedor recebe seu próprio host, modelos, autenticação, timeout 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: {
    defaults: {
      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 only when the model or server reliably fails on tool schemas. It trades agent capability for stability. localModelLean removes the browser, cron, and message tools from the agent surface, but it does not change Ollama's runtime context or thinking mode. Pair it with explicit params.num_ctx and params.thinking: false for small Qwen-style thinking models that loop or spend their response budget on hidden reasoning.

Se você precisar usar o endpoint compatível com OpenAI em vez disso (por exemplo, por trá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 oferecer suporte a streaming e chamada de ferramentas simultaneamente. Talvez você precise 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 recue silenciosamente para uma janela de contexto de 4096. Se o 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 informada 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 no nível do 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. Requisiçõ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 em VRAM. Para limitar ou forçar o contexto de runtime por requisição do Ollama sem reconstruir um Modelfile, defina params.num_ctx; valores inválidos, zero, negativos e não finitos são ignorados. O adaptador Ollama compatível com OpenAI ainda injeta options.num_ctx por padrão a partir do params.num_ctx ou contextWindow configurado; desative isso com injectNumCtxForOpenAICompat: false se o seu upstream rejeitar options.

Entradas de modelos Ollama nativas 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 requisiçã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 desativa o thinking no nível da API para modelos de thinking 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 o padrão do agente.

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

openclaw agent --model ollama/gemma4 --thinking off
openclaw 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 desativar ou forçar o thinking da API Ollama para um modelo configurado específico. O OpenClaw preserva esses parâmetros explícitos do 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 roda localmente, portanto todos os custos dos modelos 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 embeddings de memória para pesquisa de memória. Ele usa a URL base do Ollama e a chave de API configuradas, chama o endpoint atual /api/embed do Ollama e agrupa vários blocos de memória em uma requisição input quando possível.

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 o provedor de embedding de pesquisa 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 de embedding remoto, mantenha a autenticação no escopo desse 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 OpenClaw com o Ollama usa a API nativa do Ollama (/api/chat) por padrão, que oferece suporte completo a streaming e chamada de ferramentas simultaneamente. Nenhuma configuração especial é necessária.

Para solicitações nativas de /api/chat, o OpenClaw também encaminha o controle de raciocínio diretamente ao Ollama: /think off e openclaw agent --thinking off enviam think: false no nível superior, a menos que um valor explícito de modelo params.think/params.thinking esteja configurado, enquanto /think low|medium|high enviam a string de esforço think correspondente no nível superior. /think max é mapeado 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 com GPU durante a inicialização do WSL2, o Ollama pode manter memória do host fixada 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 depois da 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, depois execute wsl --shutdown:

[experimental]
autoMemoryReclaim=disabled

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

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Consulte ollama/ollama#11317.

Certifique-se de que o Ollama esteja em execução, que você tenha definido OLLAMA_API_KEY (ou um perfil de autenticação) e que você não tenha definido uma entrada explícita models.providers.ollama:

ollama serve

Verifique se a API está acessível:

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

Se o seu modelo não estiver listado, baixe o modelo localmente ou defina-o explicitamente em models.providers.ollama.

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

Verifique se o Ollama está em execução na porta correta:

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

Verifique a partir da mesma máquina e do mesmo runtime que executam o Gateway:

openclaw gateway status --deep
curl 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, o que seleciona o comportamento compatível com OpenAI em vez do Ollama nativo.
• O host remoto precisa de alterações de firewall ou vinculação à LAN no lado do Ollama.
• O modelo está presente no daemon do seu laptop, 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 a repetição normal, fallback ou tratamento de erro assuma sem persistir o texto corrompido na sessão.

Se isso acontecer repetidamente, capture o nome bruto do modelo, o arquivo da sessão atual e se a execução usou Cloud + Local ou Cloud only; depois, tente uma sessão nova e um modelo de fallback:

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

Modelos locais grandes podem precisar de um primeiro carregamento longo antes que o streaming comece. Mantenha o tempo limite restrito 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 demora para aceitar conexões, timeoutSeconds também estende o tempo limite protegido de conexão do Undici para este provedor.

Muitos modelos do Ollama anunciam contextos maiores do que seu hardware consegue executar confortavelmente. O Ollama nativo usa o padrão de contexto do próprio runtime do Ollama, a menos que você defina params.num_ctx. Limite tanto o orçamento do OpenClaw quanto o contexto de solicitação do Ollama quando quiser 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 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 estiver demorando demais.