Docs / Troubleshooting
OpenClaw Troubleshooting
Common blockers grouped by deployment stage, each with commands, config diffs, and verification steps.
Install & Environment
Before install
Install script blocked (network/proxy)
Symptoms: curl or npm downloads fail or time out.
Cause: Restricted network or missing proxy settings.
Solution
Command
curl -I https://openclaw.bot/install.sh export https_proxy=http://127.0.0.1:7890 export http_proxy=http://127.0.0.1:7890
Config change
+ https_proxy=http://127.0.0.1:7890 + http_proxy=http://127.0.0.1:7890
Why this works: Routes downloads through your proxy so installs and dependencies can resolve.
Verification: Re-run the install command and confirm downloads succeed.
Screenshot: /images/troubleshooting/en/network.png
Docker daemon not running
Symptoms: Docker commands fail or containers exit immediately.
Cause: Docker service stopped or not enabled.
Solution
Command
sudo systemctl status docker sudo systemctl enable --now docker
Config change
- restart: "no" + restart: unless-stopped
Why this works: Ensures Docker is running and containers restart after reboots.
Verification: docker ps shows running containers after a reboot.
Screenshot: /images/troubleshooting/en/docker-start.png
Permission denied on data directory
Symptoms: Writes fail with Permission denied or EACCES.
Cause: Data directory owned by root or mismatched volume path.
Solution
Command
sudo chown -R $USER:$USER ~/.openclaw ls -la ~/.openclaw
Config change
- ./openclaw-data:/root/.openclaw + ~/.openclaw:/root/.openclaw
Why this works: Aligns the volume with a user-owned directory so the gateway can write data.
Verification: Restart succeeds and files appear under ~/.openclaw.
Screenshot: /images/troubleshooting/en/permission.png
Onboarding & Startup
During setup
Onboarding hangs or no model response
Symptoms: CLI onboarding stalls or channel replies never arrive.
Cause: Missing/invalid API key or outbound traffic blocked.
Solution
Command
openclaw config get | head -n 20 openclaw gateway restart
Config change
+ ANTHROPIC_API_KEY=sk-REPLACE_ME
Why this works: Ensures the gateway can authenticate with the model provider.
Verification: openclaw health returns OK and test messages respond.
Screenshot: /images/troubleshooting/en/config.png
Control UI port already in use
Symptoms: SSH tunnel or UI connection fails with EADDRINUSE.
Cause: Another process is bound to port 18789.
Solution
Command
sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 18789
Config change
- "18789:18789" + "18790:18789"
Why this works: Moves the host port mapping to avoid conflicts while keeping the internal port.
Verification: Tunnel connects on the new port and the UI loads.
Screenshot: /images/troubleshooting/en/port-in-use.png
Config edits not taking effect
Symptoms: You change config but behavior doesn’t change.
Cause: Editing the wrong config path or not restarting the gateway.
Solution
Command
openclaw config get openclaw gateway restart
Config change
+ OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
Why this works: Forces the gateway to read from the correct config file.
Verification: Config values match your edits after restart.
Screenshot: /images/troubleshooting/en/config.png
Runtime & Stability
After launch
Data not persisted after restart
Symptoms: Settings reset after container restarts.
Cause: No host volume mapped for state/workspace.
Solution
Command
ls -la ~/.openclaw docker compose ps
Config change
- volumes: - - ./openclaw-data:/root/.openclaw + volumes: + - ~/.openclaw:/root/.openclaw
Why this works: Persists state to the host so restarts keep your config and data.
Verification: Restarted gateway keeps settings and history.
Screenshot: /images/troubleshooting/en/data.png
Memory pressure / OOM
Symptoms: Process killed under load or OOM logs appear.
Cause: Insufficient RAM for the current workload.
Solution
Command
free -m journalctl -k | grep -i oom
Config change
- plan: entry + plan: standard
Why this works: More memory or a larger VPS tier prevents OOM kills.
Verification: No OOM events during peak usage.
Screenshot: /images/troubleshooting/en/memory.png