AI & AUTOMATIONSELF-HOSTING

How to Install and Run OpenClaw on Raspberry Pi: The Complete Setup Guide

Duy NghienDuy Nghien
753 views0

Key Takeaways

  • Cost Efficiency: Run a 24/7 AI assistant for approximately $1/month in electricity costs using a Raspberry Pi.
  • Hardware Requirements: A Raspberry Pi 4 or 5 with 8GB RAM is recommended for optimal performance; 4GB is the absolute minimum.
  • Software Dependencies: The system requires a 64-bit OS and Node.js version 20 or newer.
  • Privacy: Self-hosting ensures your data remains private, interacting only with your chosen LLM provider and messaging apps.

Why OpenClaw Meets Raspberry Pi Perfectly

OpenClaw is an open-source, self-hosted AI assistant designed to automate tasks, manage browser interactions, and integrate seamlessly with messaging platforms like WhatsApp, Telegram, and Discord. While running such an assistant usually requires expensive cloud hosting or a dedicated desktop, the Raspberry Pi offers a powerful, cost-effective alternative.

The Raspberry Pi 4 and 5 are low-power single-board computers perfectly capable of handling continuous operations. When combined with OpenClaw, you can create a persistent AI agent for an upfront hardware cost of roughly $105 and a power consumption of ~5W. This guide details the installation process on Raspberry Pi OS, utilizing systemd for reliable 24/7 availability.

Prerequisites: Your Hardware and Software Checklist

Successful deployment requires specific hardware capable of handling Node.js processes and browser automation, alongside the correct software environment.

Hardware Checklist

  • Raspberry Pi 4 (8GB RAM) or Raspberry Pi 5 (8GB RAM) — While a 4GB Pi 4 is technically viable, it may struggle with intensive browser automation tasks.
  • MicroSD card — 32GB or larger with an A1/A2 rating is recommended to ensure faster write speeds and reduced wear.
  • Power supply — Use the official USB-C PSU for your specific Pi model to ensure stable operation.
  • Case with cooling — Active cooling is essential for 24/7 operation to prevent thermal throttling.
  • Ethernet cable — Wired connections are preferred for network reliability, though Wi-Fi is supported.
  • NVMe SSD adapter (Optional) — An SSD significantly enhances input/output (I/O) performance compared to MicroSD cards.

Software Checklist

  • Raspberry Pi Imager — Available at raspberrypi.com/software.
  • SSH client — Built-in on Mac/Linux; Windows users may use PuTTY, PowerShell, or Windows Subsystem for Linux (WSL).
  • Raspberry Pi OS (64-bit) Lite — The minimal Command Line Interface (CLI) version reduces RAM usage and desktop overhead.
  • Text editor — Tools like nano or vim come pre-installed.
  • Node.js 20+ — A critical core requirement for the application.

Networking & Access

  • Static IP address: Recommended to prevent connection issues within your local network.
  • SSH access: Must be enabled during the OS flashing process.
  • Port 18789: Ensure this port is available (the default OpenClaw gateway).

Step 1: System Preparation – Flashing Raspberry Pi OS

OpenClaw requires a 64-bit operating system to execute its architecture reliably. You must flash the “Lite” version to maximize available system resources.

1.1 Flash Raspberry Pi OS (64-bit)

  1. Insert your MicroSD card into an SD card reader connected to your computer.
  2. Open Raspberry Pi Imager.
  3. Click Choose OS and navigate to Raspberry Pi OS (other) → Raspberry Pi OS (64-bit) Lite.
  4. Click Choose Storage and select your MicroSD card.
  5. Click Next, then select Edit Settings (the gear icon).

1.2 Configure SSH and Hostname

In the Advanced Settings dialog, apply the following configurations:

  • Hostname: Set to openclaw-pi for easy network identification.
  • Enable SSH: Toggle this on and select “Use password authentication.”
  • Set username and password: Create secure credentials for the default user (e.g., pi).
  • Configure Wi-Fi: Enter your SSID and password if Ethernet is unavailable.
  • Locale: Set your specific region and timezone.

Click Save, then Write. Allow 2–5 minutes for the process to complete.

1.3 Boot and Connect via SSH

  1. Insert the MicroSD card into the Raspberry Pi.
  2. Connect the power supply and Ethernet cable.
  3. Allow 30–60 seconds for the initial boot sequence.
  4. Open a terminal on your computer and run:
ssh [email protected]

Alternatively, use the IP address if the hostname fails:

ssh [email protected]  # Replace with actual IP

Step 2: Install System Dependencies

OpenClaw relies on Node.js 20 or newer, Git, and Python 3 to function correctly. You must install these dependencies before attempting to run the bot.

Run the following commands to update the system and install the required packages:

Bash

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

# Install Node.js 20.x from the NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify Node.js and npm versions
node --version    # Should be v20.x.x or higher
npm --version     # Should be 10.x.x or higher

# Install Git (required for cloning the OpenClaw repo)
sudo apt install -y git

# Install build essentials and Python 3
sudo apt install -y build-essential python3

Dependency Explanation:

  • Node.js: The core runtime for the application. Version 20+ is mandatory for modern JavaScript features.
  • Git: Required for version control and system updates.
  • Build Essentials: Compiles native C/C++ modules required by certain npm packages.
  • Python 3: Utilized by specific automation scripts within the OpenClaw ecosystem.

Step 3: Install OpenClaw Using the Installer Script

The official OpenClaw installation script automates the cloning process, dependency installation, and systemd service creation.

3.1 Run the Installation Script

Execute the following command:

curl -fsSL https://openclaw.ai/install.sh | bash

