树莓派部署 OpenClaw

目标

在树莓派上运行持久化、全天候的 OpenClaw Gateway，一次性成本约 $35-80（无月费）。

适合以下场景：

• 24/7 个人 AI 助手
• 智能家居自动化中枢
• 低功耗、随时可用的 Telegram/WhatsApp 机器人

硬件要求

Pi 型号	内存	可用性	备注
Pi 5	4GB/8GB	最佳	速度最快，推荐首选
Pi 4	4GB	推荐	大多数用户的最佳性价比
Pi 4	2GB	可用	能跑，加交换空间
Pi 4	1GB	勉强	加交换空间后勉强可用，需最小配置
Pi 3B+	1GB	较慢	能跑但响应迟缓
Pi Zero 2 W	512MB	不推荐	内存不足，不建议使用

最低配置： 1GB 内存、1 核、500MB 磁盘 推荐配置： 2GB+ 内存、64 位 OS、16GB+ SD 卡（或 USB SSD）

所需物品

• 树莓派 4 或 5（推荐 2GB+）
• MicroSD 卡（16GB+）或 USB SSD（性能更好）
• 电源适配器（推荐官方 Pi 电源）
• 网络连接（有线或 WiFi）
• 约 30 分钟

1）刷写系统

使用 Raspberry Pi OS Lite（64 位）——无桌面的无头服务器模式。

1. 下载 Raspberry Pi Imager
2. 选择系统：Raspberry Pi OS Lite（64 位）
3. 点击齿轮图标（⚙️）预配置：
   • 设置主机名：gateway-host
   • 启用 SSH
   • 设置用户名/密码
   • 配置 WiFi（不用有线时）
4. 刷写到 SD 卡 / USB 驱动器
5. 插入并启动 Pi

2）通过 SSH 连接

ssh user@gateway-host
# 或使用 IP 地址
ssh user@192.168.x.x

3）系统初始配置

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装必要包
sudo apt install -y git curl build-essential

# 设置时区（对 cron/提醒功能很重要）
sudo timedatectl set-timezone Asia/Shanghai  # 改为你的时区

4）安装 Node.js 24（ARM64）

# 通过 NodeSource 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# 验证
node --version  # 应显示 v24.x.x
npm --version

5）添加交换空间（2GB 及以下内存必须执行）

交换空间可防止内存不足导致的崩溃：

# 创建 2GB 交换文件
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

6）安装 OpenClaw

方案 A：标准安装（推荐）

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

方案 B：可修改安装（适合折腾党）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link

可修改安装让你直接访问日志和代码——适合调试 ARM 特有问题。

7）运行引导程序

openclaw onboard --install-daemon

按照引导向导操作：

1. Gateway 模式： Local（本地）
2. 认证： 推荐 API 密钥（无头 Pi 上 OAuth 有时不稳定）
3. 频道： 从 Telegram 开始最简单
4. 守护进程： 是（systemd）

8）验证安装

# 检查状态
openclaw status

# 检查服务
sudo systemctl status openclaw

# 查看日志
journalctl -u openclaw -f

9）访问 OpenClaw 控制台

将 user@gateway-host 替换为你的 Pi 用户名和主机名或 IP 地址。

在你的电脑上，让 Pi 打印新鲜的控制台 URL：

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

命令会打印 Dashboard URL:。根据 gateway.auth.token 的配置，URL 可能是纯 http://127.0.0.1:18789/ 链接，也可能包含 #token=...。

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

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

然后在本地浏览器中打开打印出的控制台 URL。

如果 UI 要求认证，将 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）中的 token 粘贴到控制 UI 设置中。

需要随时随地访问，参见 Tailscale。

---

性能优化

使用 USB SSD（大幅提升性能）

SD 卡速度慢且容易磨损。USB SSD 可显著提升性能：

# 检查是否从 USB 启动
lsblk

参见 Pi USB 启动指南。

加速 CLI 启动（模块编译缓存）

在低性能 Pi 上，启用 Node 的模块编译缓存可加快 CLI 重复运行速度：

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc

说明：

