17 Essential OpenClaw Pitfalls and How to Fix Them for Beginners

Installation & Configuration (5 pitfalls)

Pitfall 1: Incompatible Node.js version

Problem : npm install -g openclaw fails with ERR_UNSUPPORTED_NODE_VERSION or TypeError: structuredClone is not a function.

Cause : OpenClaw requires Node.js ≥ 22.16 (features such as native fetch, structuredClone, --experimental-vm-modules). Most developers still run v18 or v20.

Solution :

Upgrade via nvm install 24 && nvm use 24 (recommended).

Or download the v24 LTS installer from the Node.js website.

For a one‑off test, run npx -p node@24 openclaw --version.

Prevention : Verify the version with node -v before installing and manage Node.js with nvm.

Quick‑check script :

#!/bin/bash
node -v && echo "✅ Node.js version meets requirement"

Pitfall 2: npm permission errors

Problem : Global install errors such as EACCES: permission denied when writing to /usr/local/lib/node_modules.

Cause : npm tries to write to system directories that require root privileges.

Solution :

Create a user‑local npm prefix:

mkdir "$HOME/.npm-global" && npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.zshrc
npm install -g openclaw

Or use nvm, which installs Node.js per user and avoids permission issues.

Avoid sudo npm install -g unless absolutely necessary.

Prevention : Prefer nvm or a user‑local npm directory for all global packages.

Pitfall 3: Configuration file format errors

Problem : Errors like JSON5 parse error at line 15 or Unexpected token when starting the gateway.

Cause : ~/.openclaw/openclaw.json uses JSON5 (allows comments and trailing commas) but may contain unclosed brackets, mismatched quotes, or misspelled keys.

Solution :

Run openclaw doctor to auto‑validate and fix common issues ( openclaw doctor --fix).

Use VSCode with a JSON5 extension for syntax highlighting and auto‑formatting ( Shift+Alt+F).

Manage configuration via the CLI:

openclaw config get gateway.port
openclaw config set gateway.port 18790
openclaw config unset gateway.port

Validate manually with Node.js:

node -e "require('json5'); console.log(JSON.stringify(require('json5').parse(require('fs').readFileSync('$HOME/.openclaw/openclaw.json','utf8')),null,2))"

Prevention : Keep the config under version control, edit only with openclaw config, and run openclaw doctor after changes.

Pitfall 4: Environment variables not taking effect

Problem : Variables such as OPENCLAW_TOKEN or OPENCLAW_WORKSPACE appear unset when the gateway starts.

Cause : Variables defined in a shell rc file are not loaded in the current session, systemd services do not inherit user env, or multiple rc files override each other.

Solution :

Export variables in ~/.zshrc and source the file before starting:

export OPENCLAW_TOKEN="your-token"
export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"
source ~/.zshrc
echo $OPENCLAW_TOKEN

Create a startup script (e.g., ~/bin/openclaw-start.sh) that sets the variables and launches the gateway.

#!/bin/bash
export OPENCLAW_TOKEN="your-token"
export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"
openclaw gateway start

For systemd, add Environment="OPENCLAW_TOKEN=…" lines to the service unit.

Use a .env file with dotenv-cli:

OPENCLAW_TOKEN=your-token
OPENCLAW_WORKSPACE=$HOME/.openclaw/workspace
npx dotenv-cli -- openclaw gateway start

Prevention : Verify with echo $OPENCLAW_TOKEN after any change and keep sensitive values out of the config file.

Pitfall 5: Residual files from old versions

Problem : After upgrading, commands behave unexpectedly or installation fails with EEXIST: file already exists.

Cause : Old global packages, stale config files, or multiple install locations remain.

Solution :

Run the official uninstall command:

openclaw gateway stop
openclaw uninstall --all
rm -rf ~/.openclaw
npm cache clean --force
npm install -g openclaw@latest

Or manually remove all locations:

pkill -f openclaw
npm uninstall -g openclaw
rm -rf /usr/local/lib/node_modules/openclaw
rm -rf /usr/local/bin/openclaw
rm -rf ~/.openclaw/cache
npm cache clean --force
npm install -g openclaw

