OpenClaw Installation Troubleshooting: Common Errors & Fixes

Installing OpenClaw can hit several non-obvious snags. This guide documents the most common errors — their symptoms, root causes, and exact fixes — based on real deployment experience.

1. Container OOM Killed (Exit Code 137)

Symptoms:

• Container exits with code 137
• Docker logs show nothing (killed before it could log)
• dmesg | grep -i kill shows "Out of memory: Killed process"

Cause: OpenClaw's gateway compiles a WebAssembly (WASM) sandbox on startup. This process peaks at approximately 1.3 GB of RAM. With less than 2 GB available, the Linux OOM killer terminates the container.

Fix:

# Set memory limit explicitly
docker run -m 2048m -e NODE_OPTIONS=--max-old-space-size=1536 ...

# Or in docker-compose.yml:
deploy:
  resources:
    limits:
      memory: 2048M

Check available host RAM first:

free -h

If the host has less than 2 GB free, stop other services or upgrade your server/VM.

2. WASM Compilation Timeout / Slow Start

Symptoms:

• Container runs for 5+ minutes with high CPU but no network response
• Port 18789 is not yet open
• Health checks failing

Cause: This is normal behavior. The gateway compiles its WebAssembly sandbox from scratch on first launch. This takes 3–7 minutes depending on CPU speed.

Fix: Wait. Do not restart the container during this phase. Check logs:

docker logs -f openclaw

You'll eventually see:

Gateway listening on 127.0.0.1:18789

For health checks, set start_period to at least 360 seconds:

healthcheck:
  start_period: 360s

3. Gateway Exits with Code 1 (Config Error)

Symptoms:

• Container starts and exits within seconds with code 1
• Logs may show "unrecognized configuration key" or be empty

Cause: OpenClaw is strict about configuration. Several keys look valid but are actually unrecognized and cause immediate exit:

| Unrecognized Key | Use Instead | |---|---| | selfPhoneMode | selfChatMode | | dms | dmPolicy | | groups | groupPolicy | | agents.defaults.systemPrompt | (remove entirely) | | agents.defaults.temperature | (remove entirely) | | gateway.bind | (not supported) | | gateway.auth | (not supported) | | channels.http | (channel does not exist) |

Fix:

Validate your JSON first:

cat /opt/openclaw/config/openclaw.json | python3 -m json.tool

Then remove any unrecognized keys. Minimal working config:

{
  "gateway": {
    "mode": "local"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TOKEN",
      "dmPolicy": "open"
    }
  }
}

4. gateway.mode Must Be "local"

Symptoms:

• Container exits with code 1
• Logs may show mode-related error

Cause: Only "local" is a valid value for gateway.mode. Other values ("cloud", "remote", omitting the field) cause exit=1.

Fix:

{
  "gateway": {
    "mode": "local"
  }
}

5. Port 18789 Not Opening

Symptoms:

• curl http://localhost:18789 returns "Connection refused"
• Container is running but unreachable

Cause: Most likely the gateway is still initializing (WASM compilation). Port 18789 only opens after initialization completes.

Fix: Check if the container is still starting:

docker logs --tail 20 openclaw

