Skip to main content

OpenClaw Troubleshooting — Every Error I Hit and How I Fixed It

I spent 12+ hours setting up OpenClaw on Windows WSL. Along the way, I hit just about every error the system can throw at you.

This page documents every single one — the exact error message, why it happens, and the fix that actually works. Bookmark it. You'll need it.

npm Install Issues​

npm install hangs with spinning cursor​

What you see: After running npm install -g openclaw@latest, the terminal shows a spinning cursor (| / - \) and nothing happens for 10+ minutes.

Why it happens: OpenClaw's dependencies include large AI packages (node-llama-cpp, CUDA libraries) that can be hundreds of MB. The download appears "stuck" but is often still working in the background.

Fix:

  1. Wait 10 more minutes. If the spinner is still moving, it's working.
  2. If truly stuck, press Ctrl+C and retry with verbose output:
npm install -g openclaw@latest --verbose
  1. If in China, use a mirror:
npm install -g openclaw@latest --registry=https://registry.npmmirror.com

npm warn deprecated messages​

What you see:

npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm warn deprecated glob@10.5.0: Old versions of glob are not supported...

Why it happens: Some sub-dependencies use older package versions.

Fix: Ignore these completely. They are warnings, not errors. Your installation will work fine.

CUDA packages downloading (no GPU)​

What you see: npm downloads large CUDA packages (@node-llama-cpp/win-x64-cuda) taking 2-5 minutes each, even though you don't have an NVIDIA GPU.

Why it happens: OpenClaw's dependency node-llama-cpp downloads GPU acceleration libraries by default, regardless of your hardware.

Fix: Let it finish. The packages will install but won't be used. OpenClaw works perfectly with cloud AI models (GPT-5.4, Claude, Gemini) — you don't need local GPU inference unless you specifically want it.

Homebrew Installation Errors​

GnuTLS recv error during Homebrew install​

What you see:

error: RPC failed; curl 56 GnuTLS recv error (-9): Error decoding the received TLS packet.
error: 7621 bytes of body are still expected
fetch-pack: unexpected disconnect while reading sideband packet
fatal: early EOF
fatal: fetch-pack: invalid index-pack output
Failed 5 times doing: /usr/bin/git fetch --quiet --progress --force origin

Why it happens: The standard Homebrew installer downloads from GitHub. In some regions (especially China), the connection to GitHub is unstable, causing TLS handshake failures.

Fix: Use a Chinese mirror instead:

/bin/bash -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

When prompted, select 1 (Tsinghua University) for the fastest speed.

Homebrew install stuck at "Downloading and installing..."​

What you see: Terminal shows:

==> Downloading and installing Homebrew...
remote: Enumerating objects: 323889, done.
remote: Counting objects: 100% (782/782), done.
remote: Compressing objects: 100% (345/345), done.

And then nothing happens for a long time.

Why it happens: The Homebrew git repository is very large (~300MB). On slow connections, the download can appear frozen.

Fix:

  1. Wait 5-10 minutes. If the object count is still changing, it's working.
  2. If no progress after 15 minutes, press Ctrl+C and use the mirror script shown above.

"brew: command not found" after installation​

What you see: Homebrew installed successfully, but running brew --version returns command not found.

Why it happens: Homebrew was installed but its path wasn't added to your shell configuration.

Fix:

(echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

Verify: brew --version should now show a version number.

Skill Installation Failures​

"Install failed: github — brew not installed"​

What you see:

Install failed: github — brew not installed — Homebrew is not installed.
Install it from https://brew.sh or install "gh" manually

Why it happens: The GitHub skill requires the gh CLI tool, which is installed via Homebrew.

Fix: Install Homebrew first (see above), then:

brew install gh

"Install failed: nano-pdf — uv not installed"​

What you see:

Install failed: nano-pdf — uv not installed — install manually:
https://docs.astral.sh/uv/getting-started/installation/

Why it happens: PDF-related skills use Python internally and need uv as the Python package manager.

Fix:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Skills status: Missing requirements: 45​

What you see: Running openclaw doctor shows:

Skills status
  Eligible: 10
  Missing requirements: 45
  Blocked by allowlist: 0

Why it happens: Most skills depend on system packages that aren't installed yet.

Fix: Install core packages in one go:

brew install gh uv poppler ffmpeg imagemagick coreutils

Then let OpenClaw fix the rest:

openclaw doctor --fix

Your Eligible count should increase. Don't worry if it doesn't reach 55 — you don't need all skills to use OpenClaw effectively. 16+ eligible skills is plenty for daily use.

Gateway and Service Issues​

"Gateway not running"​

What you see: openclaw doctor reports:

Gateway not running.

Fix: Start the gateway service:

systemctl --user start openclaw-gateway.service
systemctl --user enable openclaw-gateway.service

"Gateway service not installed"​

What you see: openclaw doctor reports the service doesn't exist.

Fix: Run the doctor with fix flag:

openclaw doctor --fix

This will create and install the systemd service file automatically.

Gateway stops after closing terminal​

What you see: OpenClaw works while your terminal is open, but stops when you close it or log out.

Why it happens: Without systemd lingering, the user session (and all its services) stops when you log out.

Fix:

loginctl enable-linger $USER

This keeps your services running even after logout.

Feishu / Lark Connection Issues​

Bot not responding to messages​

Checklist:

  1. Is the gateway running?
systemctl --user status openclaw-gateway.service
  1. Did you publish the app version? In Feishu developer console → Version Management & Publishing → create and approve a version. The app won't work until published.
  2. Is the bot in the group? Add the bot to your target group.
  3. Is the group whitelisted? If you chose Allowlist mode, check that the group's chat_id is in your config.
  4. Is WebSocket enabled? In Feishu developer console → Event Subscriptions → enable "Receive events via WebSocket."

Finding your group chat_id​

Problem: The onboard wizard asks for chat_id but you don't know it.

Fix: Enter a placeholder (like oc_test), complete the wizard, then:

  1. Add the bot to your target group
  2. Send any message in the group
  3. Check OpenClaw logs for:
[Feishu] Ignoring message from unauthorized group: oc_xxxxx
  1. Copy that oc_xxxxx ID into your config file

Duplicate Feishu plugin warning​

What you see:

Config warnings: plugin feishu: duplicate plugin id detected;
later plugin may be overridden

Why it happens: The onboard process created a duplicate Feishu extension in the extensions directory.

Fix:

mv ~/.openclaw/extensions/feishu ~/feishu_plugin_backup
openclaw doctor

If everything still works (Feishu: ok), you can delete the backup later.

Memory and Model Issues​

"No embedding provider configured"​

What you see: openclaw doctor reports:

Memory search is enabled but no embedding provider is configured.
Semantic recall will not work without an embedding provider.

Why it happens: Memory search needs an embedding model to work, but none is configured.

Fix: If you have a Gemini API key:

openclaw config set agents.defaults.memorySearch.provider google
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Or disable memory search if you don't need it:

openclaw config set agents.defaults.memorySearch.enabled false

"System Node 22+ not found"​

What you see:

Gateway service uses Node from a version manager; it can break after upgrades.
System Node 22+ not found; install it before migrating away from version managers.

Why it happens: You're using NVM to manage Node.js. OpenClaw prefers a system-installed Node for service stability.

Fix: This is a warning, not an error. Your NVM-managed Node (v22+) works fine. You can safely ignore this unless you plan to frequently switch Node versions. Just don't delete your current NVM environment.

OpenClaw Command Issues​

"openclaw: command not found"​

What you see: Running openclaw returns command not found, even though installation succeeded.

Why it happens: The npm global bin path isn't in your shell's PATH.

Fix: Find where openclaw was installed:

which openclaw
# or
find ~/.nvm -name "openclaw" -type f 2>/dev/null

If found, use the full path:

/home/your-username/.nvm/versions/node/v24.x.x/bin/openclaw doctor

Or add the npm global bin to your PATH:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Quick Diagnostic: openclaw doctor​

When in doubt, run this:

openclaw doctor

It checks everything: gateway status, skills, plugins, security, memory, and service configuration. If something's broken, it usually tells you what and suggests how to fix it.

For auto-repair:

openclaw doctor --fix

This is your single most useful troubleshooting command.

Still Stuck?​

If you've tried everything above and still have issues:

  1. Check the official docs: https://docs.openclaw.ai
  2. Search OpenClaw GitHub Issues: https://github.com/steipete/openclaw/issues — someone may have reported the same problem
  3. Ask in OpenClaw Discord — the community is active and helpful
  4. Check our other guides:

All errors and fixes documented here are from real installation experience with OpenClaw 2026.3.8 on Windows 11 WSL2. If you encounter an error not listed here, feel free to reach out — we'll add it to the guide.