OpenClaw Docker Fails Silently? Fix the Port Trap First

Why does my OpenClaw Docker container start, show as running in docker ps, then crash 20 seconds later with zero useful logs?

I spent two hours on this. Reinstalled Docker. Tried three different API keys. Nuked volumes. The container would spin up, pass the healthcheck once, then silently die.

Turns out something else on my machine was already using port 18789.

The Port 18789 Trap

18789 is OpenClaw’s default gateway port (per the official docker-compose.yml). Something else has it? Docker starts the container anyway – but the healthcheck quietly fails and the container restarts in a loop. docker logs openclaw-gateway shows nothing obvious. No “port in use” error. Just a vague connection timeout.

Check first:

# macOS/Linux
lsof -i :18789

# Windows
netstat -ano | findstr :18789

If something’s there, kill it or change OpenClaw’s port in docker-compose.yml:

ports:
 - "18790:18789" # Host 18790 → container 18789

Restart. It’ll work.

What Every Tutorial Assumes You Already Know

Two containers. openclaw-gateway is the main process – talks to your LLM, handles messages, runs tools. openclaw-cli is a management shell.

Here’s the part nobody explains: the CLI shares the gateway’s network namespace (official docs state this clearly). Can’t start until the gateway is already running.

Try to run setup commands through openclaw-cli before the gateway exists? “Connection refused.”

The fix: run pre-start commands directly through openclaw-gateway with --no-deps --entrypoint node.

docker compose run --rm --no-deps --entrypoint node openclaw-gateway 
 dist/index.js onboard --mode local --no-install-daemon

After the gateway is up, then you can use openclaw-cli for everything else.

The Actual Setup (What Worked for Me)

Docker installed? At least 2GB of RAM available? OpenClaw’s build process will OOM-kill itself on 1GB hosts (the official Docker installation docs call this out – exit code 137 during pnpm install).

Clone the repo:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Run the setup script:

./scripts/docker/setup.sh

Which model provider? (Anthropic, OpenAI, Google, etc.) Your API key? It’ll generate a gateway token, start the containers. Creates two directories on your host: ~/.openclaw (config, memory, API keys) and ~/openclaw/workspace (files the agent can read/write) – this two-volume setup is documented in Simon Willison’s TIL.

Check the gateway is actually running:

docker compose ps

openclaw-gateway should say “Up” and healthy. “Restarting”? Check port conflicts first (see above).

Access the Control UI at http://localhost:18789. Need the token? It’s in .env if you lost it.

WSL2 Users: Don’t Install in /mnt/c

Windows with WSL2? Skip /mnt/c (your Windows filesystem). npm installs there hit constant permission errors – even with chmod fixes. Multiple troubleshooting sources cite “EACCES in WSL2 /mnt/c directory” as a common trap.

Work in your WSL home directory instead:

cd ~
mkdir projects
cd projects
git clone https://github.com/openclaw/openclaw.git

Everything installs faster. You skip the permission nightmare entirely.

Deploying on a VPS? Don’t want to expose port 18789 to the internet? Set OPENCLAW_GATEWAY_BIND=loopback in your .env file. Gateway will only listen on 127.0.0.1. Forces you to access it via SSH tunnel – but way safer than opening it publicly. Especially after CVE-2026-25253 (more on that below).

Connecting Telegram (The Least Annoying Channel)

OpenClaw supports 50+ messaging platforms as of early 2026 (per DigitalOcean’s overview). Telegram? Fastest to set up. No QR codes, no phone pairing.

Open Telegram, message @BotFather, send /newbot. Follow the prompts. You’ll get a token that looks like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw.

Add it to OpenClaw:

docker compose run --rm openclaw-cli channels add 
 --channel telegram --token "YOUR_TOKEN_HERE"

OpenClaw will send you a pairing code via Telegram. Approve it:

docker compose run --rm openclaw-cli pairing approve telegram CODE

Now you can message your bot from your phone and it’ll route to the agent.

When Things Break

Container won’t start? RAM. The build needs 2GB. Cheap VPS with 1GB? pnpm install dies with exit 137.

Dashboard says “authentication required” even with the token? Token’s stale. Regenerate:

docker compose run --rm openclaw-cli dashboard --no-open

Prints a fresh URL with the token embedded. Copy the whole thing.

Agent responds in the dashboard but ignores Telegram messages? You didn’t approve the pairing code. Run openclaw-cli pairing list --channel telegram to see pending requests.

The Security Thing Nobody Talks About

CVE-2026-25253. CVSS 9.8. Critical RCE vulnerability in OpenClaw’s daemon mode, discovered early 2026. Daemon was listening on 0.0.0.0 with no auth by default – anyone on your network (or the internet, if you port-forwarded) could send commands to your instance and execute arbitrary code.

40,000 instances were exposed when researchers found it.

The Docker setup avoids this – binds to lan mode with a gateway token. But if you’re tweaking configs? Don’t set gateway.bind to 0.0.0.0 unless you really know what you’re doing. Use loopback and SSH tunnels instead.

Updates Are Non-Destructive

OpenClaw releases frequently (as of March 2026, the project is still in rapid development – Peter Steinberger, the creator, joined OpenAI in February 2026 per Wikipedia, and OpenClaw transitioned to a non-profit foundation).

Updating is safe. Config and workspace live in mounted volumes, not inside the container:

docker compose pull
docker compose up -d
docker image prune -f

Your settings, memory files, workspace data? Persist. The container itself is disposable.

What You Should Do Next

Container running? Message your agent from the Control UI or Telegram. Ask it to create a test file in the workspace. Check ~/openclaw/workspace on your host – the file should be there.

That confirms the volume mount is working and the agent has write access. From there? Explore channels (Discord, Slack, WhatsApp all work similarly to Telegram), add skills, or set up cron jobs.

Docker isolates the chaos. The agent can’t touch your host filesystem outside the workspace. That’s the whole point.

FAQ

Can I use a pre-built image instead of building locally?

Yes. Set OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" before running the setup script. Official images are at the GitHub Container Registry. Building locally takes longer but lets you customize the Dockerfile if you need specific dependencies baked in.

Why does openclaw-cli fail with “Cannot connect to gateway” even though the gateway is running?

CLI shares the gateway’s network namespace. Can only run after the gateway is already up.

Running setup commands before docker compose up? Use docker compose run --rm --no-deps --entrypoint node openclaw-gateway dist/index.js <command> instead. Once the gateway is running, openclaw-cli works normally.

Do I need to expose port 18789 to the internet to use Telegram or WhatsApp?

No. Telegram, WhatsApp (via Baileys), Discord – most channels use outbound connections from OpenClaw to the service’s servers. You only need inbound webhooks for a few channels like Slack or Google Chat.

Just using Telegram? Keep the gateway on loopback and access the dashboard via SSH tunnel. Much safer than opening 18789 publicly, especially given the CVE-2026-25253 history. The daemon mode vulnerability affected ~40,000 instances because they were exposed to the internet with no auth.