How do I use ClawICU?

Run one command: curl -fsSL https://xagent.icu/r | sh — ClawICU will automatically detect your system, run 20 diagnostic checks, and guide you through repairs.

What issues can ClawICU fix?

ClawICU can auto-repair: plugin SDK incompatibility (api.config.get is not a function), CLI/Gateway version mismatch, config file corruption, missing API credentials, gateway not running, daemon service not installed, port conflicts, disk space issues, and more.

Yes. ClawICU is completely free and open-source under the MIT license. No registration, no tracking, no paid upgrades.

Does ClawICU work via curl | sh?

Yes. ClawICU is fully interactive even when piped through curl | sh. It redirects stdin from /dev/tty so all menus and prompts receive keyboard input from your terminal.

What does ClawICU do before making changes?

ClawICU creates an automatic backup of your ~/.openclaw/ state directory before executing any repair. All repairs are non-destructive where possible (e.g. plugins are renamed to .clawicu-disabled, not deleted).

Issue Encyclopedia

Diagnose & Fix

Comprehensive guides to diagnose and fix common OpenClaw problems

Featured

Tool Unlock Panel

Interactive security config editor — unlock exec, browser, elevated, and sandbox tools without editing config files manually.

25 Issue Guides

Config File Corruption

The config.json5 file contains invalid JSON5 syntax, preventing OpenClaw from starting. This is the most common fatal error and can be caused by manual edits, failed upgrades, or truncated writes.

Plugin Manifest Errors

One or more installed plugins have broken manifests or fail to load, causing runtime errors or preventing OpenClaw from starting. Often occurs after upgrading OpenClaw without updating plugins.

Gateway Not Running

The OpenClaw gateway process has crashed or failed to start on port 18789. This makes all agent channels unreachable even though the rest of the system may be healthy.

Daemon Service Not Installed

The OpenClaw daemon (launchd on macOS, systemd on Linux) is not registered as a system service. This means OpenClaw will not auto-start on boot and background operations may fail.

Missing API Credentials

Provider API keys are missing or empty in the credentials store. OpenClaw cannot connect to any AI provider without valid credentials, making all agent requests fail.

Port 18789 Occupied

Another process is already using port 18789, preventing the OpenClaw gateway from binding. This commonly happens when a previous OpenClaw instance did not shut down cleanly or another service claims the same port.

Network Timeout

OpenClaw agent cannot connect to the gateway due to network timeout or firewall rules blocking communication between components.

Memory Leak

OpenClaw daemon memory usage grows continuously until the process is killed by the OOM killer. This degrades performance over time and causes unexpected crashes.

Disk Space Full

OpenClaw cannot write logs, session data, or state files due to insufficient disk space on the volume hosting ~/.openclaw/.

Permission Denied

OpenClaw cannot access configuration files, state directories, or credentials due to incorrect file permissions or SELinux/AppArmor restrictions.

Database Locked

OpenClaw's SQLite database is locked by another process, preventing writes to session state, plugin data, or configuration cache.

SSL Certificate Expired

The OpenClaw gateway's SSL/TLS certificate has expired, causing HTTPS connections to be rejected by clients and browsers.

API Rate Limit Exceeded

OpenClaw is sending too many requests to AI provider APIs within a short time window, causing 429 responses and failed agent interactions.

Version Mismatch

OpenClaw agent, gateway, and CLI are running different versions, causing protocol incompatibility and communication errors between components.

Startup Failure

OpenClaw daemon fails to start on system boot or after a manual restart. The service enters a failed state with a non-zero exit code.

Pairing Not Approved

A sender or device has requested pairing but is waiting for approval. Messages from unapproved senders are silently ignored until pairing is approved.

Mention Required in Group

OpenClaw ignores messages in group chats unless the bot is @mentioned. This is a security feature to prevent the bot from responding to every message in a group.

Channel Authentication Failed

A channel (Discord, Telegram, Slack, etc.) failed to authenticate or lost authorization. Bot token may be expired or revoked.

Dashboard Cannot Connect

The OpenClaw Control UI (browser dashboard) fails to connect to the gateway. This is usually an auth token mismatch or origin allowlist issue.

Cron Job Not Executing

Scheduled cron jobs are not running at their specified times. The cron scheduler may be disabled or the job configuration is invalid.

Heartbeat Not Sent

The scheduled heartbeat message is not being sent. This can happen during quiet hours, when there are active requests in flight, or when the heartbeat file is empty.

Browser Tool Not Working

The browser automation tool fails to launch Chrome or connect via CDP. This prevents screenshot, web scraping, and browser-based automation.

Exec Command Requires Approval

A shell command that was previously allowed now requires manual approval. This happens when exec security policy tightens or a new session is created.

Plugin SDK Incompatibility

A plugin uses an outdated OpenClaw SDK API (e.g. `api.config.get is not a function`) or the `plugin-sdk` module is missing entirely. This usually appears after upgrading OpenClaw without updating installed plugins, causing the gateway to hang or emit unhandled promise rejections.

Channel Policy Blocking Messages

Discord (or other channel) messages are silently ignored because the channel policy is too restrictive. The most common case: `groupPolicy: 'allowlist'` combined with `requireMention: true` causes direct messages to the bot to never receive a response.