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 requires Node.js 22+ (Node 22 LTS recommended). 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
Control UI: disconnected (1008): pairing required
Fix Control UI disconnects caused by device pairing. Approve the browser/device once, then reconnect (common on remote hosts and Docker).
Feishu/Lark: iOS photo-library videos fail with 502 when OpenClaw downloads them as file type
Fix Feishu/Lark cases where an iOS photo-library video arrives as `file`, OpenClaw downloads it with `type=file`, and longer clips fail with 502. Use a safer send path now or add a bounded `type=media` fallback.
Gateway restart is slow (`remote bin probe timed out` from a stale paired node)
Fix gateway restart/shutdown delays caused by unreachable or co-located paired nodes triggering repeated remote bin probes. Start with a minimal `gateway.nodes.denyCommands` workaround, then verify restart time returns to normal.
Telegram: repeated getUpdates 409 conflict blocks bot replies
Recover a Telegram bot that keeps logging getUpdates 409 Conflict errors by stopping duplicate pollers, restarting cleanly, and proving only one listener still owns the token.
Telegram: network request failed, 7s+ delays, or timeouts due to IPv6/routing
Fix slow or failing Telegram Bot API calls by checking IPv6-first behavior, regional routing problems, and outbound reachability to api.telegram.org.
Cron: jobs don't fire and nextRunAtMs silently advances
Fix cron jobs that skip runs (no execution/logs) while nextRunAtMs advances by upgrading past known scheduler regressions and verifying cron storage + timezone.
Windows: Gateway service fails to start when the user profile path is non-ASCII
Fix cases where `openclaw gateway start` works in the foreground but exits immediately when launched via Scheduled Task because the command path includes non-ASCII characters.
Windows (NTFS/WSL2): MEMORY.md is injected twice (case-insensitive filesystem)
Fix doubled bootstrap token cost when `MEMORY.md` and `memory.md` resolve to the same file on a case-insensitive NTFS workspace mount.
Still Need Help?
Can't find a solution? Our community is here to help you troubleshoot your issue