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
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.
Feishu: streaming replies show up as duplicate messages
Fix Feishu cases where enabling streaming causes two identical replies to be sent by disabling block streaming (or streaming entirely) and aligning plugin/core versions.
Feishu: TTS voice replies fail in group chats with error 234001
Work around Feishu group-chat voice send failures (234001 Invalid request param) by avoiding auto-TTS in groups and using DM or tagged TTS until the plugin is patched.
Telegram CLI: LocalMediaAccessError for --media paths outside allowed directories
Fix `openclaw message send --channel telegram --media <path>` failures by staging the file under OpenClaw's allowed media roots (such as ~/.openclaw/media) before sending.
Telegram: channel stops working because persisted session state JSON is bad
Recover a Telegram channel that looks mysteriously broken by identifying the bad persisted Telegram session-state JSON, backing it up, resetting only that file, and restarting the gateway.
OpenClaw OOM crash loop: gateway or openclaw-message hits JavaScript heap out of memory (Node v24)
Fix OpenClaw gateway or openclaw-message OOM crash loops caused by Node.js v24 by pinning the runtime to Node v22 (LTS) and verifying your service actually uses the expected Node binary.
Still Need Help?
Can't find a solution? Our community is here to help you troubleshoot your issue