OpenClaw with Ollama: Run Your Own AI Agent Locally, Safely (Linux, Windows, Mac)

What you get in one minute#

OpenClaw is an open-source AI assistant that runs on your own computer and can take real actions - read files, browse, run commands, answer in chat apps - using whatever model you connect. Here we connect a local model through Ollama, so prompts stay on your machine.

At a glance#

• What you get: a personal AI agent that lives on your computer, answers in a web page (and optionally in chat apps), and uses a model that never leaves your machine.
• Time: about 30 minutes, plus the model download.
• Difficulty: medium. Docker basics help. Safety choices matter more than the commands.
• You need: Docker with Compose v2, a few GB of free disk, and enough memory for the model you pick.
• Most important rule: an agent can act on your files and messages. Start locked down and open things one at a time.

People like it because it is one agent for many places: a web page, Telegram, WhatsApp, Discord and more. It is MIT licensed and developed by the OpenClaw Foundation.

That power is also the risk. An agent that can run commands or send messages for you can be tricked by a message or a skill you should not have trusted. This guide is built around that. Read the safety parts, not only the install parts.

Which version, and why (checked 2026-10-26). OpenClaw ships almost daily. We looked at GitHub issues for 2026.10.7. The open reports are mostly about upgrading from older versions (a startup hang after an update, an invalid-config update failure) and about one provider. We found no report of a failed fresh Docker install or lost data, so this guide uses 2026.10.7. If you hit trouble, 2026.9.34 is the official fallback. Use only official images from ghcr.io/openclaw/openclaw or openclaw/openclaw.

How it fits together#

You open the Control UI in your browser. The Gateway (the agent) asks Ollama for answers and reads and writes one workspace folder. Everything else is optional and riskier.

Before you start#

Check your tools:

docker --version
docker compose version

Checklist:

• [ ] Docker runs (docker ps works)
• [ ] Port 18789 is free on your computer
• [ ] You decided which folder the agent may touch (we use a dedicated workspace folder)
• [ ] You are not planning to put this on the open internet

Tested on 2026-10-26: Linux = not run, Windows = not run, Mac = not run. Every command is checked against the official docs and files listed in Sources; we did not execute them. The official docs win if a command differs.

Step 1: Create the folders and secrets#

All data lives under docker_volumes/openclaw in your home folder. The .env file holds the Gateway token, which is the password for the web page.

Linux#

mkdir -p "$HOME/docker_volumes/openclaw/"{config,workspace,secrets,ollama,backups}
cd "$HOME/docker_volumes/openclaw"
umask 077
printf 'DATA_ROOT=%s/docker_volumes/openclaw\n' "$HOME" > .env
printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" >> .env
sudo chown -R 1000:1000 config workspace secrets

The container runs as the node user (user id 1000). That is why the folders are handed to it.

Windows (PowerShell)#

$Root = Join-Path $HOME "docker_volumes\openclaw"
"config","workspace","secrets","ollama","backups" | ForEach-Object {
  New-Item -ItemType Directory -Force -Path (Join-Path $Root $_) | Out-Null }
Set-Location $Root
$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Fill($b)
$token = -join ($b | ForEach-Object { $_.ToString("x2") })
@("DATA_ROOT=$($Root.Replace('\','/'))", "OPENCLAW_GATEWAY_TOKEN=$token") | Set-Content -Encoding ascii .env

Mac (Terminal)#

Same commands as Linux, but skip the sudo chown line. In Docker Desktop, make sure your home folder is allowed under file sharing.

Check it worked#

ls -la ~/docker_volumes/openclaw

You should see config, workspace, secrets, ollama, backups and a .env file. On Windows run dir $Root.

Step 2: Write the Compose file#

We wrote this from the official docker-compose.yml, trimmed and tightened: the port is published on 127.0.0.1 only, and Ollama is a second service with no published port. Save it as docker-compose.yml in the same folder.

