Tools: Report: OpenClaw Common Errors: 15 Fixes for the Most...

Tools: Report: OpenClaw Common Errors: 15 Fixes for the Most...

Error 1: Connection Refused on Port 18789

Symptom

Error 2: Blank Control UI

Symptom

Error 3: Typing Indicator but No Response

Symptom

Error 4: Skill Not Triggering

Symptom

Error 5: MCP Server Connection Failed

Symptom

Error 6: Gateway Not Listening on Port 18789

Symptom

Error 7: Heartbeat Burning Tokens

Symptom

Error 8: Memory Index Failing on Large Workspaces

Symptom

Error 9: Docker Volume Not Persisting

Symptom

Error 10: Config Validation Failed

Symptom

Error 11: WhatsApp Not Connecting

Symptom

Error 12: Telegram Webhook 409 Conflict

Symptom

Error 13: API Rate Limit (HTTP 429)

Symptom

Error 14: Session Deadlock

Symptom

Error 15: Permission Denied on Linux

Symptom

Frequently Asked Questions

Why does OpenClaw show a blank Control UI?

Why does my OpenClaw agent show a typing indicator but never respond?

How do I fix OpenClaw Docker volumes not persisting data?

Related Guides Free skills and AI personas for OpenClaw — browse the marketplace. Browse the Marketplace → Join 1k+ OpenClaw operators sharing deployment guides, security configs, and workflow automations. You try to access the OpenClaw gateway or send an API request and get Connection refused or ECONNREFUSED. 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. Important: Only bind to 0.0.0.0 if you have firewall rules in place. See the security audit guide before exposing the gateway. Navigating to http://your-server:3000 shows a blank white page with no content, or the page loads but all elements are missing. 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. If the UI is still blank after rebuilding, check that port 3000 is not being used by another service: 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. 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. If the logs show timeout after 120s, increase the API timeout: You installed a skill and it appears in openclaw skills list, but it never triggers when you send the expected commands or messages. 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. 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. Logs show MCP server connection failed or MCP handshake timeout. Custom MCP tools are unavailable. 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. 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. OpenClaw starts without errors but netstat or ss shows nothing listening on port 18789. The gateway is simply not starting. Another process is already using port 18789, or the gateway module failed to initialize due to a missing dependency. 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. 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. 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. Logs show memory index build failed or memory index timeout. The agent cannot access its memory files or daily logs. 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). 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. Free skills and AI personas for OpenClaw — browse the marketplace. Browse the Marketplace → Every time you restart the Docker container, your OpenClaw configuration, memory files, and conversation history are gone. You are running docker run without the -v flag, or using bind mounts with incorrect paths. Without a persistent volume, all data lives inside the container and is destroyed on restart. If you are using docker run directly, add volume flags: Verify the volume exists and has your data: OpenClaw refuses to start with Error: config validation failed followed by a list of invalid fields. The configuration file has syntax errors (usually from manual editing) or contains settings from an older version that are no longer valid. After regenerating, compare your backup file with the new config and re-apply your custom settings one at a time, validating after each change. The WhatsApp channel shows disconnected in the Control UI. Scanning the QR code works initially but the connection drops within hours. WhatsApp Web sessions expire when the phone's internet connection is unstable or when WhatsApp detects multiple web sessions. OpenClaw's WhatsApp integration uses the same protocol as WhatsApp Web. For persistent WhatsApp stability, ensure the phone linked to the account has a constant internet connection and is plugged into power. See OpenClaw WhatsApp Not Working Fix for a detailed walkthrough. Logs show 409 Conflict: terminated by other getUpdates request. The Telegram bot receives some messages but drops others. Two OpenClaw instances (or an OpenClaw instance and another bot framework) are both polling the same Telegram bot token. Telegram only allows one active polling connection per bot. If you need multiple agents on Telegram, create a separate bot token for each agent using @BotFather. Logs show HTTP 429 Too Many Requests or rate_limit_exceeded. The agent stops responding during busy periods. You have exceeded your LLM provider's rate limit. Anthropic's default rate limit for Claude API is 60 requests per minute on the standard tier. High-volume agents or agents with short heartbeat intervals can hit this limit. For sustained high-volume usage, request a rate limit increase from your API provider. Anthropic offers higher tiers through the Anthropic Console. The agent stops processing all messages. Logs show session lock timeout or deadlock detected. Restarting the service temporarily fixes it but the problem recurs. A long-running tool execution or a crashed skill holds the session lock indefinitely. Subsequent messages queue up waiting for the lock, creating a deadlock. For a detailed guide on session management, see OpenClaw Session Deadlock Fix. OpenClaw fails to start with EACCES: permission denied errors, or specific features fail with permission errors while the core service runs. The OpenClaw process is running as a user that does not have read/write access to the data directory, config files, or log directory. This commonly happens when OpenClaw was installed with sudo but runs as a non-root user via systemd. Do not run OpenClaw as root. Create a dedicated user with minimal permissions. See Common OpenClaw Setup Mistakes for the recommended user setup. A blank Control UI is almost always caused by the frontend assets failing to build during installation. Run openclaw rebuild-ui to regenerate the frontend, then clear your browser cache and reload. If the UI is still blank, check that port 3000 is not blocked by your firewall and that no other service is using the same port. The typing indicator with no response means OpenClaw is sending the request to the LLM API but not receiving a reply. Check your API key is valid and has available credits. Run openclaw logs --tail 50 to see the actual error. The most common causes are expired API keys, rate limiting (HTTP 429), and network timeouts. Use named volumes in your docker-compose.yml (volumes: openclaw-data:/app/data) instead of bind mounts. Verify the volume exists with docker volume ls and check permissions with docker exec openclaw ls -la /app/data. Free skills and AI personas for OpenClaw — browse the marketplace. Browse the Marketplace → Templates let you quickly answer FAQs or store snippets for re-use. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse

