Setup Guide
Run OpenClaw on Raspberry Pi
Deploy your personal AI assistant on affordable Raspberry Pi hardware. This guide covers everything from hardware selection to performance optimization for a reliable, always-on OpenClaw installation. Follow this guide to set it up yourself, or let our team handle it for you.
Prerequisites
- Raspberry Pi 4 (4GB+) or Raspberry Pi 5
- MicroSD card (32GB+ recommended) or USB SSD
- Power supply (official or quality 5V/3A)
- Ethernet or WiFi connectivity
- Basic Linux command line knowledge
OpenClaw on Raspberry Pi
The Raspberry Pi provides an excellent platform for running OpenClaw as a dedicated, always-on personal assistant. With low power consumption (typically 5-10 watts), silent operation, and affordable hardware costs, a Raspberry Pi-based OpenClaw installation offers compelling advantages for home automation and personal AI assistant use cases.
OpenClaw officially supports ARM64 architecture, making it compatible with Raspberry Pi 4 and the newer Raspberry Pi 5. The Pi 5's improved CPU and I/O performance make it the preferred choice for new installations, while Pi 4 units with 4GB or 8GB RAM remain fully capable for personal use workloads.
Use Cases for Pi-Based OpenClaw
Raspberry Pi deployments excel in several scenarios. Home automation integration benefits from the Pi's GPIO capabilities and local network presence. Privacy-focused users appreciate keeping their assistant on local hardware rather than cloud servers. The Pi's low cost makes it an ideal dedicated device that runs around the clock without significant electricity costs.
Consider a Pi deployment when you want always-on availability without cloud hosting costs, prefer a physical device you control entirely, need integration with home automation systems, or want to minimize your AI assistant's infrastructure footprint. Cloud deployment may be better if you need high availability, multi-user support, or integration with cloud services.
Performance Expectations
Be realistic about Raspberry Pi performance compared to more powerful systems. The Pi 5's quad-core Cortex-A76 CPU handles OpenClaw well, but response times may be slightly longer than cloud deployments. Memory-intensive operations with long conversation histories work best with 8GB RAM models. The Pi 4's slower CPU is adequate but more noticeable during complex agent operations.
AI model inference happens on remote API servers, so the Pi's processing power primarily affects local operations: managing WebSocket connections, handling message routing, and running the WebChat interface. For these tasks, both Pi 4 and Pi 5 perform adequately with proper optimization.
Hardware Selection and Setup
Choosing the right hardware ensures a reliable OpenClaw installation. This section covers Raspberry Pi model selection, storage options, and peripheral requirements.
Raspberry Pi Model Recommendations
The Raspberry Pi 5 with 8GB RAM is the optimal choice for new installations. Its improved CPU (2-3x faster than Pi 4), better I/O throughput, and PCIe support for fast NVMe storage provide the best OpenClaw experience on Pi hardware. The 4GB Pi 5 variant works adequately for lighter workloads.
The Raspberry Pi 4 with 8GB RAM remains a solid option, especially if you already own one. The 4GB Pi 4 variant is the minimum recommended configuration; models with 2GB or less RAM are not recommended due to memory constraints with conversation history and concurrent channel connections.
Older Raspberry Pi models (Pi 3, Zero) lack sufficient processing power and memory for OpenClaw and are not supported.
Storage Options
Storage performance significantly impacts OpenClaw's responsiveness, particularly for session data and conversation history operations. While microSD cards work, USB SSD storage provides substantially better performance and longevity.
For microSD installations, use high-quality A2-rated cards (like Samsung EVO Plus or SanDisk Extreme) with at least 32GB capacity. These cards offer better random I/O performance important for database operations. For optimal performance, boot from a USB 3.0 SSD using the Pi's native USB boot capability.
The Pi 5's PCIe slot enables NVMe SSD boot with an HAT adapter, providing the fastest storage option. NVMe dramatically improves boot times, application responsiveness, and database operations compared to microSD.
Power Supply
Use an official Raspberry Pi power supply or a quality USB-C power supply rated for 5V/3A minimum (5V/5A for Pi 5). Underpowered supplies cause throttling, instability, and SD card corruption. The power requirements increase when using USB devices or HATs; consider a powered USB hub for accessories.
Cooling
OpenClaw runs continuously, generating sustained heat loads. Active cooling (small fan) or passive cooling (heatsink case) prevents thermal throttling. The official Pi 5 Active Cooler or similar products maintain optimal temperatures under continuous operation. Without adequate cooling, performance degrades during extended use.
Network Connectivity
Wired Ethernet provides the most reliable connectivity for an always-on assistant. If WiFi is necessary, ensure strong signal strength and consider a USB WiFi adapter with external antenna for improved reliability. Network interruptions affect messaging platform connections, so stable connectivity is important.
Operating System Installation
A properly configured operating system forms the foundation for your OpenClaw installation. This section covers OS selection, installation, and initial configuration.
Recommended Operating System
Raspberry Pi OS Lite (64-bit) is recommended for dedicated OpenClaw installations. The Lite variant excludes the desktop environment, freeing resources for OpenClaw. The 64-bit version is required for Node.js 22 compatibility and provides better performance than 32-bit alternatives.
Ubuntu Server 22.04 LTS for Raspberry Pi is an alternative that works well, particularly if you prefer Ubuntu's ecosystem and package management. Both options receive regular security updates and support modern Node.js versions.
Installation Process
Use the official Raspberry Pi Imager to flash your OS image to microSD or USB storage. The Imager allows pre-configuring WiFi credentials, SSH access, and username/password before first boot, streamlining headless setup. Enable SSH in the Imager's advanced options to access your Pi remotely from the start.
For USB boot on Pi 4, you may need to update the bootloader EEPROM first. Pi 5 supports USB and NVMe boot out of the box. After flashing, insert the storage media and power on the Pi. Wait 2-3 minutes for initial boot and expansion.
Initial System Configuration
Connect to your Pi via SSH using the credentials configured in the Imager. Update the system packages immediately to ensure security patches are applied. Configure the timezone and locale settings appropriate for your location. These affect logging timestamps and scheduled operations.
Expand the filesystem if it wasn't done automatically (rare with current images). Check available disk space to ensure your storage was fully utilized. Reboot after configuration changes to ensure all settings take effect.
Headless Operation
For dedicated OpenClaw use, headless operation without monitor or keyboard is standard. Ensure SSH access works reliably before disconnecting any attached display. Consider setting a static IP address or using your router's DHCP reservation to maintain consistent network addressing.
Installing OpenClaw
With the operating system configured, proceed to install Node.js and OpenClaw. This section covers the complete installation process optimized for Raspberry Pi.
Install Node.js 22
Node.js 22 is required for OpenClaw. On Raspberry Pi OS, install from the NodeSource repository for the latest versions. The ARM64 build of Node.js runs natively on 64-bit Pi OS. Installation takes a few minutes as packages download and install.
Verify the installation by checking the Node version. Ensure it shows version 22.x.x before proceeding. If the version is incorrect, the NodeSource repository may not have been properly added; retry the repository setup.
Install OpenClaw
Install OpenClaw globally using npm. The installation downloads OpenClaw and all dependencies, which may take several minutes on Pi hardware. Monitor disk space during installation if using a smaller microSD card.
After installation, verify the openclaw command is available. Run the version check to confirm the installation succeeded. If the command isn't found, the npm global bin directory may not be in your PATH; add it to your .bashrc or .zshrc file.
Run Onboarding
Execute the onboarding wizard with daemon installation to configure OpenClaw for your Pi. The wizard creates configuration files, sets up the workspace, and optionally installs the systemd service for automatic startup. Follow the prompts to configure your AI model provider and initial channel connections.
For Raspberry Pi, the systemd daemon is strongly recommended. It ensures OpenClaw starts automatically after boot, survives SSH disconnects, and restarts after any crashes. The headless nature of Pi deployments makes daemon operation essential.
Initial Testing
After onboarding completes, verify the Gateway is running with the status command. Access the WebChat interface from another device on your network using the Pi's IP address and port 18789. Send a test message to confirm the AI connection works properly.
Performance Optimization
Raspberry Pi has limited resources compared to desktop systems or cloud servers. These optimizations ensure OpenClaw runs smoothly within those constraints.
Memory Management
Configure OpenClaw to manage memory efficiently. Reduce maximum context length if you experience memory pressure with long conversations. The default settings work well on 8GB models; 4GB models benefit from more conservative limits.
Monitor system memory usage regularly with tools like htop or the free command. If memory becomes critically low, the Linux OOM killer may terminate processes unexpectedly. Swap space provides a buffer but dramatically slows operations; prefer proper memory configuration over relying on swap.
Swap Configuration
While not a replacement for adequate RAM, properly configured swap prevents crashes during memory spikes. On Pi OS, swap is configured via dphys-swapfile. For SSD-based installations, a 2GB swap file provides good headroom. Avoid large swap files on microSD cards as they accelerate wear.
GPU Memory Split
For headless operation, reduce GPU memory allocation to free RAM for OpenClaw. Edit /boot/config.txt (Pi OS) to set gpu_mem=16, the minimum for headless operation. This reclaims around 60MB of RAM on default configurations. Reboot after changing this setting.
Service Optimization
Disable unnecessary services on dedicated OpenClaw installations. Services like Bluetooth, WiFi (if using Ethernet), and audio can be disabled to free resources. Review running services with systemctl list-units and disable those not needed for your use case.
Storage Optimization
Enable log rotation to prevent disk space exhaustion from accumulating logs. Configure logrotate for OpenClaw logs with appropriate retention periods. Consider more aggressive rotation on space-constrained microSD installations.
Periodically clean package manager caches and old log files. The apt clean command removes cached packages. Review disk usage with df -h and investigate unexpected growth in any directories.
Ensuring Reliable Operation
An always-on assistant requires reliable continuous operation. This section covers practices that ensure your Pi-based OpenClaw stays running smoothly.
Automatic Updates
Enable unattended security updates to protect against vulnerabilities without manual intervention. On Pi OS, install and configure unattended-upgrades. Configure it for security updates only to avoid unexpected breaking changes from feature updates.
Consider scheduled reboots (weekly or monthly) to clear accumulated state and ensure updates take effect. Use systemd timers or cron to schedule reboots during low-usage periods.
Health Monitoring
Implement basic health monitoring for your Pi installation. The openclaw doctor command checks system health and reports issues. Schedule periodic health checks with alerts for failures.
Monitor key metrics: CPU temperature (throttling above 80C indicates cooling issues), disk space usage, memory pressure, and network connectivity. Simple scripts can check these and send notifications through OpenClaw itself or external services.
SD Card Longevity
MicroSD cards have limited write endurance. Reduce writes by mounting /tmp as tmpfs (RAM disk), reducing logging verbosity, and avoiding unnecessary database operations. These practices extend SD card life from months to years.
For highest reliability, use USB SSD boot instead of microSD. SSDs have dramatically better endurance and performance, making them worth the modest additional cost for always-on operation.
Power Protection
Power interruptions can corrupt SD cards and cause data loss. Use a UPS (uninterruptible power supply) designed for small devices, or a battery-backed HAT to provide graceful shutdown on power loss. At minimum, ensure clean shutdown procedures are documented for manual intervention.
Backup Strategy
Implement regular backups of OpenClaw configuration and data. The Pi's small storage footprint makes full-system backups practical. Use rsync to a network location or cloud storage. Consider periodic SD card images as comprehensive backups that enable quick recovery by flashing to new media.
Network Configuration
Proper network configuration ensures reliable connectivity for messaging platform connections and remote access to your Pi-based OpenClaw installation.
Static IP Configuration
Assign a static IP address to ensure consistent addressing. Configure this through your router's DHCP reservation (recommended) or directly on the Pi. Static addressing prevents the IP from changing after router reboots, which would break bookmarks and remote access configurations.
Remote Access Setup
For accessing OpenClaw from outside your home network, several options exist. Tailscale provides the simplest solution with its VPN mesh that requires no port forwarding. OpenClaw supports Tailscale natively through configuration options. Alternatively, configure port forwarding on your router with a dynamic DNS service for domain-based access.
Exposing services directly to the internet requires careful security consideration. At minimum, use HTTPS with proper certificates and consider additional authentication. Tailscale's approach avoids public exposure entirely, making it the preferred method for home deployments.
Firewall Configuration
Configure the Pi's firewall (ufw on Pi OS) to restrict incoming connections. Allow SSH from your local network, HTTP/HTTPS if needed, and the OpenClaw WebSocket port (18789) as appropriate. Deny all other incoming traffic by default.
mDNS/Bonjour
Enable mDNS (Avahi on Linux) to access your Pi via hostname rather than IP address. With mDNS configured, you can reach your Pi at openclaw.local (or your chosen hostname) from devices on the same network without remembering IP addresses.
Troubleshooting Pi-Specific Issues
This section addresses common issues specific to Raspberry Pi deployments and provides solutions.
Thermal Throttling
If OpenClaw becomes sluggish during use, check CPU temperature with vcgencmd measure_temp. Temperatures above 80C indicate thermal throttling. Solutions include adding or improving cooling (heatsinks, fans, active cooler), improving case ventilation, or relocating the Pi to a cooler environment.
SD Card Corruption
Symptoms of SD card issues include boot failures, filesystem errors, and random application crashes. Run filesystem check with fsck after booting from USB or another SD card. If corruption is found, restore from backup to a new SD card. Consider migrating to USB SSD boot to prevent recurrence.
Network Disconnections
WiFi disconnections are common on Pi, especially with power-saving features. Disable WiFi power management by creating a configuration file that disables power save. For critical deployments, wired Ethernet provides superior reliability.
Memory Exhaustion
Out-of-memory errors manifest as application crashes or system unresponsiveness. Monitor memory usage to identify the cause. Solutions include reducing OpenClaw memory limits, disabling unnecessary services, adding swap (with SSD), or upgrading to a Pi model with more RAM.
Slow Performance
If OpenClaw feels slow, check CPU usage and temperature first. High CPU with normal temperature indicates a genuine workload; reduce concurrent operations. High temperature with throttling indicates cooling issues. Slow storage operations suggest SD card issues or the need for SSD upgrade.
Service Won't Start
If the OpenClaw daemon fails to start, check logs with journalctl -u openclaw. Common causes include configuration file errors, missing API keys, or port conflicts. The openclaw doctor command provides diagnostic information about common issues.
Code Examples
# Initial system update (SSH into your Pi first)
sudo apt update && sudo apt full-upgrade -y
# Set timezone
sudo timedatectl set-timezone America/New_York
# Check system info
cat /proc/cpuinfo | grep Model
free -h
df -h# Install Node.js 22 on Raspberry Pi
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# Verify installation
node --version
npm --version# Install OpenClaw
sudo npm install -g openclaw@latest
# Run onboarding with daemon
openclaw onboard --install-daemon
# Check status
openclaw gateway status
openclaw doctor# Reduce GPU memory for headless operation
sudo nano /boot/config.txt
# Add or modify: gpu_mem=16
# Configure swap (for SSD installations)
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set: CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon# Disable WiFi power management
sudo nano /etc/NetworkManager/conf.d/default-wifi-powersave-on.conf
# Add:
# [connection]
# wifi.powersave = 2
# Or for older Pi OS versions without NetworkManager:
sudo iw wlan0 set power_save off# Temperature and health monitoring
vcgencmd measure_temp
vcgencmd get_throttled
# Create monitoring script
cat << 'EOF' | sudo tee /usr/local/bin/pi-health.sh
#!/bin/bash
echo "Temperature: $(vcgencmd measure_temp)"
echo "Throttle status: $(vcgencmd get_throttled)"
echo "Memory: $(free -h | grep Mem)"
echo "Disk: $(df -h / | tail -1)"
EOF
sudo chmod +x /usr/local/bin/pi-health.sh# Enable unattended security updates
sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades
# Configure firewall
sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 18789/tcp
sudo ufw enable# Backup script for Raspberry Pi OpenClaw
#!/bin/bash
BACKUP_PATH="/home/pi/openclaw-backup"
DATE=$(date +%Y%m%d)
mkdir -p $BACKUP_PATH
# Backup OpenClaw config and data
openclaw gateway stop
tar -czf $BACKUP_PATH/openclaw-$DATE.tar.gz \
~/.openclaw/openclaw.json \
~/.openclaw/workspace \
~/.openclaw/data
openclaw gateway start
# Keep last 7 backups
ls -t $BACKUP_PATH/openclaw-*.tar.gz | tail -n +8 | xargs rm -f
echo "Backup complete: $BACKUP_PATH/openclaw-$DATE.tar.gz"{
"agent": {
"model": "anthropic/claude-opus-4-5",
"maxTokens": 4096
},
"gateway": {
"port": 18789,
"host": "0.0.0.0"
},
"performance": {
"maxConcurrentSessions": 3,
"sessionPruneInterval": 3600000,
"maxConversationLength": 50
}
}Related Content
Configure Anthropic Claude for OpenClaw
Configure OpenClaw with Anthropic's Claude models - the officially recommended AI provider. Learn API setup, model selection, OAuth configuration, and optimization for Claude Opus, Sonnet, and Haiku.
Configure OpenAI for OpenClaw
Configure OpenClaw with OpenAI's GPT-4 and GPT-3.5 models. Learn API key setup, model selection, parameter optimization, and best practices for OpenAI integration.
Configure OpenRouter for OpenClaw
Configure OpenClaw with OpenRouter for access to 100+ AI models including Claude, GPT-4, Llama, and more through a single API. Learn setup, model selection, cost optimization, and failover configuration.
Deploy OpenClaw to the Cloud
Deploy OpenClaw to major cloud providers including AWS, Google Cloud, and Azure. Learn infrastructure setup, security configurations, scaling strategies, and production best practices.