services:
  ollama:
    image: ollama/ollama:0.40.11
    restart: unless-stopped
    volumes:
      - "${DATA_ROOT}/ollama:/root/.ollama"

  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:2026.10.7
    restart: unless-stopped
    init: true
    environment:
      HOME: /home/node
      OPENCLAW_HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_STATE_DIR: /home/node/.openclaw
      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json
      OPENCLAW_CONFIG_DIR: /home/node/.openclaw
      OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace
      OPENCLAW_GATEWAY_PORT: "18789"
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:?set OPENCLAW_GATEWAY_TOKEN in .env}
    volumes:
      - "${DATA_ROOT}/config:/home/node/.openclaw"
      - "${DATA_ROOT}/workspace:/home/node/.openclaw/workspace"
      - "${DATA_ROOT}/secrets:/home/node/.config/openclaw"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    ports:
      - "127.0.0.1:18789:18789"
    command: ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"]
    healthcheck:
      test: ["CMD", "node", "dist/docker-healthcheck.js"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s
    depends_on:
      - ollama

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:2026.10.7
    network_mode: "service:openclaw-gateway"
    init: true
    stdin_open: true
    tty: true
    entrypoint: ["node", "dist/index.js"]
    environment:
      HOME: /home/node
      OPENCLAW_HOME: /home/node
      OPENCLAW_STATE_DIR: /home/node/.openclaw
      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json
      OPENCLAW_CONFIG_DIR: /home/node/.openclaw
      OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace
      OPENCLAW_GATEWAY_PORT: "18789"
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - "${DATA_ROOT}/config:/home/node/.openclaw"
      - "${DATA_ROOT}/workspace:/home/node/.openclaw/workspace"
      - "${DATA_ROOT}/secrets:/home/node/.config/openclaw"
      - "${DATA_ROOT}/backups:/backups"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    depends_on:
      - openclaw-gateway

Why --bind lan? Inside the container the Gateway must listen on the container network so Docker can forward to it. Your computer still only sees it on 127.0.0.1, because of the ports: line. The official file publishes on all interfaces by default - we do not.

There is no version: line on purpose: it is obsolete in Compose v2.

Linux#

docker compose config --quiet && echo OK

Windows (PowerShell)#

docker compose config --quiet; if ($?) { "OK" }

Mac (Terminal)#

Same commands as Linux.

Check it worked#

You should see OK and no error. Never paste the output of plain docker compose config anywhere: it prints your token.

Step 3: Start Ollama and pull a model#

OpenClaw needs a model that supports tool calling and has at least 16K context. The official docs suggest gemma4, and also mention gpt-oss:20b and qwen3.5:27b. Pick one that fits your memory. Model sizes and speed are your call. On 2026-10-26 the Ollama library listed gemma4:latest at 6.6 GB to 9.5 GB with a 128K context window, so check the size on the library page before you download.

Linux#

docker compose up -d ollama
docker compose exec ollama ollama pull gemma4
docker compose exec ollama ollama list

Windows (PowerShell)#

docker compose up -d ollama
docker compose exec ollama ollama pull gemma4
docker compose exec ollama ollama list

Mac (Terminal)#

Same commands as Linux. Docker on a Mac cannot use the Apple GPU, so a container model runs on CPU. For speed, run Ollama natively on the Mac instead and point OpenClaw at http://host.docker.internal:11434. We did not confirm this address in the official docs, and whether native Ollama listens where Docker can reach it depends on your setup: test it before you rely on it.

Check it worked#

ollama list shows your model. This is the one place we never expose a port, so there is nothing to test from the outside.

Potential issue: a model that loads can still fail an agent turn, because OpenClaw sends a long prompt plus tool schemas. Test a real task before you trust a small model.

Step 4: Onboard and set safe defaults#

Onboarding writes the config, connects Ollama, and wires the token. These commands follow the official Docker flow, with the Ollama options from the Ollama setup page. Run them from the openclaw folder.

Linux#

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --non-interactive --accept-risk --skip-health \
  --mode local --no-install-daemon --skip-channels \
  --auth-choice ollama \
  --custom-base-url "http://ollama:11434" \
  --custom-model-id "gemma4" \
  --gateway-auth token --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

Now set the hardened baseline from the official security page. Each entry is a config path and its value:

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[
    {"path":"gateway.mode","value":"local"},
    {"path":"gateway.bind","value":"lan"},
    {"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]},
    {"path":"session.dmScope","value":"per-channel-peer"},
    {"path":"tools.profile","value":"messaging"},
    {"path":"tools.fs.workspaceOnly","value":true},
    {"path":"tools.exec.security","value":"deny"},
    {"path":"tools.exec.ask","value":"always"},
    {"path":"tools.elevated.enabled","value":false}
  ]'

Windows (PowerShell)#

Use PowerShell 7. Older Windows PowerShell mangles the quotes in the JSON.

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway `
  dist/index.js onboard --non-interactive --accept-risk --skip-health `
  --mode local --no-install-daemon --skip-channels `
  --auth-choice ollama `
  --custom-base-url "http://ollama:11434" `
  --custom-model-id "gemma4" `
  --gateway-auth token --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

$cfg = '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]},{"path":"session.dmScope","value":"per-channel-peer"},{"path":"tools.profile","value":"messaging"},{"path":"tools.fs.workspaceOnly","value":true},{"path":"tools.exec.security","value":"deny"},{"path":"tools.exec.ask","value":"always"},{"path":"tools.elevated.enabled","value":false}]'
docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set --batch-json $cfg

Mac (Terminal)#

Same commands as Linux.

What the safe defaults mean:

These come from the official hardened baseline page. Setting tools.exec and tools.fs keys exactly as shown matches that page (read again on 2026-10-26), but we did not run them: confirm with docker compose run --rm openclaw-cli config get tools after the Gateway is up.

Check it worked#

The onboarding command prints a summary and exits without an error. The first time the config exists, it is in ~/docker_volumes/openclaw/config/openclaw.json. Do not paste that file anywhere.

Step 5: Start the Gateway and open the web page#

Linux#

docker compose up -d openclaw-gateway
docker compose ps
curl -fsS http://127.0.0.1:18789/healthz

Windows (PowerShell)#

docker compose up -d openclaw-gateway
docker compose ps
curl.exe -fsS http://127.0.0.1:18789/healthz

Mac (Terminal)#

Same commands as Linux.

Check it worked#

1. docker compose ps shows openclaw-gateway as running (healthy after about 20 seconds).
2. Open http://127.0.0.1:18789/ in your browser.
3. Paste the token from your .env file (OPENCLAW_GATEWAY_TOKEN) into Settings.
4. If the page says "pairing required", approve your browser (it is a one-time step per browser):

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

5. Send a message in the chat box, such as "Say hello and tell me which model you are using". A reply means the whole chain works: browser, Gateway, Ollama.

Run the built-in safety check right now:

docker compose run --rm openclaw-cli security audit

It lists risky settings. Fix the high findings before you go further.

What it can touch (the safety model)#

OpenClaw is built for one trusted person, not for strangers. The official docs say it is not a hostile multi-tenant boundary: anyone who can operate an agent can make it do anything that agent can do.

Two ideas keep you safe:

1. Least access. Give the agent the smallest tool list and one folder. Add power only when you need it.
2. Untrusted input. Every inbound message and web page can carry hidden instructions (prompt injection). Treat them as hostile. A smaller local model is easier to trick than a big hosted one.

Sandboxing#

By default, tools for the main session run directly in the Gateway. With the sandbox on, shell and file tools run in separate Docker containers. The official docs call it "not a perfect security boundary" that "materially limits" damage.

{ "agents": { "defaults": { "sandbox": { "mode": "non-main", "scope": "agent" } } } }

Be honest about the catch. A sandbox for a Docker-run Gateway means giving the Gateway container the Docker socket (/var/run/docker.sock). Whoever controls that container then controls Docker on your computer. The official Compose file keeps that line commented out for a reason. So choose one:

• Simple and safer: keep shell commands off (exec deny, as in Step 4). The agent can chat and use messaging tools, nothing more.
• Need commands: turn the sandbox on, accept the Docker socket risk, and run the whole stack on a machine or VM you can afford to rebuild.

Setup details are in the Docker sandbox docs.

Skills and ClawHub: the real risk#

Skills are folders with a SKILL.md and sometimes scripts. ClawHub is the public registry. Installing one is installing someone else's code and instructions into an agent that can act for you.

• The OpenClaw security policy says a malicious plugin after you install and enable it is not treated as a vulnerability. That is your decision, so it is your risk.
• ClawHub shows scan results (VirusTotal, ClawScan and static analysis) on each skill page. openclaw skills verify @owner/<slug> checks the trust information. Scanners miss things. A pass is not a promise.
• Prefer a skill you have read. Open SKILL.md and any script before you install.
• Install into one workspace, not --global, until you trust it.

docker compose run --rm openclaw-cli skills install @owner/<slug>
docker compose run --rm openclaw-cli skills verify @owner/<slug>

Published security advisories#

The project publishes many advisories. We counted them on 2026-10-26 from GitHub's advisory list for openclaw/openclaw: about 720 published since January 2026, including 14 critical and roughly 250 high. Most are fixed in the same fast release train.

What to do with that:

• Read the advisory list before you pick a version.
• Stay current. Update when security fixes land (see Updates).

Channels (optional)#

A channel lets you talk to the agent from a chat app. Start with the web page only. Add one channel later, on a separate account or number from your personal one, as the official docs suggest.

docker compose run --rm openclaw-cli channels add --channel telegram --token "<YOUR_BOT_TOKEN>"

Unknown senders get a pairing code. Approve one only for people you know:

docker compose run --rm openclaw-cli pairing approve telegram <code>

Keep requireMention: true in groups so the agent answers only when called.

Put it behind HTTPS (with or without Traefik)#

With Traefik#

This section is for a server with a domain and a Traefik container already running. If you use OpenClaw only on your own computer, skip it. Putting an agent on the public internet is risky. Prefer a private network (a VPN such as Tailscale) and add login in front.

In the Compose file, drop the ports: block on the Gateway, join the external proxy network, and add labels:

  openclaw-gateway:
    networks:
      - default
      - proxy
    labels:
      - traefik.enable=true
      - traefik.docker.network=proxy
      - traefik.http.routers.openclaw.rule=Host(`<your-domain>`)
      - traefik.http.routers.openclaw.entrypoints=https
      - traefik.http.routers.openclaw.tls=true
      - traefik.http.services.openclaw.loadbalancer.server.port=18789

networks:
  proxy:
    external: true

Create the network once if it is missing:

docker network create proxy

Then tell OpenClaw about the proxy and your public address (official network exposure page). Use the proxy's real address on the proxy network, and make sure Traefik overwrites X-Forwarded-For:

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway dist/index.js config set --batch-json '[
  {"path":"gateway.trustedProxies","value":["<traefik-container-ip>"]},
  {"path":"gateway.controlUi.allowedOrigins","value":["https://<your-domain>"]}
]'

Without these two, you may see 403 proxy_attribution_required or an origin error. Read the official exposure runbook first.

Without Traefik: Caddy#

Choose Caddy when you have no Traefik yet and run one small server. Facts are from caddyserver.com/docs.

Public domain, Caddyfile for OpenClaw:

app.example.com {
    reverse_proxy localhost:18789
}

Home only:

app.home.arpa {
    tls internal
    reverse_proxy localhost:18789
}

Trust the root certificate (home only): on the Caddy machine run sudo caddy trust (Linux). On Windows and Mac copy pki/authorities/local/root.crt from Caddy's data folder and import it as a trusted root (Windows certificate manager, Mac Keychain Access).

Run Caddy (2.11.7 was current on 2026-10-26): Linux with the official apt repository from the install page, then sudo systemctl reload caddy; Windows winget install CaddyServer.Caddy then caddy run; Mac brew install caddy then caddy run. Or use Docker: put caddy:2.11.7 on the same network as the app, drop the app's ports: line and write reverse_proxy openclaw-gateway:18789.

services:
  caddy:
    image: caddy:2.11.7
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ~/docker_volumes/caddy/data:/data
      - ~/docker_volumes/caddy/config:/config

WebSockets work without extra settings. As in the Traefik case, set gateway.trustedProxies to the address Caddy connects from and gateway.controlUi.allowedOrigins to your https:// address (see above).

Check it worked: curl -I https://app.example.com answers HTTP/2 200 (or the login redirect). On Windows use curl.exe.

Security and testing#

Checklist:

• [ ] .env is private: chmod 600 .env (Linux, Mac)
• [ ] Port 18789 is published on 127.0.0.1 only (docker compose ps shows 127.0.0.1:18789->18789)
• [ ] Ollama has no ports: line
• [ ] openclaw security audit shows no high findings
• [ ] Shell tools are off, or sandboxed
• [ ] No third-party skill you have not read

Tests:

docker compose ps
curl -fsS http://127.0.0.1:18789/readyz
docker compose run --rm openclaw-cli security audit

Behind Traefik, also check HTTPS:

curl -I https://<your-domain>

On a Linux server, Docker publishes ports around your firewall rules. If you ever publish beyond loopback, add the DOCKER-USER rules from the official UFW notes.

Secrets live in three places: .env, config/openclaw.json, and secrets/. Treat all three like passwords. Transcripts in the workspace can hold sensitive text too.

Troubleshooting#

Do not use the /v1 URL#

The official Ollama page warns: do not use http://host:11434/v1. It breaks tool calling and models can emit raw tool-call JSON as text. Use http://ollama:11434.

Known bugs#

• Updating from older versions: #182967 (invalid-config update failure) and #183599 (gateway hangs on startup after 2026.9.6 to 2026.10.7). Fresh installs are not named in these reports. Back up before every update: #183599 says a downgrade can be blocked once the agent databases have moved to the newer schema, so a backup taken before the update is your real way back.
• WSL2 with NVIDIA: the official Ollama Linux installer can cause a reboot loop. It does not apply to our containerised Ollama; if you run Ollama inside WSL2, see the official fix.

Diagnostic commands:

docker compose logs --tail 100 openclaw-gateway
docker compose ps
docker compose run --rm openclaw-cli doctor

Updates and backups#

Backup first, every time. The official CLI makes a verified archive of state, config and workspace.

Linux#

docker compose run --rm openclaw-cli backup create --output /backups --verify
tar -czf "backups/openclaw-folders-$(date +%F).tar.gz" config workspace secrets .env

Windows (PowerShell)#

docker compose run --rm openclaw-cli backup create --output /backups --verify
Compress-Archive -Path config,workspace,secrets,.env -DestinationPath "backups\openclaw-folders-$(Get-Date -Format yyyy-MM-dd).zip"

Mac (Terminal)#

Same commands as Linux.

The CLI archive lands in backups/ on your computer. The folder archive is the simple safety net that does not depend on the CLI. Stop the stack first (docker compose down) for a clean copy.

Schedule it. Linux and Mac cron at 03:00 (the folder archive only):

0 3 * * * cd "$HOME/docker_volumes/openclaw" && tar -czf "backups/openclaw-folders-$(date +\%F).tar.gz" config workspace secrets .env

On Windows, create a Task Scheduler job that runs the Compress-Archive line daily at 03:00.

Restore test (do it once, with a throwaway copy):

1. Extract the archive into a new empty folder, for example restore-test.
2. Copy docker-compose.yml there and set DATA_ROOT in .env to that folder.
3. Start it with another host port (change 18789 to 18790 in ports:), then run docker compose ps and open the page. Your history and settings should be there.
4. Delete the test folder and stop the test stack.

Update.

1. Back up, as above.
2. Read the release notes for the new version.
3. Change both image tags in docker-compose.yml (for example 2026.10.7 to the next release).
4. Run:

docker compose pull
docker compose up -d
docker compose run --rm openclaw-cli doctor

If an update fails, restore your backup and go back to the old tag, or to 2026.9.34. Official docs also describe update channels (stable, extended-stable, beta) if you use the native install: openclaw update --channel extended-stable.

Performance and resources#

• The model is the cost. OpenClaw itself is light. Memory, speed and quality depend on the Ollama model, its size and its context window. We did not measure these.
• Context matters. The agent sends a long prompt with tool definitions. The docs require at least 16K context for automatic discovery. Bigger context needs more memory and is slower.
• Cold start. The first answer loads the model and can time out. Keep the model loaded for daily use.

Monitor it:

docker stats --no-stream
docker compose logs -f openclaw-gateway

FAQ#

Is it safe to give OpenClaw my files and messages? Only as safe as the access you give it. Start with the web page, the messaging tool profile, shell off, and one workspace folder. Add one thing at a time and run openclaw security audit after each change.

Can I put it on the internet so I can chat from my phone? It is possible, but not wise. Use a private VPN, or a paired chat app on a separate account. If you must publish it, read the official exposure runbook first and keep the token strong.

Are ClawHub skills safe? Not automatically. They are third-party code. Read SKILL.md, check the scan results, and install only what you trust, into one workspace.

Why is my local model so slow or dumb with tools? Agents need strong tool-calling and a long context. Small models struggle. Try a larger model that fits your memory, or a model with native tool support.

Can I use a cloud model instead? Yes: OpenClaw supports hosted providers and Ollama Cloud. Your prompts then go to that provider, so the "stays on my machine" promise no longer holds.

Sources#

All read on 2026-10-26.

• openclaw/openclaw README, SECURITY.md and docker-compose.yml
• Release v2026.10.7 (2026-10-24) and v2026.9.34 extended-stable
• Security advisories
• Docker install and Docker sandbox and troubleshooting
• Ollama provider and Ollama setup
• Security, hardened baseline, network exposure
• Sandboxing, Skills and ClawHub
• Backups, Release channels, Local models
• Issues checked for 2026.10.7: #182967, #183599, #183036
• Caddy docs: automatic HTTPS, tls internal, reverse_proxy, install (read on 2026-10-26)

Checked against the official docs on 2026-10-26. Not run by DIY Lab Hub: no test installation was made for this guide.