Skip to content
Last updated

Docs / Troubleshooting

OpenClaw Troubleshooting for gateway, Telegram, and browser relay issues

Find OpenClaw troubleshooting steps for installation, gateway token, Telegram channel replies, browser relay, Docker, and runtime failures.

Install & Environment

Before install

Install script blocked (network/proxy)

Expand

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:

Install script blocked (network/proxy) screenshot

Docker daemon not running

Expand

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:

Docker daemon not running screenshot

Permission denied on data directory

Expand

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:

Permission denied on data directory screenshot

Onboarding & Startup

During setup

Onboarding hangs or no model response

Expand

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:

Onboarding hangs or no model response screenshot

Control UI port already in use

Expand

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:

Control UI port already in use screenshot

Config edits not taking effect

Expand

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:

Config edits not taking effect screenshot

Channels & Access

After the first successful install

Telegram bot starts but never replies

Expand

Symptoms: Telegram accepts /start but normal messages never get a response.

Cause: The bot token is wrong, the gateway did not restart, or outbound access to Telegram is blocked.

Solution

Command

openclaw config get channels.telegram.botToken
openclaw gateway restart
curl -I https://api.telegram.org

Config change

- channels.telegram.enabled: false
+ channels.telegram.enabled: true
+ channels.telegram.botToken: "YOUR_TELEGRAM_BOT_TOKEN"

Why this works: This confirms the Telegram bot token is present, the channel is enabled, and the gateway has reloaded the new settings with working network access.

Verification: Send /start again in Telegram and confirm a normal text message receives a reply.

Screenshot:

Telegram bot starts but never replies screenshot

Gateway token invalid, missing, or rejected

Expand

Symptoms: Gateway calls return unauthorized, forbidden, or missing token errors.

Cause: The runtime token is unset, mismatched, or exposed through the wrong proxy or client config.

Solution

Command

openclaw config get gateway.token
openclaw gateway restart
printenv | grep -i OPENCLAW

Config change

- gateway.token: ""
+ gateway.token: "REPLACE_WITH_A_STRONG_SECRET"

Why this works: A consistent gateway token across runtime and client access paths prevents unauthorized requests and avoids stale config mismatches.

Verification: Health checks and protected gateway calls succeed only when the configured token is present.

Screenshot:

Gateway token invalid, missing, or rejected screenshot

Browser relay cannot connect or drops requests

Expand

Symptoms: Browser relay sessions fail to start, or browser-driven steps time out.

Cause: Relay settings are disabled, the browser endpoint is unreachable, or the host cannot resolve the relay target.

Solution

Command

openclaw config get browserRelay
curl -I http://127.0.0.1:3000 || true
openclaw gateway restart

Config change

- browserRelay.enabled: false
+ browserRelay.enabled: true
+ browserRelay.baseUrl: "http://127.0.0.1:3000"

Why this works: Browser relay depends on a reachable relay service and matching runtime configuration. Restarting the gateway forces the relay settings to reload.

Verification: Run one browser-dependent skill or workflow and confirm it completes without relay timeout errors.

Screenshot:

Browser relay cannot connect or drops requests screenshot

Runtime & Stability

After launch

Data not persisted after restart

Expand

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:

Data not persisted after restart screenshot

Memory pressure / OOM

Expand

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:

Memory pressure / OOM screenshot

Related OpenClaw guides