If you see active log output, wait for initialization to finish. If logs stopped and the container is idle, check for config errors (see issue #3).

Also note: OpenClaw binds to 127.0.0.1:18789, not 0.0.0.0. You cannot connect from outside without a proxy.

6. Docker Permission Denied

Symptoms:

• Got permission denied while trying to connect to Docker daemon socket

Cause: Your user is not in the docker group.

Fix:

sudo usermod -aG docker $USER
newgrp docker
# Or log out and back in

7. Invalid Telegram Bot Token

Symptoms:

• Gateway starts but Telegram bot doesn't respond
• Logs show "401 Unauthorized" or "invalid token"

Cause: The bot token in your config is wrong, or the token was revoked.

Fix:

1. Get a fresh token from @BotFather — send /token to your bot
2. Ensure the token is in the config JSON, not just as an environment variable. OpenClaw reads botToken from the JSON config file; the env var fallback is unreliable.

{
  "channels": {
    "telegram": {
      "botToken": "123456789:AABBccDDee-exact-token-here"
    }
  }
}

8. WhatsApp QR Code Expired

Symptoms:

• WhatsApp QR code appears but scanning fails with "expired" or nothing happens

Cause: WhatsApp QR codes expire after about 60 seconds. Slow network or delayed scanning causes expiry.

Fix:

1. Open the OpenClaw Control UI (http://your-server:8080)
2. Navigate to the WhatsApp pairing section
3. Click "Refresh QR" to generate a new code
4. Scan within 60 seconds
5. Ensure your phone has a stable internet connection

9. WhatsApp Pairing Mode Blocking Messages

Symptoms:

• WhatsApp is connected but no messages are received/sent
• Logs show "dmPolicy: pairing"

Cause: If dmPolicy is not set at both the channel level AND the account level, OpenClaw's doctor process auto-sets it to "pairing", which blocks self-chat and most DMs.

Fix:

Set dmPolicy: "open" at both levels:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "open",
      "selfChatMode": true,
      "accounts": {
        "default": {
          "dmPolicy": "open"
        }
      }
    }
  }
}

10. Control UI "Pairing Required" Error

Symptoms:

• Accessing the Control UI shows "Device pairing required" error
• Can't log in even with the correct token

Cause: By default, OpenClaw's Control UI requires device identity (keypair-based pairing) in addition to token auth.

Fix:

Add to your config:

{
  "gateway": {
    "mode": "local",
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true
    }
  }
}

This makes token-only authentication sufficient for the Control UI.

11. Telegram Bot Not Responding to Messages

Symptoms:

• Bot is online (shows as active in Telegram)
• Messages are sent but no reply comes

Cause candidates:

• API key is invalid or has no credits
• The bot hasn't been given permission to read messages (need to disable Privacy Mode via BotFather for group chats)
• dmPolicy is not set to "open"

Fix:

# Test your Anthropic API key
curl https://api.anthropic.com/v1/messages   -H "x-api-key: $ANTHROPIC_API_KEY"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

For group chats in Telegram, disable privacy mode via @BotFather → /mybots → Bot Settings → Group Privacy → Turn off.

12. Firewall Blocking Connections

Symptoms:

• Can access OpenClaw locally but not from the internet

Fix (Ubuntu UFW):

sudo ufw allow 8080/tcp
sudo ufw status

Fix (AWS Security Groups): Add inbound rule: TCP port 8080, source 0.0.0.0/0 (or your specific IP).

Fix (GCP Firewall):

gcloud compute firewall-rules create allow-openclaw --allow tcp:8080

13. Node.js Version Mismatch

Symptoms:

• Errors mentioning syntax not supported
• Works in Docker but not when running directly on host

Cause: OpenClaw requires Node.js 18+. Many Ubuntu installations default to Node.js 12 or 16 from the system packages.

Fix:

# Install Node.js 20 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node --version  # Verify: v20.x.x

14. Disk Space Issues

Symptoms:

• Container fails with "no space left on device"
• Docker pull fails

Fix:

# Check disk usage
df -h

# Clean up unused Docker resources
docker system prune -f
docker volume prune -f

# Check Docker's storage usage
docker system df

OpenClaw's image is ~300 MB and requires ~500 MB for the compiled WASM cache. Ensure at least 2 GB free disk space.

Quick Diagnostic Checklist

When OpenClaw won't start, run through this list:

1. docker logs openclaw — Look for exit reason
2. free -h — Check available RAM (need 2 GB+)
3. df -h — Check disk space (need 2 GB+)
4. cat config.json | python3 -m json.tool — Validate JSON syntax
5. Check for unrecognized config keys (see table above)
6. Verify gateway.mode is "local"
7. Verify bot token is correct and in the config JSON
8. Wait 5 minutes — WASM compilation takes time

Still Stuck?

If you've worked through this list and OpenClaw still won't cooperate, consider ClawMates — our managed platform that handles all of this automatically. No config files, no Docker, no server management. Just a working bot in under 2 minutes.