OpenClaw Installation & Setup

OpenClaw is designed for easy deployment across all major operating systems. Whether you're on Linux, macOS, or Windows, you can have a fully functional AI assistant running within minutes. This guide covers everything from initial installation to basic configuration and your first messaging platform integration.

System Requirements

Before starting, ensure your system meets these minimum requirements:

• CPU: 2+ cores (4+ recommended for production)
• RAM: 4GB minimum (8GB+ recommended)
• Disk Space: 20GB free (for Docker images and data)
• Docker: Version 20.10+ (get it at docker.com)
• Docker Compose: Version 1.29+ (usually included with Docker)
• Internet Connection: Required for downloading dependencies and AI models

Operating System Notes

• Linux: Any modern distribution (Ubuntu 20.04+, CentOS 8+, Debian 11+)
• macOS: Intel Macs run fine; Apple Silicon (M1/M2) works but may require additional configuration
• Windows: Windows 10 Pro/Enterprise or Windows 11 with WSL 2 (Windows Subsystem for Linux)

Installing Docker (If Not Already Installed)

Docker is the containerization platform that makes OpenClaw deployment consistent across all systems.

On Linux

For Ubuntu/Debian:

sudo apt-get update
sudo apt-get install docker.io docker-compose
sudo usermod -aG docker $USER
newgrp docker

For CentOS/RHEL:

sudo yum install docker docker-compose
sudo usermod -aG docker $USER
newgrp docker

On macOS

1. Visit Docker Desktop for Mac
2. Download the appropriate version (Intel or Apple Silicon)
3. Run the installer and follow the on-screen instructions
4. Once installed, Docker and Docker Compose are available in your terminal

On Windows

1. Visit Docker Desktop for Windows
2. Download Docker Desktop
3. Run the installer with administrator privileges
4. Enable WSL 2 when prompted (this is required)
5. Restart your computer when installation completes
6. Launch Docker Desktop from the Start menu

Step 1: Clone or Download OpenClaw

The easiest way to get started is to clone the official OpenClaw repository.

git clone https://github.com/openclaw-ai/openclaw.git
cd openclaw

If you don't have Git installed, you can download the repository as a ZIP file from GitHub and extract it.

Step 2: Configure Environment Variables

OpenClaw uses environment variables to manage settings. Create a .env file in the openclaw directory with your configuration:

cp .env.example .env
nano .env  # or use your preferred text editor

Edit the .env file with these essential variables:

# OpenClaw Core Configuration
OPENCLAW_VERSION=latest
OPENCLAW_ENVIRONMENT=development
OPENCLAW_HOST=0.0.0.0
OPENCLAW_PORT=8000
OPENCLAW_DEBUG=false

AI Model Configuration
AI_MODEL_PROVIDER=anthropic  # Options: anthropic, openai, ollama
AI_MODEL_NAME=claude-3-haiku
ANTHROPIC_API_KEY=your-api-key-here

Database Configuration
DATABASE_URL=postgresql://openclaw:openclaw@postgres:5432/openclaw
REDIS_URL=redis://redis:6379

Skills Configuration
SKILLS_DIRECTORY=./skills
MARKETPLACE_ENABLED=true

Security
SECRET_KEY=generate-a-random-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1

Getting API Keys

For Anthropic (Claude):

1. Go to console.anthropic.com
2. Create an account or log in
3. Navigate to API Keys section
4. Create a new API key
5. Copy the full key to your .env file

For OpenAI (if using GPT):

1. Visit platform.openai.com
2. Sign in to your OpenAI account
3. Go to API keys
4. Generate a new API key
5. Add to .env as OPENAI_API_KEY=sk-...

For Ollama (free, local models):

• Install Ollama from ollama.ai
• Run ollama pull llama2 to download a model
• No API key needed; Ollama runs locally on your machine

Step 3: Start OpenClaw with Docker Compose

Navigate to the openclaw directory and launch the services:

docker-compose up -d

This command starts:

• OpenClaw API server
• PostgreSQL database
• Redis cache
• Nginx reverse proxy

The -d flag runs services in the background. To see logs in real-time, omit the -d:

docker-compose up

Wait for all services to start (usually 30-60 seconds). You'll see messages like:

openclaw-api-1      | Starting OpenClaw API server on 0.0.0.0:8000
postgres-1          | database system is ready to accept connections
redis-1             | * Ready to accept connections

Step 4: Access the Web Dashboard

Once Docker Compose has started, navigate to the web dashboard:

http://localhost:8000

You should see the OpenClaw login page. Use the default credentials:

• Username: admin
• Password: admin

Important: Change these credentials immediately in Settings > Security for production deployments.

Step 5: Configure Your AI Model

After logging in, navigate to Settings > AI Models:

1. Click "Add Model"
2. Select your AI provider (Anthropic, OpenAI, Ollama)
3. Enter your API key (if required)
4. Test the connection by clicking "Test Connection"
5. Set this model as default

For best results as a beginner, we recommend:

• Anthropic's Claude 3 Haiku (fast, affordable)
• OpenAI's GPT-4 Turbo (most capable)
• Llama 2 via Ollama (free, runs locally)

Step 6: Install Your First Skill

Skills are what give OpenClaw capabilities. From the dashboard:

1. Go to Skills > Marketplace
2. Search for "Email Summary" (a popular beginner skill)
3. Click Install
4. Configure any required settings (like email credentials)
5. Click Activate

You now have your first skill running!

Step 7: Connect Your First Messaging Platform

Let's connect WhatsApp so you can interact with OpenClaw via text messages.

Connecting WhatsApp

1. Go to Settings > Integrations > WhatsApp
2. Click "Connect WhatsApp"
3. You'll see a QR code
4. Open WhatsApp on your phone and scan the code
5. Follow the on-screen instructions to link your account
6. Send a test message to your OpenClaw number

Connecting Telegram

1. Go to Settings > Integrations > Telegram
2. Copy your bot token
3. Open Telegram and search for "@BotFather"
4. Create a new bot and get your token
5. Paste the token into OpenClaw settings
6. Click Save and Test

Connecting Discord

1. Go to Settings > Integrations > Discord
2. Click "Create Discord Bot"
3. You'll be taken to Discord Developer Portal
4. Copy the bot token
5. Paste into OpenClaw settings
6. Add the bot to your Discord server
7. Test by sending a message in your configured channel

Verification: Is Everything Working?

To confirm OpenClaw is fully operational:

# Check container status
docker ps

View logs for any service
docker-compose logs openclaw-api

Test API connectivity
curl http://localhost:8000/api/health

A successful health check should return:

{
  "status": "healthy",
  "version": "1.0.0",
  "models": ["claude-3-haiku"]
}

Troubleshooting Common Issues

"Connection refused" when accessing localhost:8000

The services may still be starting. Wait 30 seconds and refresh the page. Check logs:

docker-compose logs

Docker: "command not found"

Docker isn't installed or not in your PATH. Reinstall Docker or add it to your system PATH.

Out of disk space errors

OpenClaw and its AI models require significant space. Check available disk:

df -h

You need at least 20GB free. If low on space, clean up old Docker images:

docker image prune -a

"postgres: could not create shared memory segment" on Linux

Your system's shared memory is too small. Increase it:

sudo sysctl -w kernel.shmmax=17179869184
sudo sysctl -w kernel.shmall=4194304

Wrong API key or model not responding

Double-check your .env file. Ensure your API key is correct and has proper permissions. For Anthropic, verify the key starts with sk-ant-.

Upgrading OpenClaw

To get the latest features and security updates:

cd openclaw
git pull origin main
docker-compose pull
docker-compose up -d --build

Your data persists in the PostgreSQL database, so you won't lose any configurations or history.

Production Deployment Considerations

For serious, 24/7 usage:

• Use strong passwords: Change default admin credentials immediately
• Enable SSL: Configure HTTPS with Let's Encrypt
• Regular backups: Use docker-compose exec postgres pg_dump to backup your database
• Monitor logs: Set up log aggregation for all containers
• Resource limits: Set memory and CPU limits in docker-compose.yml to prevent resource exhaustion

For production hosting on a VPS, see the OpenClaw on a Cheap VPS guide.

Frequently Asked Questions

Q: Can I run OpenClaw without Docker?

A: Yes, but Docker makes setup much simpler. For manual installation, clone the repository and follow the development setup instructions in the README. You'll need to install Node.js, PostgreSQL, and Redis separately.

Q: How much does the AI model cost?

A: If using Anthropic or OpenAI, you pay per token used. Starting with Claude Haiku is very affordable ($0.25 per million input tokens). If using Ollama locally, it's completely free.

Q: Can I use multiple AI models?

A: Absolutely. You can configure multiple models in Settings > AI Models and select which to use for different skills or agents.

Q: Is my data stored securely?

A: All data is stored in PostgreSQL on your local machine. If you're self-hosting on a VPS, you control the server. For maximum security, encrypt your database.

Q: How do I backup my configurations and data?

A: Use docker-compose exec postgres pg_dump openclaw > backup.sql to export your database. For complete backup including skills, also back up the ./data and ./skills directories.

Next Steps

Now that OpenClaw is installed and running:

• 10 Things to Try on Day 1 — Explore core features and run your first automations
• Connect Messaging Platforms — Add more ways to interact with your assistant
• Finding and Installing Skills — Explore the Skills Marketplace for more capabilities