OpenClaw Common Errors: 15 Fixes for the Most Frustrating Problems

Error 1: Connection Refused on Port 18789

Symptom

You try to access the OpenClaw gateway or send an API request and get Connection refused or ECONNREFUSED.

Cause

The OpenClaw gateway process is not running, or it is listening on a different interface (localhost vs. 0.0.0.0). This is the most common error after a fresh install, accounting for roughly 25% of first-time setup failures based on community reports.

Fix

# Check if the process is running
sudo systemctl status openclaw

# If not running, start it
sudo systemctl start openclaw

# If running but refusing connections, check the bind address
openclaw config get gateway.bindAddress

# Default is 127.0.0.1 (localhost only). To allow remote access:
openclaw config set gateway.bindAddress 0.0.0.0
sudo systemctl restart openclaw

Important: Only bind to 0.0.0.0 if you have firewall rules in place. See the security audit guide before exposing the gateway.

Error 2: Blank Control UI

Symptom

Navigating to http://your-server:3000 shows a blank white page with no content, or the page loads but all elements are missing.

Cause

The frontend assets failed to build during installation, or the browser is caching a stale version. This happens frequently on low-memory VPS instances (1GB RAM) where the build process gets killed by the OOM killer.

Fix

# Rebuild the frontend assets
openclaw rebuild-ui

# If build fails with out-of-memory, add swap space first
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
openclaw rebuild-ui

# Clear browser cache and reload with Ctrl+Shift+R

If the UI is still blank after rebuilding, check that port 3000 is not being used by another service:

sudo lsof -i :3000

Error 3: Typing Indicator but No Response

Symptom

You send a message to your agent through Telegram, WhatsApp, or the Control UI. The typing indicator appears (or "processing" shows in the UI), but no response ever comes back.

Cause

OpenClaw is sending the request to the LLM API but the API is not returning a response. The three most common causes are: expired or invalid API key, rate limiting (HTTP 429), and network timeouts on VPS providers that throttle outbound HTTPS.

Fix

# Check the logs for the actual error
openclaw logs --tail 50

# Test the API key directly
openclaw test-api-key

# If rate limited, check your usage
openclaw config get api.provider
# Then check your usage dashboard at the provider's site

# If network timeout, test outbound connectivity
curl -v https://api.anthropic.com/v1/messages

If the logs show timeout after 120s, increase the API timeout:

openclaw config set api.timeout 300

Error 4: Skill Not Triggering

Symptom

You installed a skill and it appears in openclaw skills list, but it never triggers when you send the expected commands or messages.

Cause

Skills require matching trigger patterns in the SKILL.md file, and the agent's system prompt must reference the skill. If the skill was installed after the last context refresh, the agent does not know it exists yet.

Fix

# Verify the skill is installed and active
openclaw skills list --verbose

# Check the skill's trigger pattern
openclaw skills inspect skill-name

# Force a context refresh so the agent loads the new skill
openclaw context refresh

# Test the trigger directly
openclaw skills test skill-name "your trigger message"

If the skill still does not trigger, check that its required tool categories are enabled. After the 2026.3.2 update, skills that require disabled tool categories fail silently. See OpenClaw Tools Disabled After Update.

Error 5: MCP Server Connection Failed

Symptom

Logs show MCP server connection failed or MCP handshake timeout. Custom MCP tools are unavailable.

Cause

The MCP server process is not running, the connection URL is wrong, or the MCP protocol version is mismatched between OpenClaw and your MCP server.

Fix

# Check the MCP server configuration
openclaw config get mcp.servers

# Verify the MCP server is running and accessible
curl http://localhost:8080/health  # or your MCP server URL

# Check MCP protocol version compatibility
openclaw mcp version-check

# If version mismatch, update the MCP server
npm update @modelcontextprotocol/server  # for Node.js MCP servers
pip install --upgrade mcp-server          # for Python MCP servers

The MCP protocol had a breaking change in version 0.9.0 (February 2026). If your MCP server was built before this date, it likely needs updating. Check the MCP specification repository for migration guidance.

Error 6: Gateway Not Listening on Port 18789

Symptom

OpenClaw starts without errors but netstat or ss shows nothing listening on port 18789. The gateway is simply not starting.

Cause

Another process is already using port 18789, or the gateway module failed to initialize due to a missing dependency.

Fix

# Check what is using port 18789
sudo ss -tlnp | grep 18789

