How to Set Up OpenClaw on a Raspberry Pi (Complete Guide)

By /

> *A $35 computer. Your own AI assistant. Zero recurring cloud fees.* That’s the pitch — and it’s real. By the end of this guide, you’ll have a private, always-on OpenClaw agent running on a Raspberry Pi, connected to Telegram, and smart enough to answer questions, check the weather, and run skills 24/7 from your home network.

No cloud subscriptions. No data leaving your control unless you choose it. Just a tiny Linux box doing big things.

What You’ll Need

Hardware

  • ✅ [Raspberry Pi 4 (4GB) or Pi 5 (4GB/8GB)]# — Pi 4 is the sweet spot; Pi 3B+ will work but sluggishly
  • ✅ [MicroSD card — 32GB Class 10 or better]# (a USB SSD improves performance dramatically if you have one)
  • ✅ Official Raspberry Pi power supply (underpowered PSUs cause weird crashes)
  • ✅ Ethernet cable or reliable 2.4/5GHz WiFi

Software & Accounts

  • ✅ A computer with Raspberry Pi Imager installed
  • ✅ An API key from Anthropic, OpenAI, or another supported LLM provider
  • ✅ A Telegram account (free)
  • ✅ About 30–45 minutes

> Don’t have a Pi? No problem. Everything in this guide works on any Ubuntu 22.04/24.04 VPS too. [Hostinger’s VPS starts at a few dollars a month]# and you can skip straight to Step 2.

Step 1: Prepare Your Raspberry Pi

Flash the OS

Use Raspberry Pi OS Lite (64-bit). The desktop is dead weight for a headless server.

1. Open Raspberry Pi Imager 2. Choose Raspberry Pi OS Lite (64-bit) under “Raspberry Pi OS (other)” 3. Click the ⚙️ gear icon before writing — this is where the magic happens: – Set hostname: gateway-host – ✅ Enable SSH – Set a strong username and password – Configure your WiFi SSID and password (or skip if using Ethernet) 4. Write to your SD card, insert into the Pi, and power on

Connect via SSH

Wait about 60 seconds for first boot, then:

ssh pi@gateway-host.local
# If mDNS doesn't work, use the IP address:
ssh pi@192.168.x.x

Update and Install Dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential

Set your timezone (important for reminders and cron):

sudo timedatectl set-timezone America/Chicago
# Replace with your actual timezone, e.g. Europe/London

Step 2: Install Node.js

OpenClaw requires Node 22 LTS or newer (Node 24 recommended). Don’t use the default Raspberry Pi OS version — it’s ancient.

The cleanest approach for a home server is installing directly from NodeSource:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

Verify it worked:

node --version
# Should print v24.x.x
npm --version

Add Swap (Critical for Pi 4 2GB or Less)

If you’re on a 2GB model, add swap before installing anything Node-heavy. This prevents silent OOM crashes:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

4GB models can skip this, but it doesn’t hurt to add it anyway.

Step 3: Install OpenClaw

The recommended path is the installer script, which handles Node detection and launches onboarding:

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

Alternatively, install via npm directly:

npm install -g openclaw@latest

Confirm the install:

openclaw --version

You should see a version number like 2026.x.x. If the command isn’t found, your npm global bin path isn’t in $PATH:

export PATH="$(npm prefix -g)/bin:$PATH"
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Speed Up CLI on Low-Power Pis

This one-time setup dramatically speeds up subsequent openclaw invocations by caching compiled Node modules:

cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc

Step 4: Configure Your API Key

OpenClaw’s config lives at ~/.openclaw/openclaw.json. Run the onboarding wizard to generate it interactively:

openclaw onboard --install-daemon

The wizard will ask for:

  • Gateway mode: choose Local
  • API key: paste your Anthropic or OpenAI key
  • Channels: we’ll add Telegram manually in the next step
  • Daemon: say Yes (this sets up systemd auto-start)

If you’d rather set it up manually, the config structure looks like this:

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-20250514",
        fallbacks: ["openai/gpt-4o-mini"]
      }
    }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_BOT_TOKEN_HERE",
      dmPolicy: "pairing"
    }
  }
}

> Pro tip: Don’t try to run a local LLM on the Pi itself. Even small models are too slow. Let Claude or GPT-4o handle the heavy lifting via API — the Pi is just the gateway.

Step 5: Connect Telegram

This is where it gets fun. In about 5 minutes you’ll have a private Telegram bot that talks back.

Create Your Bot with BotFather

1. Open Telegram and search for @BotFather (verified account with blue checkmark) 2. Send /newbot 3. Pick a name (e.g. “My Home Assistant”) 4. Pick a username ending in bot (e.g. myhome_assistant_bot) 5. BotFather gives you a token like 1234567890:ABCDefGhIJKlmNoPQRstUVwxYZ

