Setting Up OpenClaw on Raspberry Pi: Complete Installation Guide

Want a personal AI assistant that runs 24/7 in your home, fully under your control? Raspberry Pi is the perfect platform for self-hosting OpenClaw—affordable, energy-efficient, and powerful enough to run a complete AI agent with browser automation, message handling, and workflow integration.

This guide walks you through installing OpenClaw on Raspberry Pi 4 or 5, from OS setup to your first conversation with your new AI assistant.

Why Raspberry Pi for OpenClaw?

Running OpenClaw on Raspberry Pi offers several advantages over cloud hosting:

Full Privacy: Your conversations and data never leave your local network. No third-party servers involved (except API calls to Claude).

Always Available: 24/7 operation with minimal power consumption (3-5W vs 50-100W for a desktop PC).

Cost-Effective: After the initial ~$100 hardware investment, ongoing costs are just electricity and Claude API usage (typically $5-20/month).

Learning Platform: Great for understanding how AI assistants work—you control every component of the stack.

Home Automation Hub: Connect to local services like Home Assistant, Zigbee devices, and network-attached storage without exposing them to the internet.

Hardware Requirements

Minimum Specs (Raspberry Pi 4)

Model: Raspberry Pi 4B with 4GB RAM
Storage: 32GB microSD card (UHS-I, A2 rating recommended)
Power: Official 15W USB-C power supply
Network: Ethernet connection recommended for stability

Recommended Specs (Raspberry Pi 5)

Model: Raspberry Pi 5 with 8GB RAM
Storage: 64GB NVMe SSD with M.2 HAT (significantly faster than SD card)
Power: Official 27W USB-C PD power supply
Network: Gigabit Ethernet or WiFi 6

Why Pi 5 is better: Faster CPU (2-3x performance), PCIe M.2 support for NVMe storage, improved I/O bandwidth, and better thermal performance. The 8GB model provides comfortable headroom for browser automation and multiple concurrent tasks.

What You'll Need

Raspberry Pi 4 (4GB+) or Pi 5 (8GB recommended)
Power supply appropriate for your model
microSD card (32GB+ Class 10) or NVMe SSD
Ethernet cable (or WiFi if needed)
Computer for initial setup
Claude API key from Anthropic
(Optional) Case with fan for better cooling

Step 1: Install Raspberry Pi OS

We'll use Raspberry Pi OS Lite (64-bit) for optimal performance—no desktop GUI consuming resources.

Using Raspberry Pi Imager

Download Raspberry Pi Imager on your computer
Insert your microSD card
Open Imager and configure:
- Device: Raspberry Pi 4 or 5
- OS: Raspberry Pi OS Lite (64-bit)
- Storage: Your microSD card

Click the gear icon (⚙️) for advanced options:

Hostname: openclaw
Enable SSH: Yes
Username: pi
Password: [choose a strong password]
WiFi: [configure if not using Ethernet]
Locale: [your timezone]

Click Write and wait for completion
Insert the card into your Pi and power on

First Boot

Wait 1-2 minutes for first boot, then SSH into your Pi:

ssh pi@openclaw.local

Or if mDNS doesn't work, find the IP from your router and use:

ssh pi@192.168.1.XXX

Step 2: System Preparation

Once logged in, update the system and install dependencies:

# Update package lists and system
sudo apt update && sudo apt upgrade -y

# Install Node.js 22 (required for OpenClaw)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Verify Node.js installation
node --version  # Should show v22.x.x
npm --version   # Should show 10.x.x

# Install Git
sudo apt install -y git

# Install Chromium dependencies (for browser automation)
sudo apt install -y \
  chromium-browser \
  chromium-codecs-ffmpeg-extra \
  fonts-liberation \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libatspi2.0-0 \
  libcups2 \
  libdbus-1-3 \
  libgdk-pixbuf2.0-0 \
  libgtk-3-0 \
  libnspr4 \
  libnss3 \
  libx11-xcb1 \
  libxcomposite1 \
  libxdamage1 \
  libxrandr2 \
  xdg-utils

