All Solutions
Curated, step-by-step fixes (not raw issue threads). Search by error text, then filter by platform, channel, component, or severity.
EACCES, unauthorized, EADDRINUSE) and then narrow down using filters.AI API compatibility topic cluster
For custom providers, local-model servers, and OpenAI-compatible relays, start with the compatibility matrix and symptom pages before assuming the issue is just auth or a bad base URL.
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.
Compaction deadlock: /new and /reset hang — emergency out-of-band session reset
If compaction timeouts deadlock the session lane and even `/new` / `/reset` hang, recover by stopping the gateway and resetting the stuck session from disk (backup first).
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.
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.
macOS LaunchAgent: gateway restart fails (Bootstrap failed: 5 / not loaded)
Fix macOS LaunchAgent installs where `openclaw gateway restart` leaves the gateway not loaded or fails with `Bootstrap failed: 5` by using kickstart for in-place restarts, refreshing the service install, and correcting bare `node` paths.
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.
OpenClaw only chats and won't use tools after update
Fix OpenClaw when it suddenly stops reading files, patching code, or running commands after a recent update. The most common cause is `tools.profile: messaging` or a narrower tool policy.
Telegram: preview streaming causes duplicate-looking replies or NO_REPLY flashes
Fix Telegram preview-stream side effects (duplicates, flicker, or stale previews) by switching `channels.telegram.streaming` away from `partial`, restarting the gateway, and retesting with a clean session.
API works in curl, but OpenClaw still fails
Fix custom or local AI API integrations where direct curl requests succeed, but OpenClaw still errors, returns blank output, or fails during real agent runs.
Custom OpenAI-compatible endpoint rejects tools or tool_choice
Fix custom or proxy AI endpoints that can chat normally but fail once OpenClaw sends tools, tool_choice, parallel_tool_calls, or later tool-result turns.
Custom provider fails only when reasoning is enabled
Fix custom OpenAI-compatible providers that work in basic chat mode but fail once reasoning or thinking controls are enabled.
Local llama.cpp, Ollama, and vLLM tool-calling compatibility
Understand why local-model servers can chat normally but still fail on agent tool calling, tool-result continuation, or OpenAI-compatible multi-turn behavior in OpenClaw.
Ollama configured, but OpenClaw still uses Anthropic (or model discovery keeps failing)
Fix local Ollama setups where gateway logs show Anthropic fallback or repeated Ollama model-discovery failures by pinning provider config, verifying connectivity from the gateway runtime, and separating model selection problems from OpenAI-compatible payload problems.
OpenAI-compatible endpoint rejects stream or store
Fix OpenAI-compatible AI endpoints that fail because they do not support stream, store, or related request fields that OpenClaw may send during real runs.
TUI: '(no output)' or no response after sending a message
If the OpenClaw TUI shows '(no output)' or appears stuck, check connection status, gateway logs, model auth, and whether your provider only supports minimal chat payloads but not real OpenClaw runtime requests.
OpenClaw config becomes invalid after you remove a provider but keep its auth profile
Fix config validation failures caused by orphaned `auth.profiles` entries that still reference a provider removed from `models.providers`.
Control UI: dashboard root returns plain-text 'Not Found' after upgrade (pnpm global install)
Fix cases where the gateway starts normally after an upgrade, but `/` returns plain-text `Not Found` until Control UI assets are copied out of the pnpm global package tree and `gateway.controlUi.root` points at that local copy.
Control UI WebChat: queued user messages are processed but do not appear in the thread
Work around the Control UI limitation where a message sent during an active reply is queued internally but not rendered back into the WebChat conversation.
Cron: isolated jobs fail with 'Field required' on tools.function
Work around isolated cron job failures that reject tool definitions with `Field required` on `tools.function` by temporarily switching the job to the main-session systemEvent path.
OpenClaw: fake-IP / TUN DNS makes public hosts fail SSRF checks
Fix `Blocked: resolves to private/internal/special-use IP address` when a VPN or proxy rewrites public domains to fake-IP ranges like `198.18.x.x` before OpenClaw applies proxying.
Linux/systemd: OpenClaw leaves orphan gateway processes or port 18789 conflicts
Fix Linux hosts where CLI-triggered gateway respawn collides with a systemd-managed OpenClaw gateway, causing orphan processes, EADDRINUSE, or 'another gateway instance is already listening'.
Moltbook: threaded comment replies are not supported
Work around Moltbook comment reply failures that reject `parent_comment_id` by falling back to top-level comments and preserving context with an `@mention`.
Gateway crashes with EBUSY / EACCES / EPERM when `~/.openclaw` is cloud-synced
Fix gateway crashes caused by putting the live OpenClaw state directory inside iCloud Drive, OneDrive, Dropbox, Google Drive, or similar sync tools that briefly lock session/config files while uploading.
Telegram TTS: audio is sent as a file instead of a voice bubble (or gets sent twice)
Fix Telegram TTS replies that arrive as normal audio files instead of voice bubbles, or that produce both an audio attachment and a second narrative message, by checking provider/output format and per-session TTS prefs.
Windows: installer fails and PowerShell closes before you can read the error
Recover from Windows install/bootstrap failures where the one-liner closes PowerShell too quickly by switching to a readable manual install path and validating Node/npm first.
Windows native: node run hangs after printing PATH, or the runtime stays unstable
Stabilize native Windows setups where `openclaw node run` hangs after PATH output, the runtime behaves differently from your shell, or your real requirement is better served by WSL2.
Windows: tools.exec cannot find docker, rg, or gh even though they work in PowerShell
Fix native Windows cases where the Scheduled Task gateway uses a different PATH than your interactive shell, so tools.exec cannot resolve installed CLI tools.
Document uploads (XLS/XLSX) blow out the context window
Work around spreadsheet uploads that explode the context window by avoiding raw XLS/XLSX injection, using smaller intermediary formats such as CSV, and proving the failure with run/log evidence.
Google Gemini CLI OAuth: SSRF blocked because Google resolves to fake-ip/private addresses
Fix `google-gemini-cli` login failures where OAuth domains resolve to special-use addresses by verifying DNS on the gateway host and disabling fake-ip/proxy rewriting for Google OAuth hosts.
macOS: gateway stays down after VPN reconnect
Fix macOS cases where the OpenClaw gateway does not recover after a VPN/network drop by clearing cold-start config blockers and refreshing the launchd service install.
Browser tool: 'browser control service timeout'
Fix browser automation timeouts by confirming the gateway/browser service is alive, reducing the repro, and addressing container/headless dependency and memory issues.
Email OAuth keeps requiring re-auth (tokens disappear or refresh fails)
Fix repeated email OAuth logins by persisting the OpenClaw state directory, eliminating config/runtime drift, and diagnosing refresh failures from logs.
Telegram: configured but '(plugin disabled)' / 'plugin not available'
Fix Telegram showing as configured but disabled by verifying `channels.telegram.enabled`, config precedence, and forcing a gateway restart (plus update/rollback guidance).
OpenClaw: 'Unsafe fallback OpenClaw temp dir' after update (openclaw commands crash)
Fix OpenClaw CLI/gateway crashes when the fallback temp dir under /tmp already exists with insecure permissions or wrong ownership.
Config migration writes ${ENV_VAR} secrets into openclaw.json (upgrade security risk)
If an OpenClaw upgrade/migration rewrites `${ENV_VAR}` references (like `${TELEGRAM_BOT_TOKEN}`) into plaintext values inside `~/.openclaw/openclaw.json`, rotate the affected tokens and move secrets back to env/.env to prevent accidental leaks.
Cron: jobs run but Telegram announce delivery fails (no notification sent)
If isolated cron jobs execute successfully but the Telegram notification never arrives ("cron announce delivery failed"), disable announce and send via the message tool, or switch delivery mode while you capture gateway logs for the failing announce path.
Gateway: 'disconnected (1008): pairing required' after update (scope-upgrade / operator.write)
If new connections (Control UI, sub-agents, cron announce, webchat) are rejected with WebSocket 1008 'pairing required' after an update or reinstall, you may need to approve a device scope-upgrade (often `operator.write`).
Install/Update fails building @discordjs/opus (Raspberry Pi ARM64 and some Linux distros)
If `openclaw update` or `npm i -g openclaw@...` fails while building `@discordjs/opus`, install build tools and retry with the ARM64 CFLAGS workaround (or pin a known-good OpenClaw version).
Install: 'inappropriate ioctl for device' when running install.sh
If `curl ... | sudo bash` prints repeated 'inappropriate ioctl for device' and the OpenClaw installer fails or behaves oddly, rerun the installer with a real TTY (or disable gum), or install via npm directly.
Web search: missing_brave_api_key even though it's configured
If `web_search` fails with `missing_brave_api_key` but you set the key via `openclaw configure --section web`, make sure the running gateway service can see the secret (often via `~/.openclaw/.env`) and restart the gateway.
Gateway: reverse proxy 502 / HTTP/0.9 after update (TLS auto-generate enabled)
Fix reverse proxy breakage after an update enables gateway TLS: disable gateway TLS or update your proxy to talk HTTPS to the gateway.
Windows: Exec tool returns empty output unless pty: true
Work around a Windows regression where non-PTY exec produces no output or side effects by forcing PTY and (optionally) capturing clean output via a temp file.
ClawHub CLI: 'Unauthorized' even with a valid token
Work around ClawHub CLI token auth failures by using the www registry URL (and the no-browser login flow).
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'.
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 or downgrading.
Docker: EACCES permission denied writing ~/.openclaw (openclaw.json.*.tmp)
Fix Docker permission errors when the gateway container can't write to the bind-mounted ~/.openclaw directory (common when host UID/GID != 1000).
/model says 'model not allowed'
Fix 'model not allowed' by updating or clearing the agents.defaults.models allowlist, then selecting an allowed model.
Moonshot (Kimi): API works in browser but OpenClaw keeps failing (wrong endpoint)
Fix Moonshot/Kimi model failures by using the correct baseUrl for your region (api.moonshot.ai vs api.moonshot.cn), and ensuring MOONSHOT_API_KEY is set on the gateway host.
Model outputs '[Historical context]' / tool-call JSON instead of a normal reply
Fix chat replies that leak internal tool metadata (e.g. '[Historical context: ... Do not mimic ...]') by switching to a tool-capable model/provider and ensuring function calling is enabled.
Web chat: dragging an image opens it in a new tab (no upload)
Work around OpenClaw web chat drag-and-drop image uploads opening in a new tab by using paste/file picker and keeping images small until the UI fix lands.
Browser tool: URLs with Chinese characters are mis-encoded
Work around a browser tool encoding bug by pre-encoding non-ASCII query parameters (UTF-8) before calling the browser tool.
Control UI assets missing
Fix 'Control UI assets not found' by building UI assets (pnpm ui:build) or running openclaw doctor UI repair when sources are present.
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).
Control UI: disconnected (1008): device identity required (HTTP / insecure context)
Fix Control UI failures caused by opening the dashboard over plain HTTP on a remote host. Use HTTPS (recommended) or local access; optionally allow insecure auth.
Control UI shows 'unauthorized' / keeps reconnecting
Fix OpenClaw dashboard/control UI auth errors (unauthorized, 1008, reconnect loop) by aligning gateway token/password and reachability.
Discord: bot is online but doesn't reply in server channels
Fix Discord guild non-responses by checking channel permissions, invite status, mention/allowlist rules, and Message Content Intent.
Discord: 'Failed to resolve Discord application id'
Fix Discord startup failures by verifying the bot token and ensuring the gateway host can reach discord.com API endpoints (common in restricted networks).
Discord: 'Used disallowed intents' / bot connects but doesn't respond
Fix Discord bots that connect but don't receive messages by enabling privileged intents (Message Content, Server Members) and reinstalling/restarting.
Docker: 'This version of Antigravity is no longer supported' (update required)
When Antigravity rejects requests with an update-required message, upgrade OpenClaw (or rebuild your Docker image) and re-authenticate.
Docker: docker-setup.sh or image build fails
Fix common Docker onboarding/build failures by rebuilding with correct deps, adding apt packages, checking Docker Desktop file sharing, and reading compose logs.
Gateway: CLI/UI is probing the wrong machine (local vs remote mode mismatch)
Fix confusing 'gateway unreachable' states by aligning gateway.mode, gateway.remote.url, profiles/state dirs, and the URL you probe.
Gateway fails to start: EADDRINUSE / another gateway instance is already listening
Fix OpenClaw gateway port conflicts (EADDRINUSE) by stopping the other process or choosing a new gateway port/profile.
Gateway won't start: 'refusing to bind ... without auth'
Fix gateway startup failures when binding to LAN/tailnet without token/password auth configured.
Gateway: service says running but the CLI/UI can't connect (probe fails)
Fix 'running but unreachable' gateway states by checking you're probing the right URL, confirming the port is listening, and aligning auth/bind settings.
Installer fails: 'spawn git ENOENT' (Git missing)
Fix OpenClaw install/update failures caused by missing Git (common on fresh Windows/Linux machines).
Linux: gateway doesn't stay running (systemd service not installed)
If the gateway only runs in the foreground or stops after you close SSH, install/repair the systemd service and enable user lingering.
Model/auth failures: rate limit, billing, or 'all models failed'
Debug OpenClaw model failures by checking provider auth status, probing profiles, switching models/fallbacks, and verifying provider/model refs.
Node.js version mismatch (OpenClaw requires Node 22+)
Fix install/runtime failures caused by old Node.js versions by upgrading to Node 22 LTS and ensuring your shell/service uses the same Node.
npm install -g fails with EACCES / permission denied
Fix global install permission errors on Linux/macOS by switching npm's global prefix to a user-writable directory (avoid sudo).
openclaw: command not found
Fix PATH issues that cause the OpenClaw CLI to be missing after install (wrong shell, npm prefix not on PATH, multiple Node installs).
OAuth token refresh failed (Anthropic Claude subscription)
Fix expired Anthropic subscription auth by switching to a Claude Code setup-token and pasting it on the gateway host.
Signal: signal-cli not found / daemon won't start
Fix Signal channel startup by installing signal-cli + Java, setting cliPath, and increasing startup timeout or using an external daemon (httpUrl).
Signal: group sends fail ('Group not found') due to case-sensitive group IDs
Fix Signal group targeting failures by preserving the exact group ID casing and upgrading if your version lowercases base64 IDs.
Telegram: voice/audio-only messages don't trigger a response
Fix Telegram voice notes that are ignored by enabling inbound audio transcription (tools.media.audio) and ensuring media limits allow downloading/transcribing.
Telegram: bot shows connected but receives no messages
Fix Telegram bots that start successfully but don't receive updates by checking privacy mode, webhook/polling conflicts, and network reachability.
Slack: socket mode connection/auth fails (xapp/xoxb tokens)
Fix Slack socket mode issues by validating xapp/xoxb tokens, enabling socket mode, and reinstalling the app with correct scopes/events.
Telegram: bot is in a group but never responds
Fix Telegram group response issues caused by allowlist/groups config, requireMention, or Telegram privacy mode/admin permissions.
Slack: bot doesn't respond in channels (but DMs work)
Fix Slack channel non-responses by inviting the app to the channel, checking mention/allowlist rules, and verifying events/scopes.
Telegram: network request failed (sendMessage/sendChatAction) due to IPv6/DNS
Fix Telegram API failures by addressing IPv6-first DNS on hosts without IPv6 egress, or by fixing outbound DNS/HTTPS reachability to api.telegram.org.
Telegram: 'setMyCommands failed' / Bot API requests fail
Fix Telegram Bot API failures caused by outbound HTTPS/DNS/IPv6 issues to api.telegram.org (common on restricted VPS or proxies).
Telegram: voice .ogg turns into garbage <file> block in history
Mitigate Telegram voice note history corruption by ensuring audio transcription runs (skipping file blocks for audio) and tightening file MIME allowlists.
Venice AI: models unavailable or requests make no API calls
Fix Venice provider issues by checking VENICE_API_KEY, network reachability to api.venice.ai, model refs, and credits/billing.
WhatsApp: 401 'No cookie auth credentials found' / bot replies fail
Fix WhatsApp failures caused by missing/expired WhatsApp Web credentials by re-linking the account and ensuring the gateway owns the session files.
WhatsApp: channels login fails (408 Request Time-out / WebSocket Error)
Fix WhatsApp QR login failures caused by restricted networks, proxies without WebSocket support, or running the login on the wrong machine.
WhatsApp: 'No active WhatsApp Web listener' when sending messages
Fix outbound WhatsApp send failures by ensuring the gateway process is running and owns the WhatsApp Web socket (restart, re-link, and check runtime).
WhatsApp: using your personal number and the bot won't reply
If you're running OpenClaw on your personal WhatsApp number, enable self-chat mode and test using 'Message yourself' to avoid loop protection and policy blocks.
Windows: 'openclaw' is not recognized after install
Fix Windows PATH issues after installing OpenClaw globally (npm prefix not on PATH, terminal not restarted, or multiple Node installs).
Windows (WSL2): gateway service install fails (systemd not enabled)
Fix WSL2 gateway daemon install issues by enabling systemd in /etc/wsl.conf, shutting down WSL, and retrying openclaw gateway install.