Ollama setup

Connect OpenClaw to Ollama: auth rules, onboarding, and cloud models through a local host

Auth rules

Local and LAN hosts

Loopback, private-network, .local, and bare-hostname Ollama URLs do not need a real bearer token. OpenClaw uses the ollama-local marker for these.

Remote and Ollama Cloud hosts

Public remote hosts and https://ollama.com require a real credential: OLLAMA_API_KEY, an auth profile, or the provider's apiKey. For direct hosted use, prefer the ollama-cloud provider.

Custom provider ids

A custom provider with api: "ollama" follows the same rules. For example, an ollama-remote provider pointed at a private LAN host can use apiKey: "ollama-local"; sub-agents resolve that marker through the Ollama provider hook instead of treating it as a missing credential. memory.search.provider can also point at a custom provider id so embeddings use that Ollama endpoint.

Auth profiles

SQLite auth stores hold the credential for a provider id; put endpoint settings (baseUrl, api, models, headers, timeouts) in models.providers.<id>. Older flat auth-profiles.json files such as { "ollama-windows": { "apiKey": "ollama-local" } } are not a runtime format; openclaw doctor --fix imports them into SQLite as a canonical ollama-windows:default API-key profile with a backup. A baseUrl value in that legacy file is noise and should move to provider config.

Memory embedding scope

Bearer auth for Ollama memory embeddings is scoped to the host it was declared for:

A provider-level key is sent only to that provider's host.
memory.search.remote.apiKey and per-agent overrides are sent only to their remote embedding host.
A pure OLLAMA_API_KEY env value is treated as the Ollama Cloud convention and is not sent to local/self-hosted hosts by default.

Getting started

Onboarding (recommended)

Run onboarding

openclaw onboard

Select Ollama, then pick a mode: Cloud + Local or Local only. For hosted models without a local Ollama host, choose Ollama Cloud instead.

On a fresh guided setup, OpenClaw first checks the default or configured Ollama host. Automatic discovery considers only models already loaded in memory, as reported by /api/ps, with tool support and at least 16K of context confirmed by /api/show. An eligible model installed on disk but not loaded is not an automatic candidate. The selected route still needs a real completion before OpenClaw saves it; discovery never pulls or loads an idle model.

To use an installed but idle model in desktop Model Setup, choose Choose connection on the Ollama card, then Local only. This explicit setup path can prepare an eligible installed model for the live check without requiring it to be loaded already.

Select a model

Cloud + Local and Local only prompt for an Ollama base URL and inspect installed models; an ollama.com URL is rejected there because hosted access belongs to Ollama Cloud. If no tools-capable model is found, setup can ask permission to pull a recommended model. An installed :latest tag such as gemma4:latest is shown once instead of duplicating gemma4. Cloud + Local also checks whether the host is signed in for cloud access.

Verify

openclaw models list --provider ollama

Non-interactive:

openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b"

--custom-base-url and --custom-model-id are optional. Omitting the base URL uses the local default host. Without a model ID, setup prefers an installed model with tool support and at least 16K of context, favoring non-reasoning models and then smaller models. If none qualifies, it tries the gemma4 suggested model.

A local model advertised as embedding-only cannot be selected as the chat default. Setup reports an error and leaves the existing configuration intact; reset preflight also rejects an explicitly selected embedding-only model or an inventory advertised as entirely embedding-only. Models that support both completion and embeddings remain eligible.

Existing configured embedding rows are not deleted. Remove them from models.providers.ollama.models, or rerun Ollama onboarding to rebuild the list. Re-onboarding replaces that provider's model catalog, so preserve any custom model entries you want to keep before running it.

Manual setup

Install and start Ollama

Get it from ollama.com/download, then pull a model:

ollama pull gemma4

For hybrid cloud access, run ollama signin on the same host.

Set a credential

For a local or LAN host, any value works:

export OLLAMA_API_KEY="ollama-local"

For https://ollama.com, use the real key instead:

export OLLAMA_API_KEY="your-real-key"

Or in config: openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY".

Select the model

openclaw models list
openclaw models set ollama/gemma4

Or in config:

{
  agents: {
    defaults: {
      model: { primary: "ollama/gemma4" },
    },
  },
}

Cloud models through a local host

Cloud + Local routes both local and :cloud models through one reachable Ollama host — this is Ollama's hybrid flow and the mode to pick during setup when you want both.

OpenClaw prompts for the base URL, discovers local models, and checks ollama signin status. When signed in, it suggests hosted defaults (minimax-m2.7:cloud, minimax-m3:cloud, kimi-k3:cloud, glm-5.1:cloud, glm-5.2:cloud). If not signed in, setup stays local-only until you run ollama signin.

For cloud-only access without a local daemon, use openclaw onboard --auth-choice ollama-cloud and see Ollama Cloud — that path does not need ollama signin or a running server:

openclaw onboard --auth-choice ollama-cloud
openclaw models set ollama-cloud/minimax-m2.7:cloud

The Ollama Cloud model list comes from live https://ollama.com/api/tags discovery with your key, so the picker reflects the current hosted catalog. Without a usable key, OpenClaw shows its bundled Ollama Cloud catalog.