Skip to content

README.md

Latest commit

 

History

History
500 lines (337 loc) · 9.24 KB

README.md

File metadata and controls

500 lines (337 loc) · 9.24 KB


OpenClaw Raspberry Pi Secure Setup Guide

A comprehensive, security-first guide to install and run OpenClaw on Raspberry Pi OS (SSD or SD), using SSH keys, UFW, Fail2ban, and safe-by-default gateway settings.

Quick Start »

Security Baseline · Raspberry Pi OS Install · Pi Hardening · OpenClaw Install · Onboarding Settings · Verification

Table of Contents

Quick Start

If you already have Raspberry Pi OS running and SSH access working:

# update base OS
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y git curl ca-certificates ufw fail2ban unzip openssl

# enable firewall (SSH only)
sudo ufw allow OpenSSH
sudo ufw --force enable
sudo ufw status verbose

# enable fail2ban
sudo systemctl enable --now fail2ban

# install Node.js 22+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# install OpenClaw
sudo npm install -g openclaw@latest
openclaw --version

# run onboarding
openclaw onboard

During onboarding, bind the gateway to localhost only:

  • ✅ 127.0.0.1
  • ❌ not 0.0.0.0

Then install the Gateway service and run a security audit:

openclaw security audit --deep

About

This guide installs OpenClaw on a Raspberry Pi using a security-first baseline:

  • SSH keys-only access
  • Firewall enabled (deny inbound by default)
  • Fail2ban enabled (SSH brute-force protection)
  • OpenClaw Gateway bound to localhost (no LAN exposure)
  • Gateway auth token set to a strong random value
  • Credential directory permissions locked down

The goal is to build a stable “appliance-like” Pi host: boring, predictable, and safe.

Security Baseline

Non-negotiable defaults (recommended)

  • Do NOT expose OpenClaw Control UI directly to the internet.
  • Do NOT port-forward your router to the Raspberry Pi.
  • Bind OpenClaw gateway to 127.0.0.1 (localhost only).
  • Keep UFW enabled with default deny incoming.

Why “localhost only” matters

If the gateway binds to 0.0.0.0, anything on your network can attempt to connect. If misconfigured further, you could accidentally expose an admin surface externally.

Binding to 127.0.0.1 makes it private by default.

Prerequisites

Hardware

  • Raspberry Pi (Pi 4 recommended)
  • SD card OR USB SSD
  • Power supply
  • Ethernet or Wi-Fi

Your workstation

  • macOS / Linux / Windows machine
  • SSH client
  • Raspberry Pi Imager installed (GUI)

Raspberry Pi OS Install

Recommended OS

✅ Raspberry Pi OS Lite (64-bit)

It’s stable and minimal, and you can add only what you need later.

Flash OS with Raspberry Pi Imager (GUI)

  1. Open Raspberry Pi Imager

  2. Select:

    • OS: Raspberry Pi OS Lite (64-bit)
    • Storage: your SD card or SSD

  3. Open Advanced settings (gear icon) and set:

    • Hostname: e.g. clawpi
    • Enable SSH: ✅
    • Authentication: ✅ use password (temporary is fine)
    • Username: choose a dedicated user (example: openclaw)
    • Wi-Fi: configure if needed
    • Locale/timezone: optional

  4. Write image

  5. Boot your Pi

Tip: If you can’t SSH after boot, it’s usually Wi-Fi settings, hostname mismatch, or the wrong username.

First Boot Checklist

Once the Pi boots, SSH in:

ssh <user>@<hostname>.local

If .local does not resolve, use the IP from your router:

ssh <user>@192.168.x.x

Then confirm basics:

whoami
hostname
uname -a

Pi Hardening

SSH Key Authentication

On your workstation (Mac/Linux), create a key if needed:

ssh-keygen -t ed25519 -C "pi-admin"

Copy your public key to the Pi:

ssh-copy-id <user>@<pi-ip-or-hostname>

Verify it works:

ssh <user>@<pi-ip-or-hostname>

Disable password SSH (recommended once keys work)

Edit:

sudo nano /etc/ssh/sshd_config

Set:

PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes

Restart SSH:

sudo systemctl restart ssh

Firewall (UFW)

Install + enable:

sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw --force enable
sudo ufw status verbose

Expected:

  • Default deny incoming
  • SSH allowed

Fail2ban

Install + enable:

sudo apt install -y fail2ban
sudo systemctl enable --now fail2ban
sudo systemctl status fail2ban --no-pager

Swap

Raspberry Pi OS may use zram by default.

Check swap:

swapon --show
free -h

If swap exists (zram or swapfile), you're good.

Install Node.js 22+

Install Node.js 22 from NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

You should see Node v22.x.

Install OpenClaw

Install globally:

sudo npm install -g openclaw@latest
openclaw --version
openclaw --help

OpenClaw Onboarding Settings

Run onboarding:

openclaw onboard

If onboard is not available:

openclaw configure

Recommended secure choices

  • Gateway bind: ✅ 127.0.0.1
  • Gateway port: ✅ default is fine
  • Gateway auth: ✅ Token
  • Gateway token: ✅ long random token
  • Tailscale exposure: ✅ Off
  • Hooks: ✅ Skip for now
  • Skills: ✅ Skip for now (start minimal)

Fix short token warning (if audit reports it)

Generate a strong token:

openssl rand -hex 32

Set it:

openclaw config set gateway.auth.token "<PASTE_TOKEN_HERE>"

Restart gateway service after changes:

systemctl --user restart openclaw-gateway

Run as a Service

Onboarding will typically install the Gateway user service:

  • openclaw-gateway.service (systemd user service)

Check status:

systemctl --user status openclaw-gateway --no-pager

View logs:

journalctl --user -u openclaw-gateway -n 200 --no-pager

Restart service:

systemctl --user restart openclaw-gateway

Verification

Confirm the gateway is running

systemctl --user status openclaw-gateway --no-pager

Confirm it is localhost-only

ss -lntp | grep 18789 || true

Expected output includes:

  • 127.0.0.1:18789
  • [::1]:18789

If you see 0.0.0.0:18789, your gateway is exposed to LAN and must be fixed.

Security Audit

Run the deep audit:

openclaw security audit --deep

Expected:

  • 0 critical

Note:

  • gateway.trusted_proxies_missing is safe to ignore if you keep the UI local-only.
  • If you expose a Control UI through a reverse proxy later, configure gateway.trustedProxies.

Common Issues

Permission denied (publickey) when SSH'ing into the Pi

You are using the wrong username, or your public key was not copied to the Pi.

Fix:

ssh-copy-id <user>@<pi-ip-or-hostname>

UFW enable warning about disrupting SSH

This is normal.

Always allow SSH before enabling UFW:

sudo ufw allow OpenSSH
sudo ufw --force enable

Skills failing to install with EACCES permission errors

This usually means npm is trying to write to a system directory. For a minimal secure setup, skip skills until your base install is stable.

🦞 Supplemental Setup Guides

For detailed, step-by-step setup of specific features, refer to these reference guides:

Links

Disclaimer

This guide is provided as-is. You are responsible for reviewing and understanding commands before running them.

  • Disk flashing wipes data.
  • Security settings must be validated in your environment.
  • Do not expose admin/control surfaces to the internet without additional protections.