Skip to main content

​
Auth rules

Loopback, private-network, .local, and bare-hostname Ollama URLs do not need a real bearer token. OpenClaw uses the ollama-local marker for these.
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.
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.
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.
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

1

Run onboarding

Select Ollama, then pick a mode: Cloud + Local, Cloud only, or Local only.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.
2

Select a model

Cloud only prompts for OLLAMA_API_KEY and suggests hosted cloud defaults. Cloud + Local and Local only prompt for an Ollama base URL and inspect installed models. 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.
3

Verify

Non-interactive:
--custom-base-url and --custom-model-id are optional; omitting them uses the local default host and 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.

​
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:
The cloud model list shown during openclaw onboard is populated live from https://ollama.com/api/tags, capped at 500 entries, so the picker reflects the current hosted catalog. If ollama.com is unreachable or returns no models at setup time, OpenClaw falls back to its hardcoded suggested list so onboarding still completes.