On this page
On this page
Providers
Ollama model discovery
A successful /api/tags listing also checks configured model names. If
qwen3:8bb is configured but absent from the server, openclaw models list warns
to pull it or fix the name. Doctor and models status show the prepared Gateway
warning too. Omitted :latest tags remain accepted; an offline server produces no
missing-model warning. These warnings never reject a model declaration.
Model discovery (implicit provider)
When OLLAMA_API_KEY (or an auth profile) is set and neither
models.providers.ollama nor another custom provider with api: "ollama" is
defined, OpenClaw discovers models from http://127.0.0.1:11434:
| Behavior | Detail |
|---|---|
| Catalog query | /api/tags |
| Capability detection | Best-effort /api/show reads contextWindow, num_ctx Modelfile parameters, and capabilities (vision/tools/thinking) |
| Vision models | A vision capability from /api/show marks the model image-capable (input: ["text", "image"]) |
| Reasoning detection | Uses the thinking capability from /api/show when available; falls back to a name heuristic (r1, reason, reasoning, think) when Ollama omits capabilities. glm-5.2:cloud, glm-5.3:cloud, glm-5.3-flash:cloud, kimi-k3:cloud, deepseek-v4-flash|pro:cloud, and deepseek-v4.1-flash:cloud are always treated as reasoning regardless of reported capabilities. |
| Token limits | maxTokens defaults to OpenClaw's Ollama max-token cap |
| Costs | All costs are 0 |
When Ollama is in the agent's model scope, an explicit self-hosted endpoint is
discovered even when models.providers.ollama.models lists models, as setup
saves them. Configured models keep their settings; other installed chat models
appear beside them, so a model pulled later shows up on the next model-list
refresh without a config edit or restart. To list only configured models, set
models.mode: "replace" or plugins.entries.ollama.config.discovery.enabled: false.
models.providers.ollama.apiKey alone does not select that provider for Gateway
model browsing.
With native Ollama, discovery also fills a configured model's missing
thinkingLevelMap from that same server. This keeps reasoning separate from answer
text for models that always think, including when reasoning display is off.
Explicit thinking maps and other configured settings are preserved; models using
the OpenAI-compatible API or a different endpoint do not inherit that metadata.
Failed discovery records an unavailable or catalog-authentication failure and keeps the last successful inventory for the same endpoint and credentials. A successful empty response clears discovered models. Manual models stay separate.
Hosted https://ollama.com entries skip discovery because Ollama Cloud models
are provider-managed. Without an explicit Ollama endpoint, a custom provider
with api: "ollama" and a non-loopback baseUrl suppresses ambient localhost
discovery; list that custom provider's models manually (see
Configuration). Loopback custom providers such as
http://127.0.0.2:11434 keep ambient local discovery eligible.
You can use a full ref such as ollama/<pulled-model>:latest without a
hand-written models.json entry; OpenClaw resolves it live. For signed-in
hosts, selecting an unlisted ollama/<model>:cloud ref validates that exact
model with /api/show and adds it to the runtime catalog only if Ollama
confirms metadata — typos still fail as unknown models.
Smoke tests
For a narrow text check that skips the full agent tool surface:
Add --file with an image for a lean vision-model check (accepts PNG/JPEG/WebP;
non-image files are rejected before Ollama is called — use
openclaw infer audio transcribe for audio):
Neither path loads chat tools, memory, or session context. If it succeeds while normal agent replies fail, the issue is likely the model's tool/agent capacity, not the endpoint.
Selecting a model with /model ollama/<model> is an exact user choice: if the
configured baseUrl is unreachable, the next reply fails with the provider
error instead of silently falling back to another configured model.
Isolated cron jobs add one local safety check before starting the agent turn:
if the selected model resolves to a local/private-network/.local Ollama
provider and /api/tags is unreachable, OpenClaw records that run as
skipped with the model in the error text. This endpoint check is cached for
5 minutes per host, so repeated cron jobs against a stopped daemon do not all
launch failing requests.
Live verification. These are contributor commands: run them from a checkout of
the openclaw/openclaw repository with pnpm install already done, not from a
packaged CLI install.
For Ollama Cloud, point the same live test at the hosted endpoint (skips
embeddings by default; force with OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 since a
cloud key may not authorize /api/embed):
To add a model, pull it and it is discovered automatically:
