OpenClaw Common Errors and How to Fix Them

Here are the most common OpenClaw errors and their solutions.

'openclaw: command not found' The binary isn't in your PATH. Either the installation didn't complete, or your shell config needs updating. Fix: run the install script again, or add ~/.openclaw/bin to your PATH manually.

'Gateway failed to start: port in use' Another process is using port 18789. Find it with lsof -i :18789 and either stop that process or change OpenClaw's port in the config.

'API key invalid or expired' Your model provider rejected the API key. Check: is the key correct? Does the provider account have active billing? Has the key been rotated? Fix: update the key with openclaw config set apiKey.

'Skill installation failed' Usually a network issue or incompatible Node.js version. Fix: check internet connectivity, ensure Node.js 22+, and try again. If the skill requires specific dependencies, check its documentation.

'Model timeout' The AI model didn't respond within the timeout period. Common with slower providers (DeepSeek under load, Ollama on weak hardware). Fix: increase timeout in config or switch to a faster model.

'Memory database corrupted' Rare, usually caused by unclean shutdown. Fix: openclaw memory repair rebuilds the database from files.

For any error not listed here, run openclaw doctor — it checks the most common issues automatically and suggests fixes.

# Diagnose issues automatically
openclaw doctor

# Check port usage
lsof -i :18789

# View detailed error logs
openclaw gateway logs --level error