The script performs the following actions:

  • Clones the repository to ~/.openclaw/.
  • Installs Node.js dependencies.
  • Generates openclaw.json and .env configuration files.
  • Creates the openclaw systemd service.

3.2 Post-Installation Verification

Reload your shell environment and verify the installation:

exec bash
openclaw --version

You should receive an output similar to OpenClaw v2026.3.13.

Step 4: Configuration – API Keys and Bot Settings

You must configure your AI provider (LLM) and messaging platforms before the bot can process requests.

4.1 Run the Setup Wizard

The interactive wizard simplifies the configuration process:

openclaw setup --wizard

Follow the prompts to:

  1. Select AI Provider: Choose OpenAI, Anthropic, or others, and input your API key.
  2. Integrate Messaging: Enable platforms like Telegram or WhatsApp and provide necessary tokens.
  3. Configure Behavior: Set memory retention limits and automation preferences.

4.2 Manual Configuration (Alternative)

If you prefer manual configuration, edit the JSON file directly:

nano ~/.openclaw/openclaw.json

Example configuration structure:

{
  "provider": {
    "type": "openai",
    "apiKey": "sk-..."
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "..."
    }
  }
}

Press Ctrl + X, then Y, then Enter to save and exit.

Step 5: Running OpenClaw with Systemd

Systemd is the standard for Linux service management, ensuring your bot starts at boot and automatically restarts if it crashes.

5.1 Start and Enable the Service

Start the service immediately:

sudo systemctl start openclaw

Enable the service to start automatically on reboot:

sudo systemctl enable openclaw

5.2 Monitor Service Status

Check if the service is active and running:

sudo systemctl status openclaw

To view real-time logs for debugging or finding pairing codes:

sudo journalctl -u openclaw -f

Pro Tip: Use the -n 100 flag with journalctl (e.g., sudo journalctl -u openclaw -n 100) to quickly see the last 100 lines of logs without actively following the live stream.

Step 6: Gateway Pairing and Messaging Integration

Pairing connects your local OpenClaw instance to the external gateway that handles messaging traffic.

6.1 Retrieve Pairing Code

Monitor the logs to find your unique pairing code:

sudo journalctl -u openclaw -f

Look for the following output in the console:

Your pairing code: ABC-123-DEF
Visit https://openclaw.ai/pair to complete setup

6.2 Complete Pairing

  1. Navigate to https://openclaw.ai/pair in your web browser.
  2. Enter the code displayed in your terminal logs.
  3. Select your desired platforms (e.g., WhatsApp, Discord) and follow the authentication prompts.
  4. Send a test message (e.g., “Hello”) to your bot on the connected platform to verify functionality.

Step 7: Optimization – Maximize Performance

Optimizing the Raspberry Pi environment ensures the bot remains responsive during resource-intensive tasks.

7.1 Enable Performance Mode (Pi 4)

Increase the CPU frequency on a Raspberry Pi 4:

sudo nano /boot/firmware/config.txt

Append the following lines to the bottom of the file:

arm_freq=1800
over_voltage=6
gpu_mem=16

Save and reboot via sudo reboot. (Note: Raspberry Pi 5 handles performance scaling automatically and does not require this step).

7.2 Configure Swap Space

Increase swap space to prevent out-of-memory errors during heavy browser automation:

sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile

Change CONF_SWAPSIZE=100 to CONF_SWAPSIZE=2048. Then, apply the changes:

sudo dphys-swapfile setup
sudo dphys-swapfile swapon

7.3 NVMe SSD Storage

Booting from an NVMe SSD via USB 3.0 drastically improves I/O speeds compared to MicroSD cards. This results in faster database reads and smoother browser automation.

Pro Tip: If using an NVMe drive, ensure your USB adapter supports UASP (USB Attached SCSI Protocol) for maximum data transfer speeds.

Troubleshooting & Common Errors

Issues often arise from network configurations or outdated dependencies.

Error: “Node.js version is too old”

Solution: OpenClaw strictly requires Node.js 20+. Verify your version with node --version. If it is outdated, re-run the Node.js installation commands in Step 2.

Error: “Gateway Pairing Failed”

Solution:

  1. Check internet connectivity: ping 8.8.8.8.
  2. Ensure the service is actually running: sudo systemctl status openclaw.
  3. Check if a local router firewall is blocking port 18789.

Error: “Out of Memory”

Solution: This occurs frequently on 2GB or 4GB RAM models. Ensure you have increased the swap file size as detailed in Step 7.2. If the issue persists with heavy workloads, a hardware upgrade to an 8GB model may be necessary.

SSH Connection Refused

Solution: If ssh [email protected] fails, access your home router’s admin panel to find the Pi’s assigned IP address and connect using that IP instead. Ensure the Pi is powered on and the green activity LED is flashing occasionally.

FAQ

Q: Can I run OpenClaw on a Raspberry Pi 3 or Zero?

A: It is not recommended. The Raspberry Pi 3 and Zero lack the RAM and CPU power required for modern Node.js applications and browser automation, leading to severe instability and crashes.

Q: Is my data sent to OpenClaw servers?

A: No. OpenClaw is self-hosted. Your data resides locally on your Raspberry Pi and is sent directly to your chosen LLM provider (like OpenAI) and the specific messaging platforms you configure.

Q: How do I update OpenClaw?

A: Navigate to the installation directory and pull the latest changes via Git, or re-run the install.sh script. Always back up your openclaw.json configuration file before performing major updates.

Q: What happens if the power goes out?

A: Because OpenClaw is configured as a systemd service (Step 5), it will automatically initialize and restart as soon as the Raspberry Pi boots up when power is restored.

You may also like

Subscribe
Notify of
guest

0 Comments
Newest
Oldest Most Voted