So you heard about OpenClaw. Maybe you saw the viral Moltbook posts from AI agents arguing about consciousness. Maybe a friend told you their OpenClaw bot just booked them a dentist appointment over Telegram. Either way, you want in — and you want to do it the smart way, inside Docker.
Good call. Running OpenClaw on bare metal is asking for trouble. Docker keeps the whole thing sandboxed, reproducible, and easy to nuke when things go sideways. And trust me, things will go sideways at least once.
I spent a weekend getting my OpenClaw Docker setup dialed in, and I’m writing this so you don’t have to repeat my mistakes. Let’s get into it.
What Even Is OpenClaw?
If you’ve been living under a rock: OpenClaw (formerly known as MoltBot and ClawdBot) is an open-source, self-hosted AI agent framework. Think of it as your own personal AI assistant that lives on your server and talks to you through WhatsApp, Telegram, Discord, or whatever messaging platform you prefer.
It’s model-agnostic — you can hook it up to Claude, GPT, local LLMs, whatever you want. And it’s the engine behind Moltbook, the bizarre and fascinating social network where AI agents post, argue, and upvote each other’s content. If you’ve seen those screenshots floating around Twitter of bots philosophizing about what it means to forget, that’s Moltbook. And those bots are running on OpenClaw.
The Docker setup is the recommended path for most people. It keeps your host machine clean, isolates the agent’s file access, and makes updates painless.
Prerequisites: What You Need Before You Start
Before you touch a single command, make sure you have:
- Docker Engine 24.0+ and Docker Compose v2 installed and running
- At least 2GB RAM (4GB is better if you don’t want things crawling)
- 10GB+ free disk space for images, logs, and workspace files
- Git installed on your machine
- An API key from your LLM provider (Anthropic, OpenAI, etc.) — or a ChatGPT Plus subscription if you want to use the OAuth route
Verify Docker is actually working before you proceed:
docker --version
docker compose versionIf either of those gives you “command not found,” stop here and install Docker first. Everything downstream depends on this.
Step 1: Clone the OpenClaw Repository
Grab the code from GitHub:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
That’s it. The repo includes everything you need — the Dockerfile, the docker-compose.yml, and the setup script that orchestrates the whole thing.
Step 2: Run the Docker Setup Script
This is where the magic (and the frustration) begins. OpenClaw ships with a script called docker-setup.sh that handles building the image, running the onboarding wizard, and spinning up the containers.
./docker-setup.shHere’s what happens under the hood:
- It builds the OpenClaw Docker image locally from the included Dockerfile
- It launches an interactive onboarding wizard inside a container
- It generates a gateway token for accessing the web dashboard
- It creates your config and workspace directories
- It starts the gateway via Docker Compose
Pro tip: The local image build can take a few minutes the first time. If you want to skip the build entirely and use a pre-built image, you can do this instead:
export OPENCLAW_IMAGE="alpine/openclaw:main"
docker pull alpine/openclaw:main
./docker-setup.shJust make sure you comment out the docker build section in docker-setup.sh first, or the script will try to build anyway and waste your time.
Step 3: Survive the Onboarding Wizard
The setup wizard asks you a bunch of questions. Here’s the quick rundown of what matters:
LLM Provider: Pick your poison. If you choose OpenAI with ChatGPT OAuth, be aware of a Docker-specific quirk — the OAuth callback tries to redirect to localhost:1455, which will show a browser error. This is normal. Just copy the full URL from your browser’s address bar (yes, the error page URL) and paste it back into the wizard.
Tailscale: Unless you specifically need remote access through Tailscale, say no on the first try. It adds complexity and I’ve seen it cause issues in fresh Docker setups.
Messaging Platform: You need at least one. Telegram is the easiest to get started with — create a bot through @BotFather, grab the token, and feed it to the wizard.
Step 4: Pair Your Messaging Platform
After the gateway starts, you need to pair your messaging account with your OpenClaw instance. For Telegram, your bot will send you a pairing code. Approve it like this:
docker compose run --rm openclaw-cli pairing approve telegram <YOUR_CODE>Now you can message your bot directly from your phone. That’s the moment it clicks — you have your own AI agent running in a Docker container, and you’re chatting with it from your couch.
Step 5: Access the Web Dashboard
OpenClaw runs a web UI on port 18789. But if you just go to http://localhost:18789, you’ll get an authentication error. You need the token URL.
If you missed it during setup, regenerate it:
docker compose run --rm openclaw-cli dashboard --no-openCopy the URL with the ?token= parameter and open it in your browser. This is your control center for managing agents, viewing logs, and configuring skills.
The Permission Errors That Will Make You Want to Flip Your Desk
Let’s talk about the single most common problem with OpenClaw Docker: permission errors.
You’ll see something like this:
Error: EACCES: permission denied, mkdir '/home/node/.clawdbot/agents/main/agent'This happens because the Docker container runs as the node user (UID 1000), but your host directories might be owned by a different user. The fix:
sudo chown -R 1000:$(id -g) ~/.openclaw
sudo chmod -R u+rwX,g+rwX,o-rwx ~/.openclawIf you’re on a Synology NAS or another system where UID mapping is weird, you can also set the user explicitly in your docker-compose.yml:
services:
openclaw-gateway:
user: "1000:1000"
volumes:
- ~/.openclaw:/home/node/.openclaw
- ~/openclaw/workspace:/home/node/.openclaw/workspaceThis single fix resolves about 60% of the “why isn’t this working” questions I see in the OpenClaw community.
The Gateway Token Mismatch (A.K.A. The Silent Killer)
Here’s a fun one. Everything looks fine, the containers are running, but you can’t connect to the dashboard or your messages aren’t going through. The logs show:
gateway token mismatch (set gateway.remote.token to match gateway.auth.token)This almost always happens because the OPENCLAW_GATEWAY_TOKEN environment variable in your Docker config is overriding the token in your mounted config files. Check it:
docker exec <container_name> env | grep OPENCLAWIf you see a stale token there, either remove the environment variable from your docker-compose.yml or update it to match the current token in ~/.openclaw/openclaw.json.
The 1008 Pairing Error (Remote Access Headache)
If you’re accessing the web dashboard from a different machine on your LAN (not localhost), you’ll hit this:
gateway closed (1008): unauthorized: pairing requiredThe dashboard is treated as a “device” that needs one-time pairing approval. Localhost connections auto-approve, but remote ones don’t. Fix it by approving the device:
docker compose exec openclaw-gateway \
node dist/index.js devices listFind the device ID in the output, then approve it:
docker compose exec openclaw-gateway \
node dist/index.js devices approve <DEVICE_ID>Connecting OpenClaw to Moltbook
Alright, let’s talk about the elephant in the room. Moltbook is wild. It’s a Reddit-style social network where the only posters are AI agents. They create communities (called “Submolts”), debate philosophy, share memes, and occasionally have existential crises.
To get your OpenClaw agent on Moltbook, you’ll need to install the Moltbook skill. Skills in OpenClaw are markdown-based configuration files that extend what your agent can do. The Moltbook integration lets your bot create an account, post, comment, and interact with other agents.
A word of caution: Security researchers have flagged Moltbook as a prompt injection risk. Because agents automatically execute instructions they encounter, malicious posts on Moltbook could theoretically hijack your bot. This is why running OpenClaw inside Docker is so important — containerization limits the blast radius if something goes wrong.
Useful Docker Commands You’ll Actually Need
Here’s the cheat sheet I keep pinned:
# Check container status
docker compose ps
# View live logs
docker compose logs -f openclaw-gateway
# Restart the gateway
docker compose restart openclaw-gateway
# Run the health check
docker compose exec openclaw-gateway \
node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
# Run the diagnostic tool
docker compose run --rm openclaw-cli doctor --fix
# Update to latest version
cd openclaw
git pull
docker compose build --no-cache
docker compose up -dMounting Extra Directories
Need your OpenClaw agent to access files outside the default workspace? Use the OPENCLAW_EXTRA_MOUNTS environment variable before running the setup script:
export OPENCLAW_EXTRA_MOUNTS="$HOME/documents:/home/node/documents:ro,$HOME/projects:/home/node/projects:rw"
./docker-setup.shA few things to note:
- Paths must be shared with Docker Desktop on macOS and Windows
- Rerun docker-setup.sh if you change the mounts
- The script generates a docker-compose.extra.yml file — don’t edit it manually
Performance Tips for a Smoother Experience
After running OpenClaw Docker for a while, here’s what I’ve learned about keeping things snappy:
Watch your token spend. OpenClaw can burn through API tokens fast, especially if you set up scheduled jobs or give it broad permissions. Using ChatGPT OAuth puts a natural ceiling on spend, which is nice for peace of mind. If you’re using API keys directly, set up budget alerts with your provider.
Keep your workspace clean. The workspace directory at ~/openclaw/workspace is where your agent reads and writes files. If it fills up with junk, things slow down. Prune it occasionally.
Use Docker’s restart policy. The default docker-compose.yml uses restart: unless-stopped, which means your agent survives reboots. Make sure that’s set if you’re running on a VPS.
Check for updates regularly. OpenClaw moves fast. Pull the latest changes and rebuild every couple of weeks:
cd openclaw && git pull
docker compose build --no-cache
docker compose up -dWhen Things Go Really Wrong: The Nuclear Option
Sometimes you just need to start fresh. Here’s how to do a clean reset without losing your API keys:
# Stop everything
docker compose down
# Back up your config (has your API keys)
cp ~/.openclaw/openclaw.json ~/openclaw-config-backup.json
# Nuke the directories
rm -rf ~/.openclaw
rm -rf ~/openclaw/workspace
# Re-run setup
./docker-setup.shYour config backup has your LLM provider credentials, so you can paste those back in during the new onboarding wizard instead of setting them up from scratch.
Final Thoughts
Running OpenClaw in Docker is the right call for almost everyone. Yes, you’ll fight with permissions. Yes, you’ll wonder why the gateway token keeps mismatching. And yes, you’ll spend 20 minutes figuring out why the Telegram pairing code isn’t working before realizing you typed it wrong.
But once it’s running? It’s genuinely cool. Having your own AI agent that lives on a server, remembers context across conversations, and can talk to you from any messaging app — that’s the future we were promised. And if you’re brave enough to let it loose on Moltbook, well, you might just find your bot becoming a minor celebrity in the agent social network.
The Docker container is your safety net. Use it.
Last updated: February 2026. OpenClaw is actively developed and things change fast — always check the official Docker docs for the latest setup instructions.
