OpenClaw Troubleshooting Guides

Fixes for the most common OpenClaw errors and issues, from install failures to control-panel problems.

• Fixing "API rate limit reached, please try again" in OpenClawThis error means your model provider returned a 429, not that OpenClaw is broken. Learn what the limit means on Anthropic, OpenAI, and Groq, how OpenClaw's cooldown and fallback logic behaves, and how to configure fallbacks so one throttled key never stops your agent.
• Where Is the OpenClaw Config File?OpenClaw keeps its configuration in a single JSON5 file at ~/.openclaw/openclaw.json on every OS. This guide shows how to find the active file, edit it without breaking the gateway, regenerate it from scratch, and which fields not to touch.
• OpenClaw Stuck on Starting (or the Control Panel Will Not Open)When OpenClaw hangs on startup it is almost always a port conflict, a broken config file, the wrong Node version, or a service manager hiding an interactive prompt. When the gateway runs but the control panel will not open, an expired dashboard token or a blocked port is the usual cause. This guide covers every fix with exact commands.
• OpenClaw Gateway "Maximum Call Stack Size Exceeded"? Here Is the FixThe RangeError: Maximum call stack size exceeded crash in the OpenClaw Gateway has three known causes: a config recursion bug around disabled plugins, version-specific schema compilation bugs, and oversized session payloads. This guide walks through each fix with exact commands.
• Stop Your Mac Mini Sleeping So OpenClaw Stays OnlineA sleeping Mac mini takes your OpenClaw agent offline, killing heartbeats, cron jobs, and channel connections. Fix it permanently with pmset, caffeinate, Energy settings, or Amphetamine, and make sure the Gateway comes back on its own after reboots.
• How to Fix "OpenClaw Gateway Connect Failed: Pairing Required"The pairing required error means the OpenClaw Gateway rejected your client because its device identity or token is not approved. Approving the pending device or refreshing the gateway token fixes it in under five minutes.
• OpenClaw: Command Not Found? Fix Your PATH in 5 MinutesThe "openclaw: command not found" error almost always means npm's global bin directory is not on your shell's PATH. This guide gives the exact fix for macOS zsh, Linux bash, and Windows, plus the nvm gotcha that silently removes the command.
• How to Fix the "ollama launch openclaw" Error: unknown integrationThe "unknown integration" error means your Ollama CLI is too old to know about OpenClaw, or an outdated binary is shadowing the new one. Update Ollama past v0.17, fix your PATH, or configure the provider manually and skip the launcher entirely.