Deploy Ollama with OpenClaw Locally: Models, Ports, Permissions, and Memory Troubleshooting

The most common Ollama–OpenClaw failures are not simply “the model is too small.” They are usually a wrong port, an OpenAI-compatible URL used with the native provider, a Gateway in another network namespace, or excessive tool permissions. Validate the native Ollama provider first, let OpenClaw discover the model second, and enable memory and automation last.

This guide assumes localhost or a private LAN. It does not expose Ollama or the OpenClaw Gateway to the public internet.

Choose the Model: Chat Is Not the Same as Agent Work

Confirm four things before selecting a model:

1. Ollama has pulled the model and can generate a response.
2. Time to first token and sustained throughput are acceptable on your hardware.
3. A minimal tool task works; a “hello” prompt is not enough.
4. Long tasks have enough context and RAM/VRAM without constant model eviction.

Small models can handle summaries, classification, and fixed workflows. For complex tools, repository understanding, or multi-turn work, test the real task before choosing a larger model or cloud fallback.

1
2
3
4

ollama pull <model>
ollama list
curl http://127.0.0.1:11434/api/tags
curl http://127.0.0.1:11434/api/generate -d '{"model":"<model>","prompt":"Reply with exactly: ok","stream":false}'

Do not troubleshoot OpenClaw until the second request returns ok.

Connect OpenClaw to the Native Ollama API

The native provider needs the native URL. Do not append /v1 to baseUrl; an OpenAI-compatible route can break tool calls or make the model emit tool JSON as plain text.

For a local setup, define a local marker:

1

export OLLAMA_API_KEY="ollama-local"

Use local Ollama during onboarding or configure it explicitly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama"
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "ollama/<model>" }
    }
  }
}

baseUrl is the current key; baseURL remains only for older examples. A local marker is acceptable for loopback, private ranges, .local, or bare hostnames. Public Ollama hosts and Ollama Cloud require real credentials.

Gemma 4 Example

Do not copy an assumed tag such as gemma4:12b. Read the exact local tag:

1
2
3
4
5
6

ollama list
curl http://127.0.0.1:11434/api/generate -d '{
  "model": "<your-gemma-4-tag>",
  "prompt": "Reply with exactly: ok",
  "stream": false
}'

Only after this succeeds should the same tag be written into OpenClaw. The name must exactly match ollama list.

Verify That OpenClaw Uses the Model

1
2
3

openclaw models list --provider ollama
openclaw models status
openclaw infer model run --model ollama/<model> --prompt "Reply with exactly: ok"

If /api/tags works but models list is empty, the provider may be disabled, the Gateway service account may not inherit the environment variable, or the Gateway may run in a container or remote host. Fix the process and network boundary before renaming models at random.

Ports and Containers: localhost Changes Meaning

Ollama normally binds to 127.0.0.1:11434. That is safest when both programs run on the same host, but Docker, WSL, systemd, and remote Gateways change what localhost points to.

Do not bind port 11434 to every public interface merely to make it connect. Prefer a private network or controlled tunnel.

Restrict Permissions Before Enabling Tools

Local inference does not make tool execution safe. Risk comes from what OpenClaw can read, execute, publish, or send.

1. Run it as a normal user, not Administrator or root.
2. Limit the workspace to a dedicated project or sandbox.
3. Require approval for deletion, publishing, outbound messages, credentials, and production access.
4. Keep secrets out of prompts, memory, logs, and Git.
5. Review every Skill or plugin before installation.

Separate “the agent can execute this” from “the agent may execute this automatically.”

Tune Slow Local Models

Prefer provider-level timeouts and model residency over one oversized global Agent timeout:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          { id: "<model>", name: "<model>", params: { keep_alive: "15m" } }
        ]
      }
    }
  }
}

timeoutSeconds covers connection, streaming, and total model-request time. keep_alive reduces repeated cold starts. A shorter Agent-wide timeout can still terminate the task first.

Add a Memory Plugin Only After Inference Works

Use this order for TencentDB Agent Memory:

1
2
3
4

1. Ollama /api/tags and a minimal generation succeed.
2. OpenClaw models list, status, and infer succeed.
3. Enable the plugin and test one explicit fact across sessions.
4. Enable offload last and verify node_id can recover the original tool log.

1
2

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

If memory fails, check whether the plugin is enabled, storage is writable, and a genuinely new session was created. If offload hides full logs, inspect the context-engine slot and after-tool-call patch. See the TencentDB Agent Memory guide.

Quick Failure Map

Summary

A stable Ollama–OpenClaw deployment begins with the native API: validate 127.0.0.1:11434/api and the model, configure the native non-/v1 provider, then grant the smallest necessary tool and memory permissions. Testing the model, port, process boundary, and plugin separately is faster and safer than repeatedly reinstalling everything.