# Install optional tools
sudo apt install -y \
  ffmpeg \        # For media processing
  imagemagick \   # For image operations
  trash-cli       # Safe file deletion

Step 3: Install OpenClaw

# Install OpenClaw globally
sudo npm install -g openclaw

# Verify installation
openclaw --version

# Initialize OpenClaw workspace
mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace

Step 4: Configure Claude API

You need a Claude API key from Anthropic. If you don't have one:

Visit console.anthropic.com
Create an account and add payment method
Generate an API key under Account Settings → API Keys

Configure OpenClaw with your key:

# Set Claude API key
openclaw config set claude.apiKey "your-api-key-here"

# Configure default model (Opus for best quality)
openclaw config set claude.defaultModel "claude-opus-4"

# Or Sonnet for faster/cheaper responses
openclaw config set claude.defaultModel "claude-sonnet-4"

Step 5: Configure Browser Automation

OpenClaw uses Playwright for browser automation. Install Chromium:

# Install Playwright
npx playwright install chromium

# Set browser path in OpenClaw config
CHROMIUM_PATH=$(find ~/.cache/ms-playwright -name chrome -type f 2>/dev/null | head -1)
openclaw config set browser.executablePath "$CHROMIUM_PATH"

# Enable headless mode (required for Pi without display)
openclaw config set browser.headless true

# Disable sandboxing (necessary on Pi)
openclaw config set browser.noSandbox true

Step 6: Create Workspace Files

OpenClaw uses markdown files for memory and configuration. Create the basic structure:

cd ~/.openclaw/workspace

# Create SOUL.md (agent personality)
cat > SOUL.md << 'EOF'
# SOUL.md

I am ClawPi, an AI assistant running on Raspberry Pi. I'm helpful, 
efficient, and focused on practical automation. I specialize in 
home automation, data processing, and local network tasks.

I run 24/7 in my human's home, providing always-available assistance 
for daily tasks, reminders, information lookup, and system management.
EOF

# Create USER.md (your preferences)
cat > USER.md << 'EOF'
# USER.md

Name: [Your Name]
Timezone: [Your Timezone]

Preferences:
- Direct, concise communication
- Focus on practical solutions
- Proactive reminders for calendar events
EOF

# Create AGENTS.md (operational rules)
cat > AGENTS.md << 'EOF'
# AGENTS.md

## First Run
1. Read SOUL.md to understand identity
2. Read USER.md for context about the human
3. Check memory/ directory for recent context

## Memory
- Daily logs in memory/YYYY-MM-DD.md
- Long-term memory in MEMORY.md (main session only)

## Execution
- Always complete tasks fully
- Report errors clearly
- Use browser for visual verification
EOF

# Create memory directory
mkdir -p memory

# Create TOOLS.md (local notes)
cat > TOOLS.md << 'EOF'
# TOOLS.md - Local Notes

## Raspberry Pi
- Model: [Your Pi model]
- Hostname: openclaw
- Location: [Physical location]

## Services
- OpenClaw Gateway: localhost:3000
EOF

Step 7: Start OpenClaw Gateway

The Gateway manages persistent connections and runs your agent:

# Start Gateway in background
openclaw gateway start

# Check status
openclaw gateway status

# View logs
openclaw gateway logs

The Gateway should show as running. If you see errors, check:

Node.js version is 22.x: node --version
Claude API key is set: openclaw config get claude.apiKey
Permissions on workspace: ls -la ~/.openclaw/

Step 8: First Conversation

Start a chat session with your agent:

openclaw chat

Try these commands to test your setup:

You: Hello! Tell me about yourself.

You: What's the weather today? [tests web search]

You: Navigate to example.com and take a screenshot [tests browser]

