OpenClaw AI Troubleshooting Guide

Solutions for the most common OpenClaw errors, organized by category. Run openclaw doctor first — it diagnoses most issues automatically.

Help
🩺
Run the diagnostic tool first

openclaw doctor checks your installation, API keys, provider connectivity, and Python environment. It catches >70% of common issues automatically.

Installation Errors

pip is not installed or not in PATH. Fix:

# Reinstall pip
python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pip

# On Ubuntu/Debian
sudo apt install python3-pip

# Verify
python3 -m pip --version

Python version is too old (requires ≥ 3.10) or pip needs updating:

python3 --version    # Must be 3.10+
pip install --upgrade pip
pip install openclaw

Never use sudo pip install. Use --user or a virtual environment instead:

# Option 1: User install
pip install --user openclaw

# Option 2: Virtual environment (recommended)
python3 -m venv ~/.openclaw-env
source ~/.openclaw-env/bin/activate
pip install openclaw

API & Authentication Errors

The API key is missing, misspelled, or expired. Check:

# Check current key (masked)
openclaw config get openai.api_key

# Re-set the key
openclaw config set openai.api_key "sk-proj-your-actual-key"

# Or via environment variable
export OPENCLAW_OPENAI_KEY="sk-proj-your-actual-key"
openclaw run "test" --provider openai

Also verify the key is active in your OpenAI dashboard.

You've hit the API rate limit. Solutions:

  • Add retry delay in config: openclaw config set openai.retry_delay 5
  • Switch to a model with higher limits (gpt-4o-mini has high limits)
  • Use --rate-limit 3 to limit to 3 requests/minute
  • Upgrade your OpenAI API tier

You have no credits. Options:

  • Add credits in your OpenAI billing dashboard
  • Switch to Anthropic Claude (separate billing)
  • Use local Ollama models (free, no API key): openclaw run "..." --provider ollama

Runtime & Task Errors

The task is too complex for the default step limit. Increase it:

# Increase max steps for this run
openclaw run "complex task" --max-steps 50

# Set a higher default
openclaw config set agent.max_steps 30

Also consider breaking the task into smaller sub-tasks.

# Increase timeout (default: 300s = 5min)
openclaw run "long task" --timeout 900   # 15 minutes

# Set global timeout
openclaw config set agent.timeout 600

Enable loop detection (on by default) or use more specific task descriptions:

# Enable loop detection (default: on)
openclaw config set agent.loop_detection true

# Use more specific task descriptions
# Bad:  "Fix the code"
# Good: "Fix the TypeError on line 42 of parser.py where 'str' object has no attribute 'split'"

Ollama & Local Model Errors

Ollama server is not running. Start it:

ollama serve

# Or start as background service on Linux
sudo systemctl start ollama
sudo systemctl enable ollama  # Auto-start on boot

# Verify it's running
curl http://localhost:11434/api/tags
# Pull the model first
ollama pull llama3.1:8b

# List all downloaded models
ollama list

# Use the exact model name shown in 'ollama list'
openclaw run "task" --provider ollama --model llama3.1:8b

Getting More Help

If your issue isn't listed above:

  1. Run openclaw doctor --verbose and share the output
  2. Check the GitHub Issues for similar reports
  3. Join the Discord community for real-time help
  4. Open a new issue with logs from openclaw logs --last 50
🔗
See Also

FAQ — Frequently asked questions and quick answers about OpenClaw.

Resources & Community — Get help on Discord, Reddit, and GitHub Issues.

Configuration — Review your config if errors persist after troubleshooting.

← Previous
Integrations