Command

Copy

# Check if the process is running -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">status openclaw # If not running, -weight: 500;">start it -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">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 -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">restart openclaw # Check if the process is running -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">status openclaw # If not running, -weight: 500;">start it -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">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 -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">restart openclaw # Check if the process is running -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">status openclaw # If not running, -weight: 500;">start it -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">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 -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">restart openclaw # Rebuild the frontend assets openclaw rebuild-ui # If build fails with out-of-memory, add swap space first -weight: 600;">sudo fallocate -l 2G /swapfile -weight: 600;">sudo chmod 600 /swapfile -weight: 600;">sudo mkswap /swapfile -weight: 600;">sudo swapon /swapfile openclaw rebuild-ui # Clear browser cache and reload with Ctrl+Shift+R # Rebuild the frontend assets openclaw rebuild-ui # If build fails with out-of-memory, add swap space first -weight: 600;">sudo fallocate -l 2G /swapfile -weight: 600;">sudo chmod 600 /swapfile -weight: 600;">sudo mkswap /swapfile -weight: 600;">sudo swapon /swapfile openclaw rebuild-ui # Clear browser cache and reload with Ctrl+Shift+R # Rebuild the frontend assets openclaw rebuild-ui # If build fails with out-of-memory, add swap space first -weight: 600;">sudo fallocate -l 2G /swapfile -weight: 600;">sudo chmod 600 /swapfile -weight: 600;">sudo mkswap /swapfile -weight: 600;">sudo swapon /swapfile openclaw rebuild-ui # Clear browser cache and reload with Ctrl+Shift+R -weight: 600;">sudo lsof -i :3000 -weight: 600;">sudo lsof -i :3000 -weight: 600;">sudo lsof -i :3000 # 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 -weight: 500;">curl -v https://api.anthropic.com/v1/messages # 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 -weight: 500;">curl -v https://api.anthropic.com/v1/messages # 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 -weight: 500;">curl -v https://api.anthropic.com/v1/messages openclaw config set api.timeout 300 openclaw config set api.timeout 300 openclaw config set api.timeout 300 # 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" # 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" # 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" # Check the MCP server configuration openclaw config get mcp.servers # Verify the MCP server is running and accessible -weight: 500;">curl http://localhost:8080/health # or your MCP server URL # Check MCP protocol version compatibility openclaw mcp version-check # If version mismatch, -weight: 500;">update the MCP server -weight: 500;">npm -weight: 500;">update @modelcontextprotocol/server # for Node.js MCP servers -weight: 500;">pip -weight: 500;">install ---weight: 500;">upgrade mcp-server # for Python MCP servers # Check the MCP server configuration openclaw config get mcp.servers # Verify the MCP server is running and accessible -weight: 500;">curl http://localhost:8080/health # or your MCP server URL # Check MCP protocol version compatibility openclaw mcp version-check # If version mismatch, -weight: 500;">update the MCP server -weight: 500;">npm -weight: 500;">update @modelcontextprotocol/server # for Node.js MCP servers -weight: 500;">pip -weight: 500;">install ---weight: 500;">upgrade mcp-server # for Python MCP servers # Check the MCP server configuration openclaw config get mcp.servers # Verify the MCP server is running and accessible -weight: 500;">curl http://localhost:8080/health # or your MCP server URL # Check MCP protocol version compatibility openclaw mcp version-check # If version mismatch, -weight: 500;">update the MCP server -weight: 500;">npm -weight: 500;">update @modelcontextprotocol/server # for Node.js MCP servers -weight: 500;">pip -weight: 500;">install ---weight: 500;">upgrade mcp-server # for Python MCP servers # Check what is using port 18789 -weight: 600;">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 # Check what is using port 18789 -weight: 600;">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 # Check what is using port 18789 -weight: 600;">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 # 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 -weight: 500;">disable heartbeat entirely (agent will cold--weight: 500;">start on each message) openclaw config set heartbeat.enabled false # 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 -weight: 500;">disable heartbeat entirely (agent will cold--weight: 500;">start on each message) openclaw config set heartbeat.enabled false # 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 -weight: 500;">disable heartbeat entirely (agent will cold--weight: 500;">start on each message) openclaw config set heartbeat.enabled false # 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 # 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 # 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 # Use named volumes in -weight: 500;">docker-compose.yml # -weight: 500;">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: # Use named volumes in -weight: 500;">docker-compose.yml # -weight: 500;">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: # Use named volumes in -weight: 500;">docker-compose.yml # -weight: 500;">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: -weight: 500;">docker run -d \ -v openclaw-data:/app/data \ -v openclaw-config:/app/config \ -p 18789:18789 \ -p 3000:3000 \ openclaw/openclaw:latest -weight: 500;">docker run -d \ -v openclaw-data:/app/data \ -v openclaw-config:/app/config \ -p 18789:18789 \ -p 3000:3000 \ openclaw/openclaw:latest -weight: 500;">docker run -d \ -v openclaw-data:/app/data \ -v openclaw-config:/app/config \ -p 18789:18789 \ -p 3000:3000 \ openclaw/openclaw:latest -weight: 500;">docker volume ls -weight: 500;">docker exec openclaw ls -la /app/data -weight: 500;">docker volume ls -weight: 500;">docker exec openclaw ls -la /app/data -weight: 500;">docker volume ls -weight: 500;">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 # 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 # 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 -weight: 500;">status openclaw channel -weight: 500;">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 # Check WhatsApp connection -weight: 500;">status openclaw channel -weight: 500;">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 # Check WhatsApp connection -weight: 500;">status openclaw channel -weight: 500;">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 -weight: 500;">curl "https://api.telegram.org/botYOUR_TOKEN/deleteWebhook" # Restart only the single instance that should handle this bot -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">restart openclaw # Verify only one connection is active openclaw channel -weight: 500;">status telegram # Stop all instances using this bot token # Then delete the webhook to reset -weight: 500;">curl "https://api.telegram.org/botYOUR_TOKEN/deleteWebhook" # Restart only the single instance that should handle this bot -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">restart openclaw # Verify only one connection is active openclaw channel -weight: 500;">status telegram # Stop all instances using this bot token # Then delete the webhook to reset -weight: 500;">curl "https://api.telegram.org/botYOUR_TOKEN/deleteWebhook" # Restart only the single instance that should handle this bot -weight: 600;">sudo -weight: 500;">systemctl -weight: 500;">restart openclaw # Verify only one connection is active openclaw channel -weight: 500;">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 # 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 # 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 # 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 # 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.-weight: 500;">service # Fix ownership of the OpenClaw directories -weight: 600;">sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/ -weight: 600;">sudo chown -R openclaw:openclaw /var/log/openclaw/ # Ensure the data directory has correct permissions -weight: 600;">sudo chmod -R 750 /home/openclaw/.openclaw/ # Check which user OpenClaw runs as grep "User=" /etc/systemd/system/openclaw.-weight: 500;">service # Fix ownership of the OpenClaw directories -weight: 600;">sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/ -weight: 600;">sudo chown -R openclaw:openclaw /var/log/openclaw/ # Ensure the data directory has correct permissions -weight: 600;">sudo chmod -R 750 /home/openclaw/.openclaw/ # Check which user OpenClaw runs as grep "User=" /etc/systemd/system/openclaw.-weight: 500;">service # Fix ownership of the OpenClaw directories -weight: 600;">sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/ -weight: 600;">sudo chown -R openclaw:openclaw /var/log/openclaw/ # Ensure the data directory has correct permissions -weight: 600;">sudo chmod -R 750 /home/openclaw/.openclaw/ - Common OpenClaw Setup Mistakes and How to Fix Them - OpenClaw Logs and Debugging Guide - Reducing OpenClaw Token Costs (Up to 90% Cheaper) - OpenClaw Docker Compose Guide - OpenClaw Tools Disabled After Update: How to Fix It