• NODE_COMPILE_CACHE 加速后续运行（status、health、--help）。
• /var/tmp 比 /tmp 更能在重启后保留数据。
• OPENCLAW_NO_RESPAWN=1 避免 CLI 自重启带来的额外启动开销。
• 首次运行预热缓存，后续运行受益最大。

systemd 启动调优（可选）

如果这台 Pi 主要用于运行 OpenClaw，可添加 service drop-in 减少重启抖动并保持启动环境稳定：

sudo systemctl edit openclaw

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90

然后应用：

sudo systemctl daemon-reload
sudo systemctl restart openclaw

如有可能，将 OpenClaw 状态/缓存存储在 SSD 上，避免冷启动时 SD 卡随机 I/O 成为瓶颈。

降低内存占用

# 禁用 GPU 内存分配（无头模式）
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt

# 如不需要蓝牙，禁用它
sudo systemctl disable bluetooth

监控资源

# 查看内存
free -h

# 查看 CPU 温度
vcgencmd measure_temp

# 实时监控
htop

---

ARM 特有说明

二进制兼容性

大多数 OpenClaw 功能在 ARM64 上正常运行，但部分外部二进制可能需要 ARM 版本：

工具	ARM64 状态	备注
Node.js	完美支持	运行无问题
WhatsApp (Baileys)	完美支持	纯 JS，无问题
Telegram	完美支持	纯 JS，无问题
gog（Gmail CLI）	需检查	查找是否有 ARM 版本
Chromium（浏览器）	完美支持	sudo apt install chromium-browser

如果某个工具失败，检查其二进制是否有 ARM 版本。许多 Go/Rust 工具有；部分没有。

32 位 vs 64 位

务必使用 64 位 OS。 Node.js 和许多现代工具需要它。检查：

uname -m
# 应显示：aarch64（64 位）而非 armv7l（32 位）

---

推荐模型配置

由于 Pi 只是 Gateway（模型在云端运行），请使用基于 API 的模型：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514",
        "fallbacks": ["openai/gpt-4o-mini"]
      }
    }
  }
}

不要尝试在 Pi 上运行本地 LLM——即使是小模型也太慢了。让 Claude/GPT 承担计算工作。

---

开机自启

引导程序会自动配置，但可以手动验证：

# 检查服务是否已启用
sudo systemctl is-enabled openclaw

# 如未启用，手动启用
sudo systemctl enable openclaw

# 启动服务
sudo systemctl start openclaw

---

故障排查

内存不足（OOM）

# 检查内存
free -h

# 添加更多交换空间（参见步骤 5）
# 或减少 Pi 上运行的其他服务

性能缓慢

• 使用 USB SSD 替代 SD 卡
• 禁用不用的服务：sudo systemctl disable cups bluetooth avahi-daemon
• 检查 CPU 降频：vcgencmd get_throttled（应返回 0x0）

服务无法启动

# 查看日志
journalctl -u openclaw --no-pager -n 100

# 常见修复：重新构建
cd ~/openclaw  # 如果使用可修改安装
npm run build
sudo systemctl restart openclaw

ARM 二进制问题

如果某个工具报 "exec format error"：

1. 检查该二进制是否有 ARM64 版本
2. 尝试从源码编译
3. 或使用支持 ARM 的 Docker 容器

WiFi 断线

对于使用 WiFi 的无头 Pi：

# 禁用 WiFi 电源管理
sudo iwconfig wlan0 power off

# 永久生效
echo 'wireless-power off' | sudo tee -a /etc/network/interfaces

---

成本对比

方案	一次性成本	月费	备注
Pi 4（2GB）	~$45	$0	+ 电费（约 $5/年）
Pi 4（4GB）	~$55	$0	推荐
Pi 5（4GB）	~$60	$0	性能最好
Pi 5（8GB）	~$80	$0	过剩但面向未来
DigitalOcean	$0	$6/月	$72/年
Hetzner	$0	€3.79/月	~$50/年

回本周期： Pi 在约 6-12 个月内就能比云 VPS 更划算。

---

参考文档

• Linux 指南 —— 通用 Linux 配置
• DigitalOcean 指南 —— 云端替代方案
• Hetzner 指南 —— Docker 方案
• Tailscale —— 远程访问
• Nodes —— 将笔记本/手机与 Pi Gateway 配对