OpenClaw Not Working? A Complete Troubleshooting Guide for Install, Runtime, and Authentication Errors

Hey, guys. Anna here. This week, I had planned for OpenClaw to quietly carry out a small personal task and then resume my regular work. However, it threw me a vague error message, a complete blankness, and that familiar sense of exhaustion: Should I spend time trying to fix this tonight? I first made a cup of tea, took a deep breath, and then, as usual, conducted a basic troubleshooting - to figure out exactly what went wrong. The process wasn't exciting at all, but it got me moving again, and that was all that mattered.

Start Here: Find Your Symptom

This page is the full troubleshooting reference, but if you already know what you're seeing, jump straight to the dedicated guide for it. Everything below the table is the detailed walkthrough.

No match, or not sure yet? Run the 2-minute triage below first — it narrows things down fast.

2-minute triage guide

Identify where it's failing

I start with a simple question: is this an install problem, a runtime problem, or an account/auth problem? You can tell a lot from the first error or two.

• If your shell says "command not found" or Windows says "not recognized as an internal or external command," it's probably an installation or PATH issue. → Full fixes in the OpenClaw install guide.
• If Openclaw starts and then crashes, hangs, or logs stack traces, that's runtime, version mismatches, missing env vars, memory, or a bad config. → If it's the gateway itself, see the Gateway explainer & restart commands; if the dashboard is blank, see the dashboard-not-loading fixes.
• If it opens, asks you to sign in, shows QR codes, or mentions tokens and then loops or fails, that's authentication. → For messaging channels, see WhatsApp setup or Telegram setup.

I don't try to fix everything at once. Picking a lane saves a surprising amount of mental energy.

Copy-paste diagnostics commands

I keep a small scratchpad and run a few quick checks. No thinking, just copy–paste.

