树莓派（Raspberry Pi）

在树莓派上运行持久化、全天候的 OpenClaw Gateway。由于树莓派只负责 gateway 工作（模型通过 API 在云端运行），即使是入门款树莓派也能轻松胜任——在家"养一只龙虾"，成本极低。

前置条件

• 树莓派 4 或 5，2 GB+ 内存（推荐 4 GB）
• MicroSD 卡（16 GB+）或 USB SSD（性能更好）
• 官方树莓派电源适配器
• 网络连接（有线或 WiFi）
• 64 位树莓派 OS（必须——不要用 32 位版本）
• 约 30 分钟

配置步骤

第一步：刷写系统

使用 Raspberry Pi OS Lite（64 位）——无头服务器不需要桌面环境。

1. 下载 Raspberry Pi Imager。
2. 选择系统：Raspberry Pi OS Lite（64 位）。
3. 在设置对话框中预配置：
   • 主机名：gateway-host
   • 启用 SSH
   • 设置用户名和密码
   • 配置 WiFi（如果不用有线网络）
4. 刷写到 SD 卡或 U 盘，插入后启动树莓派。

第二步：SSH 连接

ssh user@gateway-host

第三步：更新系统

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

# 设置时区（对定时任务和提醒很重要）
sudo timedatectl set-timezone Asia/Shanghai

第四步：安装 Node.js 24

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

第五步：添加 Swap（2 GB 内存及以下的设备必做）

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

# 降低 swappiness，适合低内存设备
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

第六步：安装 OpenClaw

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

第七步：运行初始配置向导

openclaw onboard --install-daemon

按照向导操作。无头设备推荐使用 API key 而非 OAuth。Telegram 是最容易上手的渠道，龙虾入驻第一个家推荐从这里开始。

第八步：验证运行状态

openclaw status
sudo systemctl status openclaw
journalctl -u openclaw -f

第九步：访问控制界面

在你的电脑上，从树莓派获取仪表板 URL：

ssh user@gateway-host 'openclaw dashboard --no-open'

然后在另一个终端创建 SSH 隧道：

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

在本地浏览器打开打印出的 URL。如需随时远程访问，参考 Tailscale 集成。

性能优化建议

使用 USB SSD — SD 卡速度慢且容易磨损。USB SSD 能大幅提升性能。参考 树莓派 USB 启动指南。

启用模块编译缓存 — 在低性能树莓派上加速 CLI 重复调用：

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || 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

减少内存占用 — 无头部署时，释放 GPU 内存并禁用不需要的服务：

echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
sudo systemctl disable bluetooth

常见问题排查

内存不足 — 用 free -h 确认 Swap 已激活。禁用不需要的服务（sudo systemctl disable cups bluetooth avahi-daemon）。只使用基于 API 的模型。

性能慢 — 改用 USB SSD 替代 SD 卡。用 vcgencmd get_throttled 检查 CPU 降频（应返回 0x0）。

服务无法启动 — 用 journalctl -u openclaw --no-pager -n 100 查看日志，运行 openclaw doctor --non-interactive。

ARM 二进制问题 — 如果某个 skill 报"exec format error"，检查该二进制是否有 ARM64 版本。用 uname -m 验证架构（应显示 aarch64）。

WiFi 断线 — 禁用 WiFi 省电管理：sudo iwconfig wlan0 power off。

下一步

• Channels — 接入 Telegram、WhatsApp、Discord 等
• Gateway 配置 — 所有配置选项
• 更新 — 保持 OpenClaw 最新版本