Diagnose Any OpenClaw Error

The agent is not running, is on a different port, or Node.js v18+ is preferring IPv6 over IPv4. Try using 127.0.0.1 instead of localhost.

Your config file has invalid JSON — common culprits are trailing commas, unescaped backslashes in Windows paths (use \\), single quotes, or comments (// not allowed in JSON).

OpenClaw can't find the configuration file (clawhub.json) or the .openclaw directory. You need to initialize the config first.

Windows backslashes must be double-escaped in JSON (C:\\Users\\name). Single backslashes create invalid escape sequences.

The OpenClaw postinstall script crashed during npm install. Error code 3221225477 (0xC0000005) is a Windows access violation — often caused by a corrupted Node.js installation, incompatible Node version, or antivirus interference.

The node_modules folder is locked by a running Gateway process or an editor. Stop the Gateway first.

Config or credential files are readable/writable by other Windows users. This is a security risk.

On Windows, the gateway starts as a regular console process rather than a background service, so it opens a window and cannot be stopped via 'gateway stop'.

Node.js on Windows cannot spawn a process because the executable path contains invalid characters, spaces, or the executable is not found. Often occurs with OpenClaw gateway or tool execution.

The OpenClaw postinstall script (which sets up the gateway binary) failed on Windows. Common causes: Node.js version mismatch, missing Visual C++ redistributables, or running without admin privileges.

Windows PowerShell blocks .ps1 scripts by default. Use npm.cmd instead or change the execution policy.

Git is not installed or not in your system PATH.

The OpenClaw package files are missing or corrupted. Usually caused by an interrupted npm install, EBUSY lock during update, or a module path mismatch after a version change.

npm global install directory doesn't exist or lacks permissions. Incomplete Node.js installation, incorrect PATH, or running without admin privileges.

Your API key is invalid, expired, or has leading/trailing whitespace. Double-check the key in your config.

Your provider account has hit its rate limit or has zero balance. Check your billing dashboard.

Your API key does not have access to the requested model, or the model name is incorrect. For Gemini, check that you're using the correct API version and model ID (e.g., gemini-2.0-flash instead of gemini-1.5-flash).

Circuit breaker state is persisted in state.json. Standard restart/doctor does not clear the unusableProfiles list — the cooldown survives restarts.

OpenClaw sends both 'reasoning' and 'reasoning_effort' parameters simultaneously. Some providers (GLM, certain OpenRouter models) only accept one of them.

Sub-agents in different agentDir directories do not inherit the main agent's auth-profiles.json. Fallback models may also have an insufficient context window (minimum 16000 tokens required).

The agent wrote a model override to its agent-level config directory, which takes priority over openclaw.json. Standard restart does not clear this agent-level override.

Environment variable parsing strips the leading 'g' from GROQ_API_KEY. The gateway reads 'sk_...' instead of 'gsk_...', causing 401 errors.

Google Cloud Code Assist requires account re-verification (free tier exhausted or account status change). Typically occurs after updating Gemini model version.

OpenClaw injects all tool schemas into context at session start (no lazy loading). With 28+ tools, this can consume 130K+ input tokens per cold start.

Your config references macOS host paths (e.g., /Users/...) inside a Linux container. Use Docker volumes instead.

Docker containers have separate network namespaces. Use Docker Compose service names (e.g., ws://browser:3000) instead of localhost.

The base Docker image does not include Chrome/Chromium. Add a separate browser service or install Chromium in your image.

Docker is not installed or not in your PATH. OpenClaw's sandbox mode tries to run agents in Docker containers. Either install Docker or disable sandboxing.

The Docker image name is wrong or the repository is private. The official image is published under a different registry path. Check the OpenClaw docs for the correct image name and tag.

Skills running in sandbox mode (Docker) don't inherit the host's environment variables. Environment variables must be explicitly passed through the sandbox configuration.

Mounted volumes are owned by root, but the container process runs as the 'node' user.

The Gateway process crashed or was killed unexpectedly. Often caused by a zombie process or crash loop.

A previous node.exe process crashed but did not release the port. The new Gateway cannot bind to it.

OpenClaw sends a 'developer' role that your model provider doesn't support. The real API error is '400 unsupported role ROLE_UNSPECIFIED'.

Your model provider does not support the 'developer' role. This is the root cause behind the 'Message ordering conflict' error.

The Gateway is unreachable or crashed. The health probe cannot connect to the WebSocket endpoint. Common causes: Gateway not running, port conflict, or process terminated unexpectedly.

A previous Gateway process left a stale lock file. In Docker/container environments, PID reuse after restart can fool the lock validation into thinking the old instance is still alive.

The exec-approval socket is unresponsive, causing all exec tool calls to hang indefinitely. Often caused by a stuck approval prompt that was never answered.

The OpenClaw gateway auto-start via systemd user services is unavailable. This happens in WSL, Docker containers, and minimal Linux environments where systemd is not running.

OpenClaw is not installed, or the npm global bin directory is not in your PATH.

The gateway requires gateway.mode to be explicitly set. This was introduced to prevent accidental remote exposure. Set gateway.mode=local for local-only use, or gateway.mode=remote for remote access.

Node.js undici HTTP client has a hardcoded 300-second timeout. Long Ollama generations get killed at exactly 5 minutes.

auth-profiles.json uses snake_case 'api_key' field name, but OpenClaw requires camelCase 'apiKey'. Also check that the agentDir path matches.

OpenClaw can't reach the Ollama API at localhost:11434 within the timeout. Either Ollama isn't running, it's on a different port, or a firewall is blocking the connection.

The Gateway was restarted or updated, invalidating the client's cached token. A zombie process may also be holding the old port.

The gateway's auth token (gateway.auth.token) doesn't match the client's token (gateway.remote.token or OPENCLAW_GATEWAY_TOKEN env var), or the token is missing entirely. Common in Docker where the gateway regenerates a random token on each restart.

The client has no device identity (ID + cryptographic keys). This happens when accessing Control UI over HTTP from a non-localhost address (browser blocks crypto.subtle in insecure contexts), or when a CLI node doesn't have identity parameters.

Debug/break-glass authentication settings are still enabled. This bypasses device token security.

The device connecting to the Gateway hasn't been approved. Local connections are auto-approved, but Docker containers (due to NAT), LAN clients, and remote nodes require explicit device approval.

The gateway is configured to use a web-based login provider (OAuth/SSO), but the provider is not set up or the gateway URL is not accessible. This typically occurs when the control UI is accessed from an insecure context.

The token entered in the Control UI does not match the gateway's current auth token. The token may have been rotated or the config was updated after the token was copied.

The gateway.auth.token config path is empty or does not exist. This means the gateway is running without a token (open access) or the token was never set. Set a token to secure your gateway.

openclaw models auth setup-token generates a static token that is incompatible with Claude Max OAuth flow. The correct path is openclaw models auth login (OAuth flow).

The browser control service can't connect to Chromium via CDP. Common causes: a hung page.evaluate() froze the CDP connection, a stray browser process holds port 18800, or the Gateway isn't running.

Extension WebSocket handshake succeeds but the first frame type mismatches. The relay server may not be running, may be on an unexpected port, or may need reinstalling after a gateway update.

The OpenClaw Chrome extension is installed and the relay is active, but it hasn't been attached to any open browser tab. The extension needs a tab to inject into before browser tools can work.

Network isolation between WSL2 and Windows host preventing CDP/Handshake connection.

Snap-based Chromium prevents non-Snap processes like OpenClaw from managing lock files.

Two or more OpenClaw instances (or another bot using the same token) are polling the Telegram API simultaneously. Telegram only allows one active getUpdates connection per bot token.

The agent is processing (or stuck) but the typing indicator was never cleared. This occurs when the agent enters a tool loop, hits a rate limit, or the response exceeds Telegram's message length limit causing a silent failure.

Exceeded Telegram's 100-command limit due to too many active skills.

Telegram plugin misinterpreting reply text as a local file path due to greedy regex.

Message Content Intent not enabled in Discord Developer Portal, or channel binding failed due to unresolved guildId/channelId at startup time.

Streaming/draft preview mode may cause Telegram to silently reject oversized messages while returning a false success. Invalid supergroup IDs in allowFrom may also interfere.

requireMention: false only applies to regular group chats. Telegram Forum topics (threads) require additional allowThreads configuration.

EventEmitter initialization order bug in the Slack plugin (confirmed on build 2026.2.19-2). Triggers with specific Slack App configuration combinations and causes crash on every startup.

WhatsApp channel configuration schema changed. The 'enabled' field is no longer supported directly under channels.whatsapp.

The feishu plugin is registered more than once in openclaw.json (e.g., under both plugins.entries and as a legacy top-level key). The later entry wins, but this warning indicates a config conflict.

The MSTeams plugin crashes during initialization before processing any messages. Typically caused by misconfigured App ID/Password or missing Microsoft Bot Framework registration.

Slack file uploads fail even with files:write scope granted. The legacy files.upload API was deprecated — OpenClaw must use files.uploadV2 which requires the file to be in a channel the bot is a member of.

Breaking change in Slack Bolt v4.6.0 removed legacy channel events, causing startup failure.

WhatsApp session state became inconsistent after partial link success. Dashboard may show linked while runtime remains disconnected or logged out.

Sub-agent spawn requires operator.write permission, but the current device only has operator.read. The gateway blocks scope upgrades within a session and cannot approve them inline.

Sub-agent spawn uses an embedded vdev token. Editing openclaw.json while the gateway is running triggers a hot reload that invalidates the vdev token, breaking sub-agent connections even though the main session still works.

Sub-agent intermediate state is not automatically reported to the parent agent. If the sub-agent encounters an error or waits for input, it silently hangs with no feedback.

Isolated cron sessions cannot access the original channel context required for announce delivery mode. Regression introduced in a recent version.

Cron job not properly registered (sessionTarget misconfigured, gateway not running), or registration invalidated after a version upgrade.

An embedded sub-agent exceeded its maximum execution time. This can happen when the agent is waiting on a slow tool call, stuck in a loop, or the task is too complex for the configured timeout.

A session lock file (.lock) was not released by a previous process. This can happen after a crash or forced kill. The new session cannot start until the stale lock is removed.

The cron job's announce output has nowhere to deliver. This happens when sessionTarget is set to "isolated" — an isolated session has no persistent channel for cron messages. Switch to "persistent" so cron output has a valid delivery target.

A previous session crashed or was force-killed without releasing its .jsonl.lock file. The next session can't acquire the lock within the 10s timeout, so it aborts.

The built-in memory tool returns empty results when memory files use structured markdown with ## headings. The chunking algorithm splits on heading boundaries, causing short sections to fall below the relevance threshold.

The LaunchAgent plist is missing or unregistered after a version upgrade or manual bootout. Port 18789 being occupied can also cause launchd to silently fail registration.

node-gyp detects macOS version via sw_vers. macOS 26 exceeds the expected version range (≤15.x) in older CLT versions, causing native addon compilation to fail during skill installs.

macOS Tahoe privacy controls (TCC/File Access) blocked OpenClaw or Gateway access to required paths/devices, causing command or startup failures.

Gateway rejects plaintext WebSocket connections from non-loopback addresses to protect credentials and chat data. Use SSH tunnel or configure wss:// with TLS.

The Android OpenClaw client does not send an HTTP Origin header. The gateway requires origin validation by default, and allowedOrigins cannot handle a missing header (only wrong headers).

The gateway rejects WebSocket connections from origins not in the allowedOrigins list. When accessing the Control UI from a different host or port, the browser's Origin header doesn't match.

Node.js prioritizing IPv6 on a network with broken IPv6 routing, causing 32s hangs.