Save that token. You won’t see it again unless you ask BotFather with /token.

Add the Token to Your Config

Edit ~/.openclaw/openclaw.json and add the token:

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "1234567890:ABCDefGhIJKlmNoPQRstUVwxYZ"
openclaw config set channels.telegram.dmPolicy pairing

Or edit the file directly with nano ~/.openclaw/openclaw.json.

Approve the First Message

Start the gateway (we’ll make it persistent in Step 6), then message your new bot in Telegram. The first DM triggers a pairing flow:

openclaw gateway start

In a second SSH window, watch for the pairing code:

openclaw pairing list telegram

Approve it:

openclaw pairing approve telegram <CODE>

Pairing codes expire after 1 hour, so approve promptly. Now DM your bot — it should respond!

Step 6: Start the Gateway + Make It Persistent with pm2

The gateway needs to survive reboots. The onboarding wizard can set up systemd, but if you prefer pm2 (popular in the Node.js world and easier to manage):

Install pm2

npm install -g pm2

Start OpenClaw with pm2

pm2 start "openclaw gateway start" --name openclaw

Persist Across Reboots

pm2 startup
# pm2 will print a command — copy and run it (it starts with "sudo env PATH=...")
pm2 save

Now check that it’s running:

pm2 status
pm2 logs openclaw

To check gateway health at any time:

openclaw gateway status

If you used the systemd path from the wizard instead, you can verify it with:

sudo systemctl status openclaw

Step 7: Install Your First Skill — Weather

Skills are the plugins that give your OpenClaw agent new abilities. Clawhub.ai is the public registry where you can browse hundreds of community-built skills.

Install the weather skill via npx:

npx clawhub install weather

Or install the ClawHub CLI globally first for faster repeated use:

npm install -g clawhub
clawhub install weather

The skill installs into your workspace’s skills/ folder. Skills are loaded at the start of the next session — either restart the gateway or start a fresh conversation.

Test It

DM your Telegram bot:

What's the weather in Seattle?

You should get a current weather report back. If it works, your Pi is fully operational as a home AI assistant.

To browse more skills:

clawhub search "calendar"
clawhub search "home automation"
clawhub search "github"

Troubleshooting

openclaw: command not found

Your npm global bin path isn’t in $PATH. Fix:

export PATH="$(npm prefix -g)/bin:$PATH"
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Gateway Crashes or Won’t Start

Check the logs:

pm2 logs openclaw --lines 50
# or if using systemd:
journalctl -u openclaw --no-pager -n 100

Common cause: malformed openclaw.json. Run the doctor:

openclaw doctor
openclaw doctor --fix

Out of Memory (OOM Kills)

Symptom: gateway mysteriously stops, especially under load.

free -h
dmesg | grep -i 'oom\|killed'

Fix: add or increase swap (see Step 2). Also disable services you don’t need:

sudo systemctl disable bluetooth cups avahi-daemon

Telegram Bot Doesn’t Respond

1. Confirm the gateway is running: pm2 status 2. Confirm the bot token is set correctly in config 3. Check if pairing was approved: openclaw pairing list telegram 4. Watch live logs while messaging the bot: pm2 logs openclaw

Slow CLI Startup

The Pi’s SD card I/O is the culprit. Two fixes: 1. Enable the Node compile cache (see Step 3) 2. Boot from a USB SSD instead of SD card — this is a huge performance improvement

Check if the Pi is thermal-throttling:

vcgencmd get_throttled
# 0x0 means no throttling — anything else means check your cooling

What’s Next?

You’ve got a working home AI server. Here’s where to take it:

More Skills: Visit clawhub.ai and browse the registry. There are skills for GitHub issue management, calendar access, home automation hooks, web research, and more. Install with clawhub install .

More Channels: OpenClaw supports Discord, Slack, WhatsApp, Signal, and a dozen others. Add them to openclaw.json under channels..

Remote Access: Install Tailscale on the Pi and your phone/laptop for secure remote access to your home assistant from anywhere — no port forwarding required.

Multiple Agents: You can configure multiple agent profiles in OpenClaw, each with different system prompts, skills, and even different AI models — routing different Telegram bots or channels to different personalities.

VPS as an Alternative: If you ever want cloud uptime guarantees without managing hardware, the same guide works on any Ubuntu VPS. [Hostinger’s VPS plans]# start cheap, and your configuration is fully portable.

Ready to explore skills? Check out our complete OpenClaw skills roundup → where we review the most useful community-built skills for developers and home users.

*Have a question or hit a snag? Drop a comment below — I read every one.*

> 📣 Disclosure: This post contains affiliate links. If you purchase through one of those links, EasyOutcomes.ai may earn a small commission at no extra cost to you. We only recommend hardware and services we’ve actually tested. All opinions are our own.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top