OpenClaw Troubleshoot Center

Common problems & quick fixes for installing and running OpenClaw.

Start by finding your platform or symptom below. Each issue lists what you see, why it happens, and how to fix it.

Install issues

Install script failed / permission denied

What you see: the install.sh script exits with “permission denied” or similar.

Why it happens: the shell user doesn’t have the right permissions, or there are network / TLS issues when downloading dependencies.

How to fix (general tips):

  • Make sure you’re not behind a proxy / firewall that blocks GitHub or npm.
  • Try again with a clean shell, and check your system clock & certificates.
  • Look at the last 20 lines of the error and search the official docs or GitHub issues.

Windows & WSL2 issues

wsl --install fails or is not recognized

What you see: PowerShell says the command is unknown, or WSL doesn’t install.

Why it happens: your Windows build is too old, or WSL is disabled in Windows Features / BIOS.

How to fix (short version):

  • Check that you’re on Windows 10/11 build 19041+.
  • Enable “Windows Subsystem for Linux” and “Virtual Machine Platform” in Windows Features.
  • Reboot and try wsl --install again.

openclaw command not found inside WSL

What you see: after installing, running openclaw prints “command not found”.

Why it happens: the install didn’t finish correctly, or your PATH wasn’t updated.

How to fix:

  • Re-run the install script in WSL: curl -fsSL https://openclaw.ai/install.sh | bash.
  • Open a new WSL terminal and try again.

Model / API issues

API key errors (Anthropic / OpenAI)

What you see: onboarding or later calls fail with authentication / API key errors.

How to fix:

  • Double-check that you pasted the key correctly (no extra spaces, correct account).
  • Verify that the key is active in the provider dashboard and has enough quota.
  • Check logs for more detailed error messages.

Chat integrations

WhatsApp / Telegram / Discord not connecting

What you see: onboarding links are created, but messages don’t arrive or commands don’t trigger actions.

How to fix (high level):

  • Make sure OpenClaw is actually running (daemon or foreground).
  • If you’re using a public URL (reverse proxy or Cloudflare Tunnel), verify that it’s reachable from the internet.
  • Re-run onboarding for that integration if needed.

This page is meant as a starting point. For deeper debugging, always cross-check with the official documentation and GitHub issues.