OpenClaw Not Working?
Here's How to Fix It.

OpenClaw wasn't installed globally, or the install completed with errors. This often happens after a Node.js version upgrade that clears global packages.

• Re-install OpenClaw globally: npm install -g openclaw
• Verify it installed: openclaw --version
• If you get a permissions error on macOS/Linux, run: sudo npm install -g openclaw
• On Windows, open your terminal as Administrator before running npm install.

OpenClaw looks for openclaw.json (or config.yaml) in the current working directory. If you run it from the wrong folder, or the file was never created, this error appears.

• Make sure you're in your project folder: cd /path/to/your/project
• Check the file exists: ls openclaw.json (Mac/Linux) or dir openclaw.json (Windows)
• If it doesn't exist, create one — see the openclaw.json guide for a starter template.
• If using config.yaml, make sure it's not misnamed (e.g. config.yml — the extension must be .yaml).

Something else is already listening on port 8080 — either another OpenClaw instance left running, or another app claimed that port.

• Find what's using the port: lsof -i :8080 (Mac/Linux) or netstat -ano | findstr 8080 (Windows)
• Kill the conflicting process, or change OpenClaw's port in your config:
  In openclaw.json: "gateway": { "port": 8181 }
• Make sure you didn't leave a previous OpenClaw session running in another terminal tab.

You're running an older version of Node.js that OpenClaw doesn't support. OpenClaw requires Node.js 18+.

• Check your version: node --version
• If it's below v18, install the latest LTS from nodejs.org or use a version manager like nvm.
• With nvm: nvm install 20 && nvm use 20
• After upgrading, re-run npm install -g openclaw.

The three most common causes: (1) the gateway isn't running, (2) the LLM provider is down or unreachable, or (3) the API key is invalid and requests are silently failing.

• Run openclaw status to check if the agent process is alive.
• Check the logs: openclaw logs --tail 50 — look for connection errors or auth failures.
• Test your API key directly with a curl command to your LLM provider's API.
• Check your LLM provider's status page (e.g. status.anthropic.com) for outages.
• Increase the timeout in your config if you're on a slow connection: "gateway": { "timeout": 60000 }

The agent is repeating the same tool call because it never gets a satisfying result — often caused by a broken tool, a vague task description, or a tool that returns unexpected output.

• Stop the current task immediately: openclaw task stop
• Check which tool is looping in the logs: openclaw logs --tail 100
• If the looping tool is broken, disable it in tools.enabled and re-test.
• Be more specific in your task prompt — vague instructions like "fix all the things" often cause loops.
• Add a max-iteration limit in your config if not already set: "tools": { "maxIterations": 20 }

Likely either a slow local model that doesn't match your hardware, high load on a cloud LLM provider, or a tool call (like web search) taking a very long time.

• Switch to a faster/smaller model for testing: "model": "claude-haiku-4-5-20251001" or "model": "gpt-4o-mini"
• For local models, make sure GPU acceleration is enabled in Ollama or LM Studio.
• Disable tools you don't need — fewer tools = fewer extra calls per response.
• Lower maxTokens in your config to reduce response generation time.

The default memory type is "memory" (in-process RAM), which clears on every restart. If you want persistence between sessions, you need to configure SQLite or Postgres.

• Add this to your openclaw.json to enable persistent SQLite memory:

• Make sure the path is writable and the directory exists.
• If the .db file gets corrupted, delete it and let OpenClaw recreate it on next start.

The most common causes: invalid bot token, the Telegram skill not listed under tools.enabled, or the bot wasn't started with /start in the Telegram app.

• Get a fresh token from @BotFather in Telegram — even a single extra space breaks it.
• Make sure telegram is in your tools.enabled array in your config.
• Open Telegram, find your bot, and send it /start — bots won't respond until this handshake happens.
• Check that your bot token is set correctly: "TELEGRAM_BOT_TOKEN": "$TELEGRAM_BOT_TOKEN" in your env or config.
• Verify the bot is active via the Telegram Bot API: https://api.telegram.org/bot<YOUR_TOKEN>/getMe

WhatsApp's web session expires or gets logged out, especially if you open WhatsApp on your phone while the bot session is active. This is a WhatsApp limitation, not an OpenClaw bug.

• Restart OpenClaw — it will generate a new QR code to re-link your WhatsApp account.
• Scan the QR code with WhatsApp on your phone (Settings → Linked Devices → Link a Device).
• Keep your phone connected to the internet while OpenClaw is running.
• Avoid opening WhatsApp Web in a browser simultaneously — this kicks out the bot session.
• Delete the session cache folder (~/.openclaw/whatsapp-session/) if the QR code loop keeps repeating.

The bot token is valid but the bot hasn't been invited to the server/workspace, or it lacks the correct permissions (scopes).

• Discord: Go to the Discord Developer Portal → OAuth2 → URL Generator. Select the bot scope and required permissions, then use the generated URL to invite the bot to your server.
• Slack: Make sure your Slack app has the chat:write, channels:read, and im:history OAuth scopes. Reinstall the app to your workspace after adding scopes.
• Verify the bot token in your config matches the token in your developer portal — these rotate if you regenerate them.