# If another process owns the port, kill it or change OpenClaw's port
openclaw config set gateway.port 18790

# Check gateway initialization logs specifically
openclaw logs --filter gateway --tail 30

# If missing dependency, reinstall gateway module
openclaw module reinstall gateway

Error 7: Heartbeat Burning Tokens

Symptom

Your API token usage is abnormally high even when you are not interacting with the agent. The cost dashboard shows constant small requests throughout the day.

Cause

OpenClaw's heartbeat system sends periodic check-in messages to the LLM to maintain context freshness. The default interval is every 5 minutes, which can consume $3-8 per day in API costs depending on the model and context size.

Fix

# Check current heartbeat interval
openclaw config get heartbeat.interval

# Increase the interval to reduce token waste
openclaw config set heartbeat.interval 30m  # every 30 minutes

# Or disable heartbeat entirely (agent will cold-start on each message)
openclaw config set heartbeat.enabled false

Disabling heartbeat means the agent takes 3-8 seconds longer to respond to the first message after a period of inactivity, because it needs to reload context from disk. For most use cases, a 30-minute interval is the best balance between responsiveness and cost. See Reducing OpenClaw Token Costs for more optimization strategies.

Error 8: Memory Index Failing on Large Workspaces

Symptom

Logs show memory index build failed or memory index timeout. The agent cannot access its memory files or daily logs.

Cause

The memory index scans all files in the memory directory on startup. If the directory contains hundreds of daily log files or large attachments, the indexing process times out (default 30 seconds).

Fix

# Check how many files are in the memory directory
ls -la ~/.openclaw/memory/ | wc -l

# Archive old daily logs (keep last 30 days)
mkdir -p ~/.openclaw/memory/archive
find ~/.openclaw/memory/daily-logs/ -name "*.md" -mtime +30 \
  -exec mv {} ~/.openclaw/memory/archive/ \;

# Increase the index timeout
openclaw config set memory.indexTimeout 120

# Rebuild the memory index
openclaw memory reindex

For long-term management, set up a weekly cron job to archive logs older than 30 days. This keeps the memory directory lean and the index fast.

Error 9: Docker Volume Not Persisting

Symptom

Every time you restart the Docker container, your OpenClaw configuration, memory files, and conversation history are gone.

# Use named volumes in docker-compose.yml
# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
      - "3000:3000"
    volumes:
      - openclaw-data:/app/data
      - openclaw-config:/app/config

volumes:
  openclaw-data:
  openclaw-config:

docker run -d \
  -v openclaw-data:/app/data \
  -v openclaw-config:/app/config \
  -p 18789:18789 \
  -p 3000:3000 \
  openclaw/openclaw:latest

docker volume ls
docker exec openclaw ls -la /app/data

# Validate the config and see specific errors
openclaw config validate

# Reset a specific broken setting to default
openclaw config reset gateway.bindAddress

# If the entire config is corrupted, back up and regenerate
cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.bak
openclaw config init

# Check WhatsApp connection status
openclaw channel status whatsapp

# Force a fresh connection (will require new QR scan)
openclaw channel reconnect whatsapp

# Enable auto-reconnect to handle temporary drops
openclaw config set channels.whatsapp.autoReconnect true
openclaw config set channels.whatsapp.reconnectInterval 30

# Stop all instances using this bot token
# Then delete the webhook to reset
curl "https://api.telegram.org/botYOUR_TOKEN/deleteWebhook"

# Restart only the single instance that should handle this bot
sudo systemctl restart openclaw

# Verify only one connection is active
openclaw channel status telegram

# Enable built-in rate limit handling
openclaw config set api.rateLimitRetry true
openclaw config set api.rateLimitBackoff exponential

# Set maximum concurrent requests
openclaw config set api.maxConcurrent 5

# Reduce heartbeat frequency to lower baseline usage
openclaw config set heartbeat.interval 30m

# Force-release the session lock
openclaw session unlock --force

# Set a maximum lock duration to prevent future deadlocks
openclaw config set session.lockTimeout 120

# Identify which skill or tool caused the deadlock
openclaw logs --filter "lock acquired" --tail 20

# Check which user OpenClaw runs as
grep "User=" /etc/systemd/system/openclaw.service

# Fix ownership of the OpenClaw directories
sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/
sudo chown -R openclaw:openclaw /var/log/openclaw/

# Ensure the data directory has correct permissions
sudo chmod -R 750 /home/openclaw/.openclaw/