# Ollama setup

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

- 网址：https://funcoding.ai/agents/openclaw/providers/ollama/setup/
- 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/providers/ollama/setup

---
## Auth rules

<details>
<summary>Local and LAN hosts</summary>

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

</details>

<details>
<summary>Remote and Ollama Cloud hosts</summary>

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.

</details>

<details>
<summary>Custom provider ids</summary>

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.

</details>

<details>
<summary>Auth profiles</summary>

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.

</details>

<details>
<summary>Memory embedding scope</summary>

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.

</details>

## Getting started

**Onboarding (recommended)**

**Run onboarding**

```bash
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**

```bash
openclaw models list --provider ollama
```

Non-interactive:

```bash
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](https://ollama.com/download), then pull a model:

```bash
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:

```bash
export OLLAMA_API_KEY="ollama-local"
```

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

```bash
export OLLAMA_API_KEY="your-real-key"
```

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

**Select the model**

```bash
openclaw models list
openclaw models set ollama/gemma4
```

Or in config:

```json5
{
  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](https://funcoding.ai/agents/openclaw/providers/ollama-cloud/) — that path does not need `ollama signin` or a running server:

```bash
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.