Gateway Issues

The OpenClaw gateway daemon is the background service that manages connections, routing, and agent lifecycle. When the gateway fails to start, disconnects, or reports errors, your CLI and channels cannot communicate with the agent. This guide covers the most common gateway problems and how to fix them.

Run openclaw doctor first. The doctor command checks gateway health, config, and dependencies. Use it before digging into specific errors.

Quick Diagnostic Commands

Use these commands to diagnose gateway-related issues:

# Recommended first step: full health check
openclaw doctor

# Apply automatic fixes where possible (use with care)
openclaw doctor --fix

# Check gateway and service status
openclaw status
openclaw status --all

# Test gateway connectivity (RPC probe)
openclaw gateway probe

# View live logs
openclaw logs --follow
openclaw logs --tail 50

# Validate configuration
openclaw config validate

See Quick diagnostics for a full runthrough of diagnostic steps.

Common Gateway Issues & Solutions

Below are the gateway errors most often reported, with causes and fixes aligned to the OpenClaw troubleshooting structure.

Symptom	Likely Cause	Solution
Gateway won't start	Port in use, missing config, or bad bind address	Check port with `lsof -i :3000` (or your configured port). Ensure gateway binds to `localhost` only; see Security best practices. Restart after fixing config.
Gateway already running (PID lock)	Another instance or stale PID file	Run `openclaw status`. If you see "already running," stop the service cleanly with `openclaw stop`. If needed, remove the PID file in the OpenClaw data directory and restart.
Gateway unauthorized / can't connect	Token mismatch or wrong gateway URL	CLI and gateway must share the same token (in config or env). Verify `OPENCLAW_GATEWAY_URL` and token. Restart both gateway and CLI after changing credentials.
Gateway keeps reconnecting	Network instability, firewall, or gateway crashes	Check `openclaw logs --follow` for disconnect reasons. Ensure firewall allows local traffic; if remote, use SSH tunnel or VPN (e.g. Tailscale). See network isolation.
RPC probe failures	Gateway not reachable or wrong endpoint	Run `openclaw gateway probe`. Confirm gateway is running and URL/port match. Fix config or environment and run `openclaw doctor` again.
Token mismatch errors	Different tokens in config vs. environment or across restarts	Use a single source of truth for the gateway token (e.g. env var). Restart gateway and CLI; clear any cached credentials. Avoid mixing config file and env.
Port already in use	Another process on gateway port (e.g. 3000)	`lsof -i :3000` (Linux/macOS) or `netstat -ano` (Windows). Stop the conflicting process or change the gateway port in config.
Agent not responding	Gateway up but API key or model config invalid	Verify API key and model provider in config; see Model & API errors. Ensure gateway can reach the LLM provider.
Memory errors / gateway crashes	Insufficient RAM or memory leak	Ensure 4GB+ RAM for typical setups. Check `openclaw logs` for OOM. Optimize config or scale up; see Performance problems.
Connection timeout	Network or firewall blocking gateway	Confirm firewall rules and that the gateway is bound to the expected interface. For remote access, use SSH tunnel or VPN-do not expose the gateway port publicly.

Step-by-Step Debugging

Run openclaw doctor - Review output for gateway, config, and path issues. Use openclaw doctor --fix only when you understand the suggested fixes.
Check service status: openclaw status and openclaw status --all.
Probe the gateway: openclaw gateway probe to test RPC connectivity.
Review logs: openclaw logs --follow while reproducing the issue.
Validate config: openclaw config validate.
Restart cleanly: openclaw stop then openclaw start (or your service manager).

When to Use `openclaw doctor --fix`

openclaw doctor --fix can automatically repair some issues (e.g. permissions, missing directories). Use it when:

Doctor reports fixable items and you're comfortable with the changes.
You're in a dev or test environment and want a quick repair.

Avoid running --fix blindly in production; review what it will change first. When in doubt, follow the manual steps suggested in the doctor output.

Getting Help

If the gateway still fails after these steps:

Run quick diagnostics and note the output.
Ask in the Discord community - include OS, OpenClaw version, and redacted logs/config.
Search or open a GitHub issue - attach logs and error messages with secrets redacted.
Always include: openclaw doctor output, relevant log lines, and config (with API keys and tokens removed).

For a full overview of support options, see the Troubleshooting guide. After fixing the gateway, ensure installation and security setup are correct.