RPi 5 Deployment Plan¶

Step-by-step guide to deploy the Raspberry Pi 5 as an OpenClaw AI assistant node.

Hardware Summary¶

Component	Model	Notes

Remote Preparation (Before Physical Access)¶

Complete these tasks remotely before the deployment day:

1. Generate Tailscale Auth Key¶

# SSH to VPS
ssh vps

# Generate pre-auth key (expires in 1 hour, single use)
docker exec headscale headscale preauthkeys create --expiration 1h

# Save the key! You'll need it during RPi 5 setup

2. Add OPNsense DHCP Reservation¶

Login to OPNsense via Tailscale: https://100.79.230.235
Services > DHCPv4 > LAN
Add reservation: MAC -> 192.168.0.20 (get MAC from RPi 5 board sticker)

3. Flash Raspberry Pi OS to SD Card¶

# Use Raspberry Pi Imager on MacBook
# Settings:
#   OS: Raspberry Pi OS Lite (64-bit, Debian Bookworm)
#   Hostname: rpi5
#   Username: augusto
#   Enable SSH (password authentication initially)
#   WiFi: skip (Ethernet only)
#   Locale: America/Asuncion

4. Pre-generate Credentials¶

# OpenClaw API keys (Anthropic, OpenAI, etc.)
# Store in Vaultwarden before going home

Pre-Deployment Checklist¶

Hardware Ready¶

[ ] RPi 5 board with active cooler attached
[ ] 32GB SD card flashed with Pi OS (hostname: rpi5, user: augusto)
[ ] 27W PSU available
[ ] Ethernet cable to MokerLink switch

Network Ready¶

[ ] MokerLink switch port available
[ ] OPNsense DHCP reservation: 192.168.0.20 -> RPi 5 MAC
[ ] Pi-hole DNS entry: rpi5.home -> 192.168.0.20

Software Ready¶

[ ] Tailscale auth key from Headscale (generate day-of, 1h expiry)
[ ] OpenClaw API keys saved in Vaultwarden

On-Site Deployment (~20-30 min)¶

Step 1: Physical Setup¶

Insert flashed SD card into RPi 5
Connect Ethernet cable to MokerLink switch
Connect 27W PSU
Wait for boot (~60 seconds)

Step 2: Initial SSH Access¶

# Copy SSH key (from MacBook)
ssh-copy-id [email protected]

# Verify key-based login
ssh rpi5

Step 3: Run Ansible Playbooks (in order)¶

cd ~/homelab/ansible

# 1. Tailscale first (mesh connectivity = backup access)
ansible-playbook -i inventory.yml playbooks/tailscale.yml -l rpi5

# 2. Common setup (base packages, UFW, disables password auth)
ansible-playbook -i inventory.yml playbooks/common.yml -l rpi5

# 3. OpenClaw (Node.js + OpenClaw)
ansible-playbook -i inventory.yml playbooks/openclaw.yml -l rpi5

Step 4: OpenClaw Initial Setup¶

# SSH into RPi 5
ssh rpi5

# Run onboarding wizard
openclaw onboard --install-daemon

# Configure API keys (Anthropic, OpenAI, etc.)
# Follow the interactive prompts

# Connect messaging channels
openclaw channels login

# Test the gateway
openclaw gateway --port 18789

Step 5: Enable Systemd Service¶

# Enable and start OpenClaw as a service
sudo systemctl enable --now openclaw

# Verify it's running
sudo systemctl status openclaw

Verification¶

SSH via Tailscale¶

# After Tailscale enrollment, update SSH config with Tailscale IP
# Then verify:
ssh rpi5

OpenClaw Gateway¶

# From RPi 5
curl http://localhost:18789

# From another Tailscale node
curl http://<rpi5-tailscale-ip>:18789

UFW Rules¶

# Expected rules:
sudo ufw status

# Should show:
# 22/tcp    ALLOW  Anywhere
# 18789/tcp ALLOW  Anywhere
# Anywhere on tailscale0 ALLOW  Anywhere

Service Survives Reboot¶

sudo reboot

# Wait ~60 seconds, then:
ssh rpi5
sudo systemctl status openclaw
curl http://localhost:18789

Post-Deployment¶

1. Update SSH Config with Tailscale IP¶

Edit ~/.ssh/config on MacBook:

# RPi 5 - OpenClaw (Tailscale)
Host rpi5
    HostName <rpi5-tailscale-ip>
    User augusto
    IdentityFile ~/.ssh/id_ed25519

2. Update Ansible Inventory¶

Edit ansible/inventory.yml — replace LAN IP with Tailscale IP for the rpi5 host.

3. Add Uptime Kuma Monitor¶

Via web UI at https://status.cronova.dev:

Name: OpenClaw Gateway
Type: HTTP(s)
URL: <http://:18789
Interval: 60s

4. Update Hardware Doc¶

In docs/architecture/hardware.md, change RPi 5 status from "Pending setup" to "Active".

5. Add Pi-hole DNS Entry¶

# SSH to docker-vm, edit Pi-hole config
ssh docker-vm
docker exec -it pihole bash

# Add DNS entry in /etc/pihole/pihole.toml under dns.hosts:
# { addr = "192.168.0.20", names = ["rpi5.home"] }

pihole reloaddns

Troubleshooting¶

RPi 5 Not Booting¶

# Check LED status:
# - Solid red: power OK
# - Blinking green: SD card activity
# - No green blink: SD card not detected or bad image

# Re-flash SD card if needed
# Try a different SD card

Can't SSH¶

# Verify RPi 5 got DHCP lease
# Check OPNsense: Services > DHCPv4 > Leases

# Try direct IP
ssh [email protected]

# If password auth disabled too early, need keyboard+monitor

OpenClaw Won't Start¶

# Check Node.js
node --version  # Should be v22.x

# Check OpenClaw
openclaw --version

# Check service logs
journalctl -u openclaw -f

# Try running manually
openclaw gateway --port 18789

Tailscale Won't Connect¶

# Check status
tailscale status

# Re-authenticate (get new key from Headscale)
ssh vps
docker exec headscale headscale preauthkeys create --expiration 1h

# On RPi 5
sudo tailscale up --login-server=https://hs.cronova.dev --authkey=<new-key> --reset

Rollback Plan¶

If something goes wrong:

OpenClaw issues: sudo systemctl restart openclaw or reinstall via Ansible
OS issues: Re-flash SD card (no persistent data on RPi 5)
Network issues: Connect keyboard+monitor, check /etc/network/ config
Tailscale issues: Re-enroll with new auth key

Time Estimate¶

Phase	Estimate

| Physical setup | 5 min | | SSH + key copy | 2 min | | Ansible playbooks | 10-15 min | | OpenClaw setup | 5-10 min | | Verification | 5 min | | Total | ~20-30 min |

References¶

hardware.md - Full hardware specs
mobile-homelab.md - Mobile kit (RPi 5 migration history)
ansible/playbooks/openclaw.yml - OpenClaw Ansible playbook
Raspberry Pi 5 Specs
OpenClaw Docs