Check for multiple binaries with which -a openclaw and keep only one.

Prevention : Backup ~/.openclaw before upgrading and always use openclaw uninstall --all instead of manual deletion.

Gateway Service (4 pitfalls)

Pitfall 6: Port 18789 already in use

Problem : Starting the gateway fails with EADDRINUSE or health checks return connection refused.

Cause : The default port is occupied by another gateway instance, a different service, or a zombie process.

Solution :

Find and kill the occupying process:

lsof -i :18789
kill 1234   # or kill -9 1234
openclaw gateway start

Use OpenClaw commands to stop all instances:

openclaw gateway status
openclaw gateway stop --all
openclaw gateway start

Change the port via configuration:

openclaw config set gateway.port 18790
# or edit ~/.openclaw/openclaw.json:
# { "gateway": { "port": 18790 } }

One‑line cleanup script:

#!/bin/bash
PORT=${1:-18789}
PID=$(lsof -ti :$PORT)
if [ -n "$PID" ]; then
  echo "⚠️ Killing process $PID on port $PORT"
  kill $PID || kill -9 $PID
  sleep 1
  echo "✅ Port $PORT released"
else
  echo "✅ Port $PORT not in use"
fi

Prevention : Run openclaw gateway status before launching; consider containerisation to isolate ports.

Pitfall 7: Gateway exits immediately after start

Problem : openclaw gateway start prints “Gateway started.” then returns to the shell; openclaw gateway status shows not running.

Cause : Invalid config file, expired token, insufficient permissions, missing workspace, or dependent services down.

Solution :

Inspect logs:

openclaw logs gateway --follow
journalctl -u openclaw -n 50

Run the built‑in health check:

openclaw doctor

The output highlights which checks failed (e.g., ❌ Token: invalid or expired).

Validate the config file:

openclaw config get gateway
openclaw doctor --fix

Check workspace permissions (see Pitfall 14).

Run in foreground for debugging:

openclaw gateway run --verbose

Prevention : Always run openclaw doctor after any config change and start the gateway before any agents.

Pitfall 8: Token authentication failure

Problem : API calls return 401 Unauthorized with {"error":"unauthorized"}.

Cause : Token mismatch, expiration, formatting errors, or revocation.

Solution :

Generate a new token and update the config:

openclaw token generate
# Example output: New token generated: oc_token_abc123def456...
openclaw config set token "oc_token_abc123def456..."
openclaw gateway restart

Verify the token value contains no extra spaces:

openclaw config get token

Test with curl:

TOKEN="your-token"
curl -H "Authorization: Bearer $TOKEN" http://localhost:18789/api/health

Check token permissions:

openclaw token info $TOKEN
# Ensure scopes such as gateway:connect, agent:execute, channel:send are present

Prevention : Manage tokens with openclaw config, rotate every 90 days, store them in a secret manager, and keep separate tokens for different environments.

Pitfall 9: Multiple Gateway instances conflict

Problem : Running more than one gateway leads to port conflicts, duplicate message processing, and unpredictable routing.

Cause : OpenClaw is designed for a single gateway with multiple agents; launching several gateways shares the same configuration and port.

Solution :

Adopt the recommended single‑gateway architecture:

# Start one gateway
openclaw gateway start
# Start any number of agents
openclaw agent start agent-1
openclaw agent start agent-2

For true multi‑tenant scenarios, isolate each gateway with a separate profile and distinct ports:

# Profile directories
mkdir -p ~/.openclaw/profiles/gw1
mkdir -p ~/.openclaw/profiles/gw2
# gw1 uses port 18789, gw2 uses 18790
OPENCLAW_CONFIG=~/.openclaw/profiles/gw1 openclaw gateway start
OPENCLAW_CONFIG=~/.openclaw/profiles/gw2 openclaw gateway start

Containerise each gateway with its own port mapping (docker‑compose example omitted for brevity).

Prevention : Keep to a single gateway unless isolation is required; verify registered agents with openclaw agents list and document the intended topology.

Channel Integration (4 pitfalls)

