Help Center
Quick fixes for the most common OpenClaw issues
Solutions based on real problems from our Discord community
Quick Commands
openclaw doctorDiagnose most issues
/newFresh session in chat
openclaw logsView error details
Common Issues
Bot Not Responding — Missing API Key
Your OpenClaw bot connects but never replies. Usually caused by a missing or misconfigured API key.
Telegram Connection Failed — WebSocket Error 1006
Telegram messages fail with WebSocket 1006 errors. Usually an IPv4/IPv6 issue on your VPS.
Gateway Won't Start — Troubleshooting Guide
The OpenClaw gateway crashes on startup or won't run. Port conflicts, disk space, or duplicate services.
Rate Limited — All Models Failed Cooldown
Your bot stops responding with 'all models failed' or provider cooldown errors.
Context Overflow — Prompt Too Large for Model
Long conversations cause 'context overflow' errors. How to fix and prevent it.
Tool Use Error — Unexpected tool_use_id
LLM request rejected with 'unexpected tool_use_id found in tool_result blocks'. Quick fix inside.
Update Stuck on Old Version — NPM Migration
Can't update past an old version? The package was renamed from clawdbot to openclaw.
Browser Not Working — Extension Relay Setup
Browser automation fails with relay errors. Setup guide for local and remote gateways.
Claude OAuth Not Working — 401 Error
Claude OAuth token expired or invalid. How to re-authenticate.
Ollama Local LLM — No Output or Broken Tools
Local models via Ollama show empty responses or can't use tools. Configuration tips.
OpenClaw Installation Guide — All Platforms (Linux, macOS, Unraid)
Complete installation guide covering gateway setup, Ollama integration, systemd services, and troubleshooting common setup errors like ECONNREFUSED and model loading issues.
OpenClaw on Windows — Installation & Common Issues
Step-by-step Windows installation guide covering Node.js setup, WSL2 configuration, LM Studio integration, and troubleshooting Windows-specific issues.
Running OpenClaw in Docker — Setup & Troubleshooting
Complete guide to running OpenClaw in Docker containers, including setup on Synology NAS, fixing permission errors, resolving pairing/1008 errors, and configuring volumes for persistent skills.
OpenClaw Gateway Crashes or Won't Start — Complete Fix Guide
Comprehensive troubleshooting for gateway startup failures, 1006/1008 WebSocket errors, token mismatches, health check failures, and platform-specific issues on Windows, macOS, and Linux.
Setting Up Ollama & Local Models with OpenClaw
Complete guide to configuring Ollama for local LLM inference with OpenClaw, including Docker setup, WSL2 configuration, and troubleshooting common issues like 0/200k tokens and empty responses.
Model Not Responding — No Output or Empty Replies
Troubleshooting guide for when OpenClaw shows "(no output)" or produces empty responses. Covers authentication issues, gateway problems, model configuration, and platform-specific fixes for VPS, WSL2, and Docker.
How to Switch Models & Configure Providers in OpenClaw
Complete guide to switching between AI models (Claude, Gemini, Ollama, DeepSeek, OpenRouter) and configuring providers in OpenClaw. Covers local models, Docker setups, and common configuration issues.
Setting Up API Keys for All Providers — Complete Guide
Complete guide to configuring API keys and authentication for all OpenClaw providers including Anthropic, OpenAI, Google, OpenRouter, and OAuth-based services like Gmail. Covers multi-auth, token refresh issues, and proper config file structure.
Telegram Bot Setup — Complete OpenClaw Guide
Complete guide to setting up, configuring, and troubleshooting your Telegram bot with OpenClaw. Covers pairing codes, authorization errors, token issues, plugin configuration, and streaming setup.
Discord Bot Setup — OpenClaw Integration Guide
Complete guide to setting up Discord as a channel for OpenClaw. Covers bot creation, permissions, authorization errors, slash commands, duplicate messages, per-channel configuration, and credential storage.
Memory & Semantic Search — Setup & Configuration
Complete guide to configuring OpenClaw's memory system, semantic search, embeddings, and fixing common issues like context overflow, memory files not writing, and voice message failures.
Browser Automation — Setup, Extensions & Troubleshooting
Complete guide to setting up OpenClaw browser automation, including Chrome Extension Relay, headless browser mode, VPS configurations, remote gateway setups, and fixing common issues like tabs not found and relay not reachable errors.
Tools, Skills & MCP — Extending OpenClaw
Complete guide to extending OpenClaw with custom skills, configuring search providers, troubleshooting tool errors, and understanding the skill loading system.
Hosting OpenClaw on a VPS — Complete Guide
Step-by-step guide to running OpenClaw on a VPS including setup, optimization, SSH configuration, troubleshooting disconnects, and best practices for Hetzner, DigitalOcean, Contabo, and Google Cloud.
Cron Jobs & Heartbeats — Making OpenClaw Proactive
Fix cron jobs that never fire, messages that don't deliver, and heartbeats that interrupt your agent's work. Complete troubleshooting for proactive automation.
Dashboard & Web UI — Setup & Troubleshooting
Get the OpenClaw web dashboard working, fix connection errors, resolve white-on-white text, and access the UI remotely from VMs or other machines.
Permissions, Sandbox & Security Settings
Configure sandbox isolation, tool permissions, exec security policies, and macOS permission grants for secure OpenClaw operation.
Proxy, SSL & Network Connection Issues
Troubleshoot network connectivity, webhook integrations, Copilot Proxy setup, API credential issues, and connection timeouts.
OpenClaw Configuration — Complete Reference
Master OpenClaw configuration: multi-agent setup, browser profiles, CDP ports, Tailscale modes, MCP integrations, and troubleshooting config validation errors.
OpenClaw on Mac — Setup & Common Issues
Fix Mac-specific OpenClaw issues: sleep/wake problems, PTY file descriptor leaks (spawn EBADF), EMFILE watcher loops, permission configuration, and multi-tenant isolation on Mac mini.
Using DeepSeek, MiniMax, Kimi & Alternative Models with OpenClaw
Configure alternative model providers like DeepSeek, MiniMax, Kimi K2.5, and Groq with OpenClaw. Troubleshoot 'no output' issues and learn direct API vs OpenRouter setup.
Antigravity OAuth Errors — Fix 'Version No Longer Supported' and Authentication Issues
Fix the 'This version of Antigravity is no longer supported' error and other Google Antigravity OAuth issues. Includes user-agent patch fix and multi-account setup.
Managing Token Usage & Costs in OpenClaw
Burning through millions of tokens unexpectedly? Learn how to diagnose runaway token consumption, configure context limits, and avoid bill shock with Gemini and other models.
Rate Limits & Quota Management — Avoid Downtime
Getting HTTP 429 rate limit errors? Learn how to configure model fallbacks, rotate API keys, understand cooldown periods, and keep your agent running when quotas are exhausted.
iMessage & SMS Integration Guide
Complete guide to setting up iMessage integration with OpenClaw, including Full Disk Access permissions, fixing duplicate messages, and troubleshooting common issues.
Email & Gmail Integration — Setup Guide
How to integrate Gmail and email with OpenClaw using the Gmail Pub/Sub system, gogcli tool, and custom skills. Includes troubleshooting for drafts not appearing and script execution issues.
Voice & Text-to-Speech Setup
Configure TTS providers like ElevenLabs, fix MEDIA: path output issues, and set up hands-free voice-only workflows for mobile or car use.
Multi-Agent Architecture — Fleet Setup & Best Practices
Configure multiple OpenClaw agents running 24/7, set up persistent memory, handle OAuth token issues, use multiple models, and fix exec session timeouts.
Reduce API Costs — Save Money on AI Usage
Slash your OpenClaw API bill by 50-80%. Learn model selection, caching, prompt optimization, and smart fallback strategies.
Still stuck?
Join our Discord community for real-time help from the team and other users.
Join DiscordLooking for detailed documentation? Check out the full docs.