Ollama

Local and LAN Ollama hosts do not need a real bearer token. OpenClaw uses the local ollama-local marker only for loopback, private-network, .local, and bare-hostname Ollama base URLs.

Remote public hosts and Ollama Cloud (https://ollama.com) require a real credential through OLLAMA_API_KEY, an auth profile, or the provider's apiKey.

Custom provider ids that set api: "ollama" follow the same rules. For example, an ollama-remote provider that points at a private LAN Ollama host can use apiKey: "ollama-local" and sub-agents will resolve that marker through the Ollama provider hook instead of treating it as a missing credential. Memory search can also set agents.defaults.memorySearch.provider to that custom provider id so embeddings use the matching Ollama endpoint.

auth-profiles.json stores the credential for a provider id. Put endpoint settings (baseUrl, api, model ids, headers, timeouts) in models.providers.<id>. Older flat auth-profile files such as { "ollama-windows": { "apiKey": "ollama-local" } } are not a runtime format; run openclaw doctor --fix to rewrite them to the canonical ollama-windows:default API-key profile with a backup. baseUrl in that file is compatibility noise and should be moved to provider config.

When Ollama is used for memory embeddings, bearer auth is scoped to the host where it was declared:

• A provider-level key is sent only to that provider's Ollama 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, not sent to local or self-hosted hosts by default.

Use this when Ollama runs on the same machine as the Gateway and you want OpenClaw to discover the installed models automatically.

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

This path keeps config minimal. Do not add a models.providers.ollama block unless you want to define models manually.

Use native Ollama URLs for LAN hosts. Do not add /v1.

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

Use this when you do not run a local daemon and want hosted Ollama 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" },
    },
  },
}

Use this when a local or LAN Ollama daemon is signed in with ollama signin and should serve both local models and :cloud models.

ollama signin
ollama pull gemma4

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}

Use custom provider IDs when you have more than one Ollama server. Each provider gets its own host, models, auth, timeout, and model refs.

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

When OpenClaw sends the request, the active provider prefix is stripped so ollama-large/qwen3.5:27b reaches Ollama as qwen3.5:27b.

Some local models can answer simple prompts but struggle with the full agent tool surface. Start by limiting tools and context before changing global runtime settings.

