OpenClaw AI Installation Guide

Install OpenClaw AI on your preferred platform. This guide covers Windows, macOS, Linux, Docker, and server environments with verification steps for each.

Setup ⏱ 10 min read
ℹ️
Before you begin

Ensure you have Python 3.10 or higher installed. Run python --version to check. If you need to install Python, visit python.org/downloads.

Choose Your Platform

Windows Installation

The recommended approach on Windows is using pip inside a virtual environment, with PowerShell or Command Prompt.

  1. 1

    Open PowerShell as Administrator

    Press Win + X → select Terminal (Admin) or Windows PowerShell (Admin).

  2. 2

    Create a Virtual Environment

    python -m venv openclaw-env
.\openclaw-env\Scripts\Activate.ps1
  3. 3

    Install OpenClaw

    pip install openclaw
  4. 4

    Verify Installation

    openclaw --version
# Expected: OpenClaw AI v1.0.0
⚠️
Execution Policy

If you get a script execution error, run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS Installation

On macOS, we recommend using Homebrew for Python and installing OpenClaw in a virtual environment.

  1. 1

    Install Python 3.11 via Homebrew

    brew install python@3.11
# Verify:
python3 --version
  2. 2

    Create and activate a virtual environment

    python3 -m venv ~/openclaw-env
source ~/openclaw-env/bin/activate
  3. 3

    Install OpenClaw

    pip install openclaw
  4. 4

    Verify

    openclaw --version
openclaw doctor  # checks all dependencies

Linux Installation

Tested on Ubuntu 20.04+, Debian 11+, Fedora 36+, and Arch Linux.

# Ubuntu / Debian
sudo apt update && sudo apt install -y python3.11 python3.11-venv python3-pip

# Create venv
python3.11 -m venv ~/openclaw-env
source ~/openclaw-env/bin/activate

# Install
pip install openclaw

# Verify
openclaw --version

For Fedora / RHEL / Rocky:

sudo dnf install python3.11 python3.11-venv
python3.11 -m venv ~/openclaw-env
source ~/openclaw-env/bin/activate
pip install openclaw

Docker Installation

The official OpenClaw image is available on Docker Hub. This is the recommended approach for servers and CI/CD pipelines.

# Pull the latest image
docker pull openclaw/openclaw:latest

# Run a task directly
docker run --rm \
  -e OPENCLAW_API_KEY=your_key \
  -v $(pwd):/workspace \
  openclaw/openclaw:latest \
  run "List all Python files in /workspace"

Or use Docker Compose for persistent configuration:

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_PROVIDER=openai
      - OPENCLAW_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./workspace:/workspace
      - ./config:/root/.openclaw

Server Installation

For running OpenClaw as an API server or background service on a VPS/cloud instance:

# Install as system service
pip install openclaw[server]

# Create config
mkdir ~/.openclaw
openclaw config init --provider openai

# Start the API server
openclaw serve --port 8080 --host 0.0.0.0

# Or run as a systemd service
openclaw install-service --port 8080

The API server exposes a REST endpoint at http://localhost:8080/v1/run compatible with the OpenAI chat format for easy integration.

Optional Components

Depending on your use case, you may want to install optional components:

# Browser automation support (Playwright)
pip install openclaw[browser]
playwright install chromium

# Database tools
pip install openclaw[db]

# Full feature set
pip install openclaw[all]

# Development tools
pip install openclaw[dev]

Installing Ollama for Local LLMs

To run AI agents completely offline without any API key, install Ollama alongside OpenClaw:

# macOS / Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model (3.8B — fast, runs on 4GB RAM)
ollama pull llama3.2:3b

# Or a larger, more capable model
ollama pull mistral:7b

# Tell OpenClaw to use Ollama
openclaw config set provider ollama
openclaw config set ollama_model llama3.2:3b

Verify Your Installation

Run the built-in diagnostic tool to confirm everything is working:

openclaw doctor
OpenClaw Doctor v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Python 3.11.4 (required: ≥3.10)
✅ OpenClaw 1.0.0 installed
✅ Config file found: ~/.openclaw/config.yaml
✅ Provider: openai
✅ API key: configured (sk-...xxxx)
⚠️  Optional: browser tools not installed
⚠️  Optional: Ollama not detected

All required checks passed. Ready to run agents!

Troubleshooting

Having issues? These are the most common installation problems:

Try pip3 or python -m pip. On some systems pip is not in PATH. Install python3-pip from your package manager.
This usually means the pip scripts directory is not in your PATH. Try running python -m openclaw or add ~/.local/bin to your PATH. On Windows add %APPDATA%\Python\Scripts.
Run pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org openclaw. This is usually caused by corporate proxies or outdated certifi.
Install Python 3.11 from python.org. Use py -3.11 -m pip install openclaw on Windows to target the correct version.

For more help, see the full Troubleshooting guide or ask the community.

💡
See Also
  • Configuration — Set your API key, configure LLM provider, and customise profiles
  • Getting Started — Back to basics: run your first agent step by step
  • Troubleshooting — Solutions for common installation issues
← Previous
Getting Started