Ollama

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. agents.defaults.memorySearch.provider can also point at a custom provider id so embeddings use that Ollama endpoint.

auth-profiles.json stores the credential for a provider id; put endpoint settings (baseUrl, api, models, headers, timeouts) in models.providers.<id>. Older flat files such as { "ollama-windows": { "apiKey": "ollama-local" } } are not a runtime format; openclaw doctor --fix rewrites them into 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.
• agents.*.memorySearch.remote.apiKey is sent only to its 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.

Ollama on the same machine as the Gateway, discovered automatically:

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

Do not add a models.providers.ollama block unless you need manual models.

{  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 is OpenClaw's context budget; params.num_ctx is sent to Ollama. Keep them aligned when hardware cannot run the model's full advertised context.

No local daemon, hosted models directly:

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

For the dedicated ollama-cloud provider id instead of this shape, see Ollama Cloud.

Custom provider IDs when running more than one Ollama server; each gets its own host, models, auth, and timeout.

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

OpenClaw strips the active provider prefix (falling back to a bare ollama/ prefix) before calling Ollama, so ollama-large/qwen3.5:27b reaches Ollama as qwen3.5:27b.

Some local models handle simple prompts but struggle with the full agent tool surface. Limit tools and context before touching global runtime settings:

{  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 only when the model or server reliably fails on tool schemas — it trades agent capability for stability. localModelLean removes heavyweight browser, cron, message, media-generation, voice, and PDF tools from the direct agent surface unless explicitly required, and puts larger catalogs behind Tool Search. It does not change Ollama's runtime context or thinking mode. Pair it with params.num_ctx and params.thinking: false for small Qwen-style thinking models that loop or spend their budget on hidden reasoning.

Set api: "openai-completions" explicitly for a proxy behind /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // default: true        apiKey: "ollama-local",        models: [...]      }    }  }}

This mode may not support streaming and tool calling simultaneously; you may need params: { streaming: false } on the model.

OpenClaw injects options.num_ctx by default in this mode so Ollama does not silently fall back to a 4096-token context. If your proxy rejects unknown options fields, disable it:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

For auto-discovered models, OpenClaw uses the context window /api/show reports, including larger PARAMETER num_ctx values from custom Modelfiles; otherwise it falls back to OpenClaw's default Ollama context window.

Provider-level contextWindow, contextTokens, and maxTokens set defaults for every model under that provider and can be overridden per model. contextWindow is OpenClaw's own prompt/compaction budget. Native /api/chat requests leave options.num_ctx unset unless you set params.num_ctx explicitly, so Ollama applies its own model, OLLAMA_CONTEXT_LENGTH, or VRAM-based default; invalid, zero, negative, or non-finite params.num_ctx values are ignored. If an older config used only contextWindow/maxTokens to force native request context, run openclaw doctor --fix to copy those into params.num_ctx. The OpenAI-compatible adapter still injects options.num_ctx by default from the configured params.num_ctx or contextWindow; disable with injectNumCtxForOpenAICompat: false if the upstream rejects options.

Native model entries also accept common Ollama runtime options under params, forwarded as native /api/chat options: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap, and num_thread. A few keys (format, keep_alive, truncate, shift) are forwarded as top-level request fields instead of nested options. OpenClaw only forwards these Ollama request keys, so runtime-only params such as streaming are never sent to Ollama. Use params.think (or params.thinking) to set top-level think; false disables API-level thinking for Qwen-style thinking models.

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

Per-model agents.defaults.models["ollama/<model>"].params.num_ctx also works; the explicit provider model entry wins if both are set.

OpenClaw forwards thinking as Ollama expects it: top-level think, not options.think. Auto-discovered models whose /api/show reports a thinking capability expose /think low, /think medium, /think high, and /think max; non-thinking models expose only /think off.

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

Or set a model default:

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

Per-model params.think/params.thinking can disable or force API thinking for a specific model. OpenClaw preserves that explicit config when the active run only has the implicit off default; a non-off runtime command such as /think medium still overrides it. A truthy thinking request is never sent to a model explicitly marked reasoning: false; a think: false request is always sent regardless.

Models named deepseek-r1, reasoning, reason, or think are treated as reasoning-capable by default — no extra config needed:

ollama pull deepseek-r1:32b

Ollama runs locally and is free, so all model costs are 0 for both auto-discovered and manually defined models.

The bundled Ollama plugin registers a memory embedding provider for memory search. It uses the configured Ollama base URL and API key, calls /api/embed, and batches multiple memory chunks into one input request when possible.

When proxy.enabled=true, embedding requests to the exact host-local loopback origin derived from the configured baseUrl use OpenClaw's guarded direct path instead of the managed forward proxy. The configured hostname must itself be localhost or a loopback IP literal — DNS names that merely resolve to loopback still use the managed proxy path. LAN, tailnet, private-network, and public Ollama hosts always stay on the managed proxy path, and redirects to another host/port do not inherit trust. proxy.loopbackMode: "proxy" routes loopback traffic through the proxy anyway; proxy.loopbackMode: "block" denies it before connecting — see Managed proxy.

Query-time embeddings use retrieval prefixes for models that require or recommend them: nomic-embed-text, qwen3-embedding, and mxbai-embed-large. Document batches stay raw, so existing indexes need no format migration.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default for Ollama. Raise on larger hosts if reindexing is too slow.          nonBatchConcurrency: 1,        },      },    },  },}

For a remote embedding host, keep auth scoped to that host:

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

Ollama uses the native API (/api/chat) by default, which supports streaming and tool calling together — no special config needed.

For native requests, thinking control is forwarded directly: /think off and openclaw agent --thinking off send top-level think: false unless an explicit params.think/params.thinking is configured; /think low|medium|high send the matching effort string; /think max maps to Ollama's highest effort, think: "high".

On WSL2 with NVIDIA/CUDA, the official Ollama Linux installer creates an ollama.service systemd unit with Restart=always. If that service autostarts and loads a GPU-backed model during WSL2 boot, Ollama can pin host memory while loading; Hyper-V memory reclaim cannot always reclaim those pages, so Windows can terminate the WSL2 VM, systemd restarts Ollama, and the loop repeats.

Evidence: repeated WSL2 reboots/terminations, high CPU in app.slice or ollama.service right after WSL2 startup, and SIGTERM from systemd rather than the Linux OOM killer.

OpenClaw logs a startup warning when it detects WSL2, ollama.service enabled with Restart=always, and visible CUDA markers.

Mitigation:

sudo systemctl disable ollama

On the Windows side, add this to %USERPROFILE%\.wslconfig, then run wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Or shorten keep-alive / start Ollama manually only when needed:

export OLLAMA_KEEP_ALIVE=5mollama serve

See ollama/ollama#11317.

Confirm Ollama is running, OLLAMA_API_KEY (or an auth profile) is set, and models.providers.ollama is not defined explicitly:

ollama servecurl http://localhost:11434/api/tags

Pull the model locally, or define it explicitly in models.providers.ollama:

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Verify from the same machine and runtime that runs the Gateway:

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

Common causes:

• baseUrl points at localhost, but the Gateway runs in Docker or on another host.
• The URL uses /v1, selecting OpenAI-compatible behavior instead of native Ollama.
• The remote host needs firewall or LAN binding changes.
• The model is on your laptop's daemon but not the remote one.

Usually the provider is in OpenAI-compatible mode, or the model cannot handle tool schemas. Prefer native mode:

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

If a small local model still fails on tool schemas, set compat.supportsTools: false on that model entry and retest.

Hosted Kimi/GLM responses that are long, non-linguistic symbol runs are treated as a failed provider call rather than a successful reply, so normal retry/fallback/error handling takes over instead of persisting corrupted text into the session.

If it recurs, capture the model name, the current session file, and whether the run used Cloud + Local or Cloud only, then try a fresh session and a fallback model:

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

Large local models can need a long first load. Scope the timeout to the Ollama provider and optionally keep the model loaded between turns:

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

If the host itself is slow to accept connections, timeoutSeconds also extends the guarded connect timeout for this provider.

Many models advertise contexts larger than your hardware can run comfortably. Native Ollama uses its own runtime default unless params.num_ctx is set. Cap both OpenClaw's budget and Ollama's request context for predictable first-token latency:

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

Lower contextWindow if OpenClaw sends too much prompt. Lower params.num_ctx if Ollama's runtime context is too large for the machine. Lower maxTokens if generation runs too long.