{
  agents: {
    defaults: {
      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 the browser, cron, and message tools from the agent surface, but it does not change Ollama's runtime context or thinking mode. Pair it with explicit params.num_ctx and params.thinking: false for small Qwen-style thinking models that loop or spend their response budget on hidden reasoning.

If you need to use the OpenAI-compatible endpoint instead (for example, behind a proxy that only supports OpenAI format), set api: "openai-completions" explicitly:

{
  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 to disable streaming with params: { streaming: false } in model config.

When api: "openai-completions" is used with Ollama, OpenClaw injects options.num_ctx by default so Ollama does not silently fall back to a 4096 context window. If your proxy/upstream rejects unknown options fields, disable this behavior:

{
  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 reported by Ollama when available, including larger PARAMETER num_ctx values from custom Modelfiles. Otherwise it falls back to the default Ollama context window used by OpenClaw.

You can set provider-level contextWindow, contextTokens, and maxTokens defaults for every model under that Ollama provider, then override them per model when needed. contextWindow is OpenClaw's prompt and compaction budget. Native Ollama requests leave options.num_ctx unset unless you explicitly configure params.num_ctx, so Ollama can apply its own model, OLLAMA_CONTEXT_LENGTH, or VRAM-based default. To cap or force Ollama's per-request runtime context without rebuilding a Modelfile, set params.num_ctx; invalid, zero, negative, and non-finite values are ignored. The OpenAI-compatible Ollama adapter still injects options.num_ctx by default from the configured params.num_ctx or contextWindow; disable that with injectNumCtxForOpenAICompat: false if your upstream rejects options.

Native Ollama model entries also accept the common Ollama runtime options under params, including temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread, and use_mmap. OpenClaw forwards only Ollama request keys, so OpenClaw runtime params such as streaming are not leaked to Ollama. Use params.think or params.thinking to send top-level Ollama 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 works too. If both are configured, the explicit provider model entry wins over the agent default.

For native Ollama models, OpenClaw forwards thinking control as Ollama expects it: top-level think, not options.think. Auto-discovered models whose /api/show response includes the 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 off
openclaw agent --model ollama/gemma4 --thinking low

You can also set a model default:

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

Per-model params.think or params.thinking can disable or force Ollama API thinking for a specific configured model. OpenClaw preserves those explicit model params when the active run only has the implicit default off; non-off runtime commands such as /think medium still override the active run.

OpenClaw treats models with names such as deepseek-r1, reasoning, or think as reasoning-capable by default.

ollama pull deepseek-r1:32b

No additional configuration is needed. OpenClaw marks them automatically.

Ollama is free and runs locally, so all model costs are set to $0. This applies to 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 Ollama's current /api/embed endpoint, and batches multiple memory chunks into one input request when possible.

Query-time embeddings use retrieval prefixes for models that require or recommend them, including nomic-embed-text, qwen3-embedding, and mxbai-embed-large. Memory document batches stay raw so existing indexes do not need a format migration.

To select Ollama as the memory search embedding provider:

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

OpenClaw's Ollama integration uses the native Ollama API (/api/chat) by default, which fully supports streaming and tool calling simultaneously. No special configuration is needed.

For native /api/chat requests, OpenClaw also forwards thinking control directly to Ollama: /think off and openclaw agent --thinking off send top-level think: false unless an explicit model params.think/params.thinking value is configured, while /think low|medium|high send the matching top-level think effort string. /think max maps to Ollama's highest native 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 the model loads. Hyper-V memory reclaim cannot always reclaim those pinned pages, so Windows can terminate the WSL2 VM, systemd starts Ollama again, and the loop repeats.

Common evidence:

• repeated WSL2 reboots or terminations from the Windows side
• high CPU in app.slice or ollama.service shortly after WSL2 startup
• SIGTERM from systemd rather than a Linux OOM-killer event

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

Mitigation:

sudo systemctl disable ollama

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

[experimental]
autoMemoryReclaim=disabled

Set a shorter keep-alive in the Ollama service environment, or start Ollama manually only when you need it:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

See ollama/ollama#11317.

Make sure Ollama is running and that you set OLLAMA_API_KEY (or an auth profile), and that you did not define an explicit models.providers.ollama entry:

ollama serve

Verify that the API is accessible:

curl http://localhost:11434/api/tags

If your model is not listed, either pull the model locally or define it explicitly in models.providers.ollama.

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

Check that Ollama is running on the correct port:

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

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

openclaw gateway status --deep
curl 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, which selects OpenAI-compatible behavior instead of native Ollama.
• The remote host needs firewall or LAN binding changes on the Ollama side.
• The model is present on your laptop's daemon but not on the remote daemon.

This usually means the provider is using OpenAI-compatible mode or the model cannot handle tool schemas.

Prefer native Ollama 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 failed provider output instead of a successful assistant answer. That lets normal retry, fallback, or error handling take over without persisting the corrupted text into the session.

If it happens repeatedly, capture the raw 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" --json
openclaw models set ollama/gemma4

Large local models can need a long first load before streaming begins. Keep the timeout scoped to the Ollama provider, and optionally ask Ollama to 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 Undici connect timeout for this provider.

Many Ollama models advertise contexts that are larger than your hardware can run comfortably. Native Ollama uses Ollama's own runtime context default unless you set params.num_ctx. Cap both OpenClaw's budget and Ollama's request context when you want 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 first if OpenClaw is sending too much prompt. Lower params.num_ctx if Ollama is loading a runtime context that is too large for the machine. Lower maxTokens if generation runs too long.