Gmail and other providers often block standard password logins from apps. You need an app-specific password or an OAuth token — not your regular account password.

• Gmail: Enable 2-Step Verification, then go to Google Account → Security → App Passwords. Generate a password and use that in your OpenClaw email config — not your main Gmail password.
• Make sure IMAP is enabled in Gmail Settings → Forwarding and POP/IMAP → Enable IMAP.
• For Outlook/Hotmail, use an OAuth token or enable "Less Secure App Access" in your Microsoft account settings.
• Double-check the SMTP port: Gmail uses port 587 (TLS) or 465 (SSL).

Skills must be in the correct directory and have a valid SKILL.md file. A missing directory, wrong path in config, or a malformed skill file will cause this error.

• Run openclaw skills list to see what OpenClaw detects. A skill showing as "broken" means the SKILL.md has an issue.
• Check the skills directory exists: ls ~/.openclaw/skills/
• Each skill must be a folder with a SKILL.md file inside: ~/.openclaw/skills/my-skill/SKILL.md
• If you set a custom skills path in config, make sure the folder actually exists at that path.
• Re-install a broken skill: openclaw skills install <skill-name>

The MCP server process failed to launch — usually because npx can't find the package, a required env variable is missing, or the path argument is wrong.

• Test the MCP command directly in your terminal: npx -y @modelcontextprotocol/server-filesystem /your/path — if it fails here, it'll fail in OpenClaw too.
• Make sure the path you're passing exists and OpenClaw has read/write permission to it.
• Check all required environment variables are set (e.g. GITHUB_TOKEN for the GitHub MCP server).
• Update the MCP package: npx -y @modelcontextprotocol/server-filesystem@latest
• Check the MCP guide for server-specific setup requirements.

Web search requires a third-party search API key (Brave, SerpAPI, etc.). The key is either missing, invalid, or you've hit the free-tier monthly limit.

• Check your search API dashboard for usage/quota status.
• Re-confirm the API key in your config matches what's in your provider dashboard — no extra spaces or quotes.
• Brave Search API has a generous free tier (2,000 queries/month) — get a key at api.search.brave.com
• Temporarily disable web search to test if it's blocking other tools: remove "web_search" from tools.enabled.

Voice mode requires both a microphone for input and a TTS provider API key for output. Either the API key is wrong, the mic isn't accessible, or voice mode wasn't enabled in config.

• Make sure "voice": { "enabled": true } is in your config.
• Check your TTS API key is set correctly for your provider (ElevenLabs, OpenAI, etc.).
• Grant microphone permissions to your terminal application in System Settings (macOS) or Settings (Windows).
• Test your mic with another app to rule out a hardware issue.
• See the Voice Mode guide for a full setup walkthrough.

The API key in your config is wrong, expired, or the environment variable it references isn't set. This is the #1 most common error for new OpenClaw users.

• Copy-paste your API key directly from your provider dashboard — never type it by hand.
• If using an env var like $ANTHROPIC_API_KEY, verify it's actually set: echo $ANTHROPIC_API_KEY in your terminal.
• Check for hidden characters: open the config file in a hex editor or run cat -A openclaw.json to spot invisible characters.
• Make sure the key hasn't been revoked — log in to your provider dashboard and check its status.
• Never commit your API key to git. Use environment variables or a .env file that's in your .gitignore.

You've sent more requests than your API tier allows in a given time window. This is common with free-tier API keys or when running many automations at once.

• Wait a minute and try again — rate limits usually reset within 60 seconds.
• Reduce concurrent automations — if you have 10 automations running simultaneously, spread them out.
• Switch to a smaller model (e.g. Claude Haiku, GPT-4o mini) — cheaper models have higher rate limits on most tiers.
• Upgrade your API tier if you need higher throughput — or switch to a local model to avoid rate limits entirely (see the Pricing guide).

Large local models (7B+ parameters) require significant RAM and VRAM. Running a 13B model on a machine with 8GB RAM will cause crashes or extreme slowness.

• Use a smaller quantized model — a 4-bit quantized 7B model uses ~4GB RAM vs. ~14GB for the full version. In Ollama: ollama pull llama3:7b-instruct-q4_0
• Close other heavy applications before running a local model.
• If you have less than 16GB RAM, consider using a cloud API instead (see the Pricing guide — it can be cheaper than you think).
• Enable GPU offloading in Ollama or LM Studio to shift processing to your GPU and free up system RAM.

Two OpenClaw processes tried to write to the same SQLite file at the same time, or a previous run crashed mid-write and left a lock file behind.

• Make sure only one OpenClaw instance is running at a time: openclaw status
• Look for a stale lock file: ls *.db-wal *.db-shm — delete these if OpenClaw isn't running.
• If the database is corrupted (not just locked), back up and delete the .db file — OpenClaw will create a fresh one on next start. You'll lose stored memories but the agent will work again.
• To prevent this, don't run multiple OpenClaw instances pointing at the same database file.