• Environment basics:
• macOS/Linux: uname -a: Windows: systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
• Node.js (if Openclaw uses it): node -v and npm -v or pnpm -v/yarn -v
• Python (if referenced): python3 --version or py --version
• PATH check:
• macOS/Linux: echo $PATH: Windows PowerShell: $Env:Path -split ':'
• See if the Openclaw install directory appears.
• Permissions:
• macOS/Linux: which openclaw or command -v openclaw
• Windows: where openclaw
• Logs (if there's a log file or verbose mode): The official OpenClaw troubleshooting docs recommend running openclaw logs --follow or openclaw status --all to get a complete diagnostic report. Try running with --verbose or --debug if supported, or check the most recent log in the tool's folder.

If any of these commands error out or return nothing, that's a clue, not a failure.

Quick symptom checklist

• Did it ever work on this machine? If yes, what changed since then (updates, new shell, antivirus, VPN)?
• Are you in the right directory when running it (some CLIs expect project context)?
• Are you on Wi‑Fi that blocks certain ports (work networks can be strict)?
• Did you copy an example config but forget to rename .env.example to .env?
• If you installed moments ago, did you open a new terminal so PATH updates apply?

Two minutes here usually narrows the problem from "everything" to one or two suspects. It's a relief, even if nothing's fixed yet.

Installation failures

Working through a fresh install or reinstall? The OpenClaw install guide has the clean, verified setup for macOS, Windows (WSL2), and Linux. Containerizing instead? See the Docker setup guide; deploying to a server? See the VPS deployment guide.

PATH configuration issues

If your terminal says it doesn't recognize openclaw, that's almost always PATH. I've seen this after a global install that quietly placed binaries in a directory my shell didn't know about.

What helped:

• Find the binary: which openclaw (macOS/Linux) or where openclaw (Windows). If nothing returns, the binary either didn't install or lives somewhere unexpected.
• If you installed via a package manager, check where it puts executables. For Node-based installs, npm bin -g shows the global bin path: make sure it's on PATH.
• On macOS/Linux, add the bin path to ~/.bashrc, ~/.zshrc, or the shell profile you actually use. Then open a fresh terminal.

If you're in a managed corporate environment, PATH might be locked down. In that case, a local (per-project) install plus an npx openclaw-style run can sidestep global PATH entirely.

Permission denied errors

The quiet villain: permissions that look fine until they don't. I hit this once when the binary had no execute flag after a manual download.

What helped:

• macOS/Linux: ls -l $(which openclaw), if it exists but isn't executable, chmod +x can fix it.
• Avoid sudo installing via npm or similar unless the docs explicitly say so, it tends to create future permission tangles.
• On macOS Gatekeeper: if you downloaded a binary, the OS may block it. Right‑click → Open once, or allow in System Settings → Privacy & Security.
• Windows: run PowerShell as Administrator only if necessary: otherwise, try installing in a user-writable path.

Missing system dependencies

Some tools assume you have a runtime (Node, Python, Git) or system libraries. The OpenClaw npm package requires Node.js for installation. If Openclaw mentions a module it can't load or a compiler toolchain, that's your cue.

What helped:

• Verify runtimes: node -v, python3 --version, git --version.
• If Node is required, prefer an LTS version manager like nvm or fnm. LTS is boring in the best way.
• On Linux, watch for build-essentials (build-essential on Debian/Ubuntu) when native modules are involved.
• If a readme lists dependencies, install those first, in order. It saves odd, cascading errors later.

Operating system specific problems

• macOS: Shell profile confusion is real. If you use zsh but edit .bashrc, nothing changes. Also, Rosetta vs ARM binaries can misbehave on Apple Silicon, ensure you're installing the correct architecture.
• Windows: Long paths and antivirus can block installs. Try a shorter path (e.g., C:\Tools\Openclaw) and temporarily pause real‑time scanning to test.
• Linux: Distro differences matter. Package names and service managers vary: reading the section for your distro in the docs, not just "Linux", is faster than guessing.

When installs feel cursed, a clean uninstall and reinstall with a version manager usually resets the board without drama. If you'd rather run it in a container to avoid host-environment quirks entirely, the Docker setup guide covers ports, volumes, and the safe bind configuration.

Runtime failures

If the gateway runs but the dashboard is blank, refuses to connect, or fails the WebSocket handshake, that's a networking/proxy issue covered in full by the dashboard-not-loading fixes.

Node.js version mismatch

If Openclaw runs on Node and you're seeing syntax errors or dependency complaints, it's often a version gap. I've had perfectly fine code implode on Node 18 but behave on Node 20, and vice versa.

What helped:

• Check the project's supported Node versions (release notes or readme). If unclear, try LTS first.
• Switch quickly with nvm use --lts (or your manager of choice). Then reinstall dependencies to avoid ABI mismatches.
• Delete node_modules and lock files before a fresh install if you've hopped versions a few times.

Process crashes or won't start

A process that flashes and dies usually leaves a hint somewhere. The OpenClaw error troubleshooting center provides detailed fixes for every common error type.

• Look for a --verbose or --debug flag. If logs exist, they're your map.
• Confirm required environment variables are set: printenv | sort (macOS/Linux) or Get-ChildItem Env: (PowerShell). Redacted is fine: presence matters.
• Port conflicts: if a local server is involved, another app might already have that port. On macOS/Linux, lsof -i :PORT: on Windows, netstat -ano | findstr :PORT.
• Config paths: absolute vs relative paths can break when you launch from a different directory or via a shortcut.

If nothing appears in logs, try running it in the foreground (not as a background service) to catch early errors. When it's specifically the gateway that won't stay up — or you're not sure whether the gateway or the agent is the broken piece — the Gateway explainer & restart commands walks through the exact restart sequence for both native and Docker installs.

Out of memory errors

Memory issues don't always mean "your computer is weak." Leaks, large payloads, or recursive jobs can spike usage.

• Watch usage live: macOS Activity Monitor, Windows Task Manager, or top/htop.
• For Node apps, set a higher heap temporarily to test: NODE_OPTIONS=--max-old-space-size=4096 openclaw ... (adjust MB). If that helps, you've found the pressure point, then look for the real cause.
• Reduce batch sizes, limit concurrency, or process smaller files first to see if behavior changes.

Quietly, these tweaks are less about speed and more about avoiding that mental "is it me or the tool?" spiral.

CPU spike issues

When the fan spins up like a tiny jet, I pause. High CPU with no progress often points to loops, heavy parsing, or unnecessary re-renders.

• Sample the process: macOS sample PID, Linux perf/strace, Windows Performance Monitor. Even a crude snapshot can show the hot path.
• Disable watchers or auto-reload features if they exist: recursive directory watching on large folders is a classic footgun.
• Try a smaller input set. If CPU calms down, scale back the workload or chunk it deliberately.

Authentication failures

The classic gateway-token error (disconnected (1008) / "gateway token missing") usually means the dashboard and gateway disagree on the token — the dashboard-not-loading guide covers that auth path step by step.

API token errors

If your Openclaw setup expects an API key (some do, depending on integrations), typos and scope mismatches cause quiet failures.

• Double-check the variable name exactly as the tool expects, OPENCLAW_API_KEY vs OPENCLAW_TOKEN-style differences matter.
• Rotate the token to rule out an expired or revoked key.
• Store it in the right place: .env for local dev, the service's secrets store for deployments, not in code or shell history.

QR code scan problems

Some flows use QR codes for pairing. When this stalls:

• Brightness and glare count. Hold the code steady, avoid screen moiré, zoom out a bit.
• Check for VPNs or firewalls blocking the callback URL. Corporate networks can quietly block the return hop.
• If the code times out, refresh it rather than reusing the old screen, many are single‑use and short‑lived.

Pairing OpenClaw to WhatsApp specifically — QR failures, 24-hour session drops, and the pairing-mode gotcha — is covered in the WhatsApp setup & session guide.

Session reconnection loops

The "sign in → reconnecting → signed out" loop is weirdly common across tools.

• Clear cached credentials for just this app (keychain, credential manager, or the tool's config directory) and try again.
• Sync your system clock. Drifting time can invalidate tokens in a way that looks random.
• Switch networks briefly. If it works on a hotspot, your main network's filtering is the likely culprit.

For a Telegram bot that stays silent or drops updates, the webhook and command-routing fixes are in the Telegram bot setup guide.

OAuth failures

OAuth errors are often about redirect URIs and scopes.

• Ensure the redirect URI in the provider's console matches exactly (scheme, subdomain, trailing slash).
• Ask for the minimum viable scopes first. Too-broad scopes sometimes get blocked by org policy.
• Try a private window to rule out cookie conflicts.

If documentation exists for your specific Openclaw build or fork, follow that, exact variable names and screens vary. When in doubt, searching the project's issues for your error string is faster than guessing.

A small note before I stop: this isn't a manifesto, just a field note. When something like Openclaw won't budge, I don't wrestle it for hours anymore. Two minutes of triage, pick a lane, one fix at a time. I'll keep using that approach, at least until the next mysterious blank screen raises an eyebrow.

If you're tired of juggling terminals, configs, and scattered automations just to keep a small workflow running, you're not alone. We built Macaron to give you one place to run and manage your AI tasks without switching between tools. ➡️ Try Macaron here!