OpenClaw Troubleshooting Guide: Common Issues & Fixes

Running into issues with OpenClaw? This guide covers the most common problems and their solutions.

Installation Issues

Docker won’t start

Symptoms: docker compose up fails or containers crash immediately.

Fix:

# Check Docker is running
systemctl status docker

# Check available disk space (need at least 5GB)
df -h

# Check available memory (need at least 2GB)
free -h

# Pull images fresh
docker compose pull
docker compose up -d

Port already in use

Symptoms: Error: port 8080 already allocated

Fix:

# Find what's using the port
lsof -i :8080

# Change the port in docker-compose.yml
ports:
  - "8081:8080"  # Use a different host port

Model Configuration

“Model not found” errors

Symptoms: Agent responds with model-related errors.

Fix: Check your .env file:

# Ensure your API key is set correctly
OPENAI_API_KEY=sk-...

# Verify the model name matches your provider
CHAT_MODEL=gpt-4

# If using a local model, check the endpoint
API_BASE=http://localhost:11434

Slow responses

Symptoms: Agent takes >30 seconds to respond.

Possible causes:

1. Network latency to model provider — check ping api.openai.com
2. Model overload — try a different model or provider
3. Large context — conversation history may be too long, start a new chat
4. Resource constraints — check CPU/memory usage with docker stats

Memory Issues

Agent “forgets” things

Symptoms: Agent doesn’t recall previous conversations or saved information.

Fix:

# Check if memory volume is mounted correctly
docker inspect openclaw | grep -A5 Mounts

# Ensure the data directory persists
volumes:
  - ./data:/app/data  # This must be a persistent volume

Memory database errors

Symptoms: Errors mentioning FAISS, embeddings, or memory corruption.

Fix:

# Back up existing memory
cp -r data/memory data/memory.bak

# Reset memory index (agent will rebuild)
rm data/memory/index.faiss
# Restart the container
docker compose restart

Performance Optimization

Container using too much memory

# Add resource limits in docker-compose.yml
deploy:
  resources:
    limits:
      memory: 4G
    reservations:
      memory: 1G

Slow file operations

If working with large files:

• Use bind mounts instead of volume mounts for large datasets
• Mount only necessary directories
• Consider tmpfs for temporary file processing

Browser Tool Issues

Browser agent can’t connect

Symptoms: Browser tool returns connection errors.

Fix:

# Check if the browser container is running
docker ps | grep browser

# Restart the browser container
docker compose restart browser

# Check browser logs
docker compose logs browser

Pages not loading

Symptoms: Browser tool times out or shows blank pages.

Possible causes:

1. DNS resolution — Check container DNS settings
2. Network restrictions — Ensure the container can reach the internet
3. Site blocking — Some sites block headless browsers

Network Issues

Can’t access external APIs

# Test connectivity from inside the container
docker exec -it openclaw curl -v https://api.openai.com

# Check DNS resolution
docker exec -it openclaw nslookup api.openai.com

# If using internal networks, ensure external access is allowed

Getting Help

1. Check the logs: docker compose logs -f for real-time output
2. Community forums: OpenClaw community channels
3. GitHub Issues: Search existing issues or file a new one
4. ClawNews: Subscribe to our daily brief for the latest fixes and updates

Found a fix not listed here? Email tips@clawnews.org and we’ll add it.