Pitfall 10: WeChat IP whitelist rejection

Problem : Callback URL returns invalid ip, not in whitelist (error code 40164).

Cause : Server IP not listed in the WeChat backend whitelist; dynamic or multiple outbound IPs; proxying through an unlisted IP.

Solution :

Query the current public IP and add it to the whitelist:

curl ifconfig.me
# Add the returned IP in the WeChat console under IP whitelist.

Use a cloud server with a fixed public IP or a stable proxy.

If behind a proxy, ensure the proxy’s IP is whitelisted.

Prevention : Keep a documented list of allowed IPs and update it whenever the server’s outbound IP changes.

Pitfall 11: Feishu WebSocket connection failure

Problem : Errors such as WebSocket connection failed: connection refused or invalid encrypt_key.

Cause : Wrong encrypt key, AppSecret, network blockage, missing permissions, or firewall restrictions.

Solution :

Verify the four parameters (App ID, App Secret, Encrypt Key, Verification Token) in the Feishu Open Platform.

Test API connectivity:

curl -I https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal

Re‑configure via the CLI:

openclaw channels config feishu --interactive

Check that outbound port 443 is open and that DNS resolves open.feishu.cn.

Prevention : Keep Feishu credentials in a secret manager, run openclaw channels status feishu after any change.

Pitfall 12: Telegram Bot webhook not receiving messages

Problem : Bot receives no messages; webhook status shows failed and logs contain 404 Not Found.

Cause : Webhook not set, wrong token, non‑HTTPS URL, or using a blocked port.

Solution :

Configure the bot in openclaw.json (or via CLI) with botToken and an optional webhookUrl.

Or set the webhook manually:

curl -F "url=https://your-domain.com/telegram-webhook" https://api.telegram.org/bot$TOKEN/setWebhook
curl https://api.telegram.org/bot$TOKEN/getWebhookInfo

Ensure the URL is HTTPS and uses an allowed port (443, 80, 88, 8443).

Prevention : Use HTTPS, keep the token in an environment variable, and verify webhook health with openclaw doctor.

Pitfall 13: Duplicate channel messages

Problem : The same message is delivered 2‑3 times to users.

Cause : Multiple channels subscribed to the same event, several agents processing the same message, or aggressive retry logic.

Solution :

List configured channels and ensure each event routes to only one channel:

openclaw channels list

Use allowFrom or dmPolicy: "allowlist" to restrict sources.

Implement ID‑based deduplication in custom agents (example code below).

// Example deduplication using a Set of processed IDs
const processed = new Set();
function handle(msg) {
  if (processed.has(msg.id)) { console.log(`Message ${msg.id} already processed`); return; }
  processed.add(msg.id);
  // process the message …
  setTimeout(() => processed.delete(msg.id), 300000); // clean after 5 min
}

Prevention : Design clear routing rules, enable allowFrom, and add deduplication logic where needed.

Multi‑Agent Coordination (2 pitfalls)

Pitfall 14: Agent workspace permission errors

Problem : Errors such as

EACCES: permission denied, open '/Users/.../.openclaw/workspace/data.json'

.

Cause : Workspace directory owned by root or with restrictive permissions; SELinux/AppArmor restrictions; Docker UID/GID mismatch.

Solution :

Reset ownership and permissions:

chown -R $(whoami):$(whoami) ~/.openclaw/workspace
chmod -R 755 ~/.openclaw/workspace

Avoid creating the workspace with sudo; always create it as the regular user.

When using Docker, run the container with matching UID/GID:

# docker‑compose example snippet
services:
  agent:
    image: openclaw/agent:latest
    user: "${UID}:${GID}"
    volumes:
      - ~/.openclaw/workspace:/app/workspace

Prevention : Create the workspace as the current user, verify permissions before starting agents, and map UID/GID correctly in containers.

Pitfall 15: Agent‑to‑Agent communication failure

Problem : One agent cannot invoke another; messages are lost; distributed tasks are incomplete.

Cause : Gateway not running, incorrect routing configuration, network isolation, or mismatched authentication tokens.

Solution :

Ensure the gateway is up:

openclaw gateway status
curl http://localhost:18789/health

Verify agents are registered:

openclaw agents list
openclaw agents status agent-a

Check routing rules in openclaw.json (agents communicate via the gateway by default).

Test a direct message:

openclaw agents send --from agent-a --to agent-b --message "test"
openclaw logs agent-b --follow

Prevention : Start the gateway before any agents, keep the agent list up‑to‑date, and document inter‑agent dependencies.

Runtime Performance (2 pitfalls)

Pitfall 16: Excessive memory usage

Problem : Gateway or agent processes grow to several gigabytes and eventually trigger OOM.

Cause : Memory leaks, unbounded caches, large objects not released, or accumulated event listeners.

Solution :

Temporary relief: restart the service.

openclaw gateway restart

Limit Node.js heap size:

export NODE_OPTIONS="--max-old-space-size=1024"   # 1 GB
openclaw gateway start

Use a process manager such as PM2 with automatic memory‑based restarts:

npm install -g pm2
pm2 start openclaw --name gateway --gateway start --max-memory-restart 1G
pm2 monit

Upgrade to the latest OpenClaw version where known leaks are fixed:

npm update -g openclaw

Prevention : Monitor memory with ps aux | grep openclaw or PM2, schedule periodic restarts, and keep the software up‑to‑date.

Pitfall 17: Slow response times

Problem : Commands or API calls take several seconds (e.g., time openclaw agents list > 5 s).

Cause : Slow AI model API, network latency, heavy disk I/O, high concurrency, or unoptimized database queries.

Solution :

Switch to a faster model or a nearer endpoint:

openclaw config set model "ollama/llama2"

Increase request timeout if the model is inherently slower:

openclaw config set timeout 30000   # 30 s

Limit concurrent requests and enable a request queue:

openclaw config set gateway.maxConcurrentRequests 10
openclaw config set gateway.requestQueue.enabled true
openclaw config set gateway.requestQueue.maxSize 100

Enable response caching:

openclaw config set cache.enabled true
openclaw config set cache.ttl 300   # seconds

Reduce log I/O overhead:

openclaw config set logging.maxSize 10M
openclaw config set logging.maxFiles 5

Prevention : Choose low‑latency model providers, configure reasonable timeouts, enable caching, and monitor system metrics.

Quick‑Check Lists

Startup Failure Checklist

1. Verify Node.js version (>=22.16, recommended 24).
2. Run <strong>openclaw doctor</strong> to validate configuration.
3. Check port 18789: <code>lsof -i :18789</code>.
4. View recent gateway logs: <code>openclaw logs gateway --lines 50</code>.
5. Run health check again: <code>openclaw doctor</code>.

Connection Issue Checklist

1. <code>openclaw gateway status</code> and <code>curl http://localhost:18789/health</code>.
2. Verify token: <code>openclaw config get token</code> and test with curl.
3. Check channel status: <code>openclaw channels status <name></code>.
4. Ping external APIs (e.g., <code>ping api.openai.com</code>).

Performance Issue Checklist

1. Inspect CPU/memory: <code>top -pid $(pgrep -f "openclaw gateway")</code>.
2. Check log size: <code>du -sh ~/.openclaw/logs</code>.
3. Measure model latency: <code>time curl https://api.model.com/v1/…</code>.
4. Restart gateway if needed: <code>openclaw gateway restart</code>.

Command Cheat Sheet

Basic Commands

openclaw --version

– show version. openclaw doctor – run health diagnostics. openclaw config – manage configuration. openclaw logs – view logs.

Gateway Management

openclaw gateway start

– start the gateway. openclaw gateway stop – stop the gateway. openclaw gateway restart – restart the gateway. openclaw gateway status – show running status.

Channel Management

openclaw channels list

– list all channels. openclaw channels config <name> – configure a channel. openclaw channels status <name> – check channel health. openclaw channels test <name> – send a test message.

Agent Management

openclaw agents list

– list agents. openclaw agents start <name> – start an agent. openclaw agents stop <name> – stop an agent. openclaw agents status <name> – show agent status.