You: Create a file called test.txt with "Hello from OpenClaw" [tests file operations]

You: Read test.txt back to me

Type /exit to leave the chat.

Step 9: Enable Autostart

Make OpenClaw start automatically on boot:

# Create systemd service
sudo tee /etc/systemd/system/openclaw-gateway.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=pi
Environment=HOME=/home/pi
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

# Check status
sudo systemctl status openclaw-gateway

Now OpenClaw will start automatically when your Pi boots.

Performance Optimization

Use NVMe Storage (Pi 5)

If you have a Pi 5, switching from microSD to NVMe dramatically improves performance:

Install NVMe HAT and SSD
Flash OS to NVMe using Raspberry Pi Imager
Boot from NVMe (configure in Raspberry Pi Imager advanced options)

Browser operations and file I/O will be 5-10x faster.

Reduce Memory Usage

# Use Sonnet instead of Opus (uses less context)
openclaw config set claude.defaultModel "claude-sonnet-4"

# Limit browser resource usage
openclaw config set browser.args '["--disable-dev-shm-usage", "--disable-gpu"]'

Monitor Resources

# Check CPU and memory
htop

# Check disk space
df -h

# Check temperature (keep under 80°C)
vcgencmd measure_temp

If temperature exceeds 75°C regularly, add active cooling (fan).

Integration Examples

Home Assistant

Connect OpenClaw to Home Assistant for voice-controlled smart home:

# In ~/.openclaw/workspace/TOOLS.md, add:
## Home Assistant
- URL: http://homeassistant.local:8123
- Token: [Long-lived access token]

Then ask OpenClaw: "Turn off the living room lights" or "What's the temperature in the bedroom?"

Scheduled Tasks

Create cron jobs for recurring tasks:

# Edit crontab
crontab -e

# Add daily morning briefing at 7 AM
0 7 * * * /usr/bin/openclaw exec "Generate morning briefing: weather, calendar, news summary"

# Add hourly calendar check
0 * * * * /usr/bin/openclaw exec "Check calendar for events in next 2 hours and notify if any"

Discord Bot

Run OpenClaw as a Discord bot (see our Discord integration guide):

openclaw message setup --channel discord
# Follow prompts to add bot token

Now your Pi-hosted agent can respond in Discord channels.

Troubleshooting

Gateway Won't Start

# Check logs for errors
openclaw gateway logs

# Common issues:
# - Port 3000 in use: Change with `openclaw config set gateway.port 3001`
# - Permission errors: Check ~/.openclaw/ ownership: `ls -la ~/.openclaw/`
# - Missing dependencies: Reinstall with `sudo npm install -g openclaw --force`

Browser Automation Fails

# Verify Chromium is installed
chromium-browser --version

# Reinstall Playwright
npx playwright install chromium --force

# Check browser config
openclaw config get browser

Out of Memory Errors

Pi 4 with 4GB can struggle with complex browser tasks. Solutions:

# Increase swap space
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Use Sonnet model (lighter weight)
openclaw config set claude.defaultModel "claude-sonnet-4"

# Disable browser for memory-intensive tasks
openclaw config set browser.enabled false

Slow Performance

Use Ethernet, not WiFi: Reduces latency for API calls
Switch to NVMe (Pi 5): 10x faster storage access
Reduce browser usage: Browser automation is CPU/memory intensive
Use lighter models: Sonnet instead of Opus for routine tasks

Next Steps

Now that OpenClaw is running on your Pi, explore:

Set up messaging: Connect to Discord, Telegram, or email
Create custom skills: Build Pi-specific integrations (GPIO, sensors, etc.)
Automate workflows: Use cron jobs for scheduled tasks
Add cameras: Connect USB webcams for visual input
Build voice control: Integrate with wake word detection

Your Raspberry Pi is now a powerful, always-on AI assistant—fully under your control, running in your home, ready to help 24/7.

Resources

Happy automating! 🤖🥧