Troubleshooting Hub
Find solutions to common OpenClaw issues and get back up and running quickly
EACCES, unauthorized, EADDRINUSE) and then narrow down using filters.Prefer browsing? See all solutions .
Browse Solutions by Category
Install & Setup
Node version, PATH, permission errors, CLI not found
Channels
Telegram/WhatsApp/Discord/Slack message and connection issues
Configuration
JSON5/schema validation, wrong types, missing keys
Models & Auth
βAll models failedβ, billing/rate limits, OAuth/setup-token issues
AI API Compatibility
OpenAI-compatible endpoints, local models, tools, reasoning, and streaming mismatches
AI API Compatibility Fast Path
If your issue sounds like "curl works but OpenClaw fails", "probe works but the agent still errors", or "my local OpenAI-compatible backend only breaks on tools", start with this topic cluster instead of generic auth troubleshooting.
Pick the right integration path before you debug the wrong layer.
Separate endpoint reachability from runtime payload compatibility.
Most common failure pattern after plain chat already works.
Use this when local chat works but agent loops break on later turns.
Most Common Issues
Error: Node.js version mismatch
OpenClaw recommends Node.js 24 and supports Node.js 22.19+. Check your version with node --version
Telegram: Bot API requests failing
Common causes include outbound network/DNS issues to Telegram, or missing token configuration.
View solution βInvalid JSON syntax in configuration
JSON parsing errors are often caused by missing commas, trailing commas, or unquoted strings.
View solution βPermission denied error during installation
This usually occurs when trying to install globally without proper permissions. Use sudo or configure npm prefix.
View solution βControl UI: disconnected (1008): pairing required
First-time remote connections require one-time device approval. Approve the device, then reload.
View solution βFeatured Solutions
Gateway won't start: config validation failed / JSON5 parse error
Fix gateway boot failures caused by invalid JSON5 syntax or schema validation errors (unknown keys, wrong types) using openclaw doctor and config tools.
Control UI error: missing scope: operator.read (LAN/IP access)
Work around a regression where the Control UI works on localhost but fails via LAN/IP with 'missing scope: operator.read'.
Cron: announce delivery sends a summary instead of the full output (Telegram topics / chat channels)
If an isolated cron job used to deliver the full output but now sends a summary (or leaks extra text like thinking/reasoning), disable announce delivery and send a clean final message explicitly.
/model says 'model not allowed'
Fix 'model not allowed' by updating or clearing the agents.defaults.models allowlist, then selecting an allowed model.
OpenClaw OOM crash loop after a Node/runtime mismatch
Fix OpenClaw gateway or openclaw-message OOM crash loops by updating to stable OpenClaw 2026.6.1, using Node 24 or Node 22.19+, and verifying your service actually uses the expected Node binary.
Node.js version mismatch (OpenClaw recommends Node 24)
Fix install/runtime failures caused by old Node.js versions by upgrading to Node 24 or Node 22.19+ and ensuring your shell/service uses the same Node.
npm global install: OpenClaw breaks after upgrade/downgrade (missing dist chunk)
Fix OpenClaw global installs that break after a version swap (upgrade/downgrade) with errors like 'Cannot find module ... dist/...chunk...' by doing a clean reinstall and refreshing the gateway service install.
Onboarding skips Model/Auth setup (agent unresponsive after install)
Fix a broken onboarding flow where OpenClaw defaults to a model without credentials, causing the agent to hang, by configuring provider auth manually and rerunning current configuration.
Still Need Help?
Can't find a solution? Our community is here to help you troubleshoot your issue