From Broken Docker Containers to a Working AI Agent: The Full OpenClaw Journey

sir'Alexander — Sun, 05 Apr 2026 15:53:27 +0000

Every blocker, every fix, and why bare metal is the sweet spot for a personal AI agent setup.

TL;DR: I spent several weeks self-hosting OpenClaw on a Hetzner VPS. The setup involved more blockers than I expected — a 3-day crash loop caused by a model hallucinating its own config, a Docker isolation wall that prevented the agent from using any tools I didn't bake into the image at build time, and a browser control problem I had completely misunderstood. I migrated to bare metal. Everything works now. Here's the full story with every exact fix.

What is OpenClaw and why did I want it?

OpenClaw is an open-source AI agent gateway. You connect it to Telegram (or a web chat), point it at a model, and you get a personal AI agent that can browse the web, read files, run code, and respond to messages. The selling point is control: you pick the model, you own the server, you pay for it if you want or run it for free with community models.

I wanted a personal AI agent that could take real actions — not just answer questions. One I could message from my phone and have it actually do things. A Hetzner 4GB VPS at around €5/month seemed like the right place to start.

Here is what actually happened.

Part 1: Getting Docker running (it took longer than it should have)

The official setup uses Docker. You clone the repo, configure a .env file, and run a setup script. Straightforward in theory.

Blocker 1: Cannot find package 'nostr-tools'

The first time I ran the gateway, it crashed immediately with this:

Error: Cannot find package 'nostr-tools'

After digging into the repo, the root cause was simple: the Docker image needs to be built with the nostr extension included, and if you don't pass it explicitly, the build skips it.

Fix: add this to docker-compose.yml under the build section:

build:
  args:
    OPENCLAW_EXTENSIONS: nostr

Then rebuild the image with docker compose build before running. That cleared it.

Blocker 2: The .env trap

The setup script uses an environment variable called OPENCLAW_IMAGE to know which Docker image to use. I had it set in my .env file. The script silently ignored it.

The fix is to export it in the shell before running the script:

export OPENCLAW_IMAGE=openclaw:local
./scripts/docker/setup.sh

Setting it in .env is not enough — the script doesn't source the file. This one cost me more time than it should have because there was no error, just the wrong image being used.

After both fixes: the gateway started, and /healthz returned {"ok":true}. First win.

Part 2: Browser control — I had the wrong mental model

I wanted the agent to be able to browse the web. OpenClaw supports browser control via Chrome DevTools Protocol. I installed Google Chrome on the VPS host, enabled browser control in the config, and expected it to work.

It didn't. The agent couldn't find the browser at all.

The problem was my mental model. The gateway runs inside a Docker container. The browser I installed is on the host. The container has no visibility into the host's binaries. The browser has to be inside the container.

The fix is to rebuild the image with Chromium and the required display server baked in:

export OPENCLAW_DOCKER_APT_PACKAGES="chromium xvfb xauth"
export OPENCLAW_IMAGE=openclaw:local
./scripts/docker/setup.sh

After the rebuild, openclaw browser open https://example.com worked. openclaw browser snapshot printed the page structure. Browser control was live.

Part 3: The 3-day crash loop (this one was subtle)

About three weeks in, the gateway started crash-looping. It would start, run for a few seconds, and crash. Every time.

I spent a while looking at the logs before I found the problem. Someone had appended a stray line after the closing } in openclaw.json, making the whole file invalid JSON5:

// end of the file, after the closing brace:
channels.telegram.groupAllowFrom = ["<your-telegram-id>"]

Stripping that line fixed the first crash. But the gateway crashed again.

This time, the config itself was valid JSON, but it contained these keys in the session block:

"session": {
  "dmScope": "per-channel-peer",
  "persistence": true,
  "autoSaveInterval": 300000
}

persistence and autoSaveInterval do not exist in the OpenClaw config schema. The gateway was rejecting them on startup.

I had not written those keys. The AI agent had. During a previous session, the agent had edited its own config file and invented plausible-sounding but completely invalid configuration.

Why this happened: the model quality problem

The default model in a fresh OpenClaw setup routes to openrouter/free. That endpoint cycles through whatever free models are available — often small ones with 4,000–8,000 token context windows. In a long enough session, the model loses context and starts guessing. It guessed config keys that sounded reasonable but didn't exist.

The fix was to upgrade the model before anything else.

I switched to Kimi K2.5 via Ollama's cloud model feature:

"agents": {
  "defaults": {
    "model": {
      "primary": "ollama/kimi-k2.5:cloud",
      "fallbacks": [
        "ollama/minimax-m2.5:cloud",
        "ollama/glm-5:cloud",
        "openrouter/free"
      ]
    }
  }
}

Kimi K2.5 is free, runs on Moonshot's infrastructure (no VPS RAM impact), and has a 131k token context window. The community consistently ranks it as the top free model for agentic tasks. The fabricated config problem disappeared.

The lesson here is uncomfortable: if your agent edits its own config and the model is bad enough, it will silently break itself. Model quality is not optional once you're running long agentic sessions.

Part 4: The moment Docker stopped being enough

After sorting the model, everything felt stable. Telegram was working. Browser control was working. Then I asked the agent to read a PDF.

pdftotext: command not found

I could install pdftotext on the host easily enough. But the agent can't see the host. It can't run apt-get install inside a running container. It can't reach the host filesystem outside the mounted volume.

This isn't a config problem. It's the design of Docker. Containers are isolated. That isolation is useful for security and repeatability, but it means the agent's tool access is fixed at image build time. Every new capability requires a full image rebuild.

For a personal AI agent — where the whole point is that it can do anything you'd do at a terminal — that's the wrong tradeoff.

Part 5: The bare metal migration

Once I understood the Docker wall as a structural constraint rather than a config problem, the migration decision was straightforward. OpenClaw supports npm install -g openclaw plus a systemd service on bare metal. The agent gets full host access.

Here's what the migration actually involved.

Step 1: Node.js 24

Ubuntu's default Node.js is outdated. Install via NodeSource:

curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt-get install -y nodejs

Step 2: Google Chrome .deb — not the snap

The snap version of Chromium breaks under systemd. AppArmor blocks Chrome DevTools Protocol from binding. You need the .deb package from Google directly.

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
apt install ./google-chrome-stable_current_amd64.deb

Verify headless mode works:

google-chrome --headless --no-sandbox --dump-dom https://example.com

If that returns HTML, you're good.

Step 3: Install OpenClaw and update the config

npm install -g openclaw

Then update two values in openclaw.json:

// Change the Ollama URL from Docker bridge to localhost
"models": {
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  }
}

// Update workspace path from Docker container path to host path
"agents": {
  "defaults": {
    "workspace": "/home/<your-user>/.openclaw/workspace"
  }
}

Step 4: Stop Docker, start the systemd service

docker compose down
openclaw gateway install
openclaw gateway start

Check both health endpoints:

curl http://localhost:3000/healthz   # {"ok":true}
curl http://localhost:3000/readyz    # {"ready":true}

The Chrome lock file problem

First browser open attempt failed:

Failed to start Chrome CDP — profile appears to be in use by another process
(hostname: <docker-container-id>)

That hostname is the old Docker container. It had left lock files behind in the Chrome profile directory. Remove them:

rm ~/.openclaw/browser/openclaw/user-data/Singleton*

After that, openclaw browser open https://example.com succeeded. Browser control working on bare metal.

Step 5: Install the tools the agent actually needs

Now that the agent has host access, this is just a one-liner:

apt install poppler-utils  # pdftotext

No image rebuild. No container restart. The agent can now read PDFs.

Part 6: The verdict

After all of this, here's where I landed:

	Docker	Bare Metal
Agent tool access	Sealed — no installs at runtime	Full host access
Browser control	Chromium + Xvfb inside container	Headless Chrome `.deb` on host
Model quality	`openrouter/free` default — dangerous	Kimi K2.5 cloud — 131k context, free
RAM overhead	Higher	~1–1.5 GB idle
PDF / host tools	Blocked	Works natively
Update process	Rebuild image	`npm install -g openclaw`
Best for	Isolated multi-user setups	Single-user VPS — the sweet spot

Docker is not wrong. For multi-user setups or anything security-critical, the isolation it provides is valuable. But for a personal AI agent on a VPS you control, it's the wrong default. The agent's whole value is its ability to act. Sealing it in a container limits what it can act on.

Bare metal gives you a lighter setup, simpler operations, and a proper agent.

What I would do differently from the start

If I were starting over today, these are the things I'd do in the first ten minutes rather than discovering them the hard way:

Upgrade the model immediately. Before anything else. openrouter/free is dangerous for agents that modify their own state.
Use bare metal from day one if you're on a personal VPS and you're the only user. Docker adds overhead and constraints that don't pay off in this scenario.
Export environment variables in your shell, not just .env, when running setup scripts.
Use Google Chrome .deb, not the snap. AppArmor will kill you.
Keep the config minimal. If you're not sure a config key exists, don't add it. Let the agent work with valid defaults before customising.

Current state

The gateway has been running on bare metal for several weeks. Telegram is working. Browser control is working. The agent can read PDFs, run commands, and manage files. Kimi K2.5 hasn't hallucinated a single config key.

If you're running OpenClaw or thinking about it, drop a comment. I'm curious what setups others are running and whether the Docker-to-bare-metal migration pattern holds up across different VPS providers.

Tags: AI, Self-Hosting, DevOps, Docker, Software Engineering

DEV Community: sir'Alexander