nyrn
/
openclaw
mirror of https://github.com/openclaw/openclaw.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
openclaw/docs/zh-CN/platforms/raspberry-pi.md

11 KiB
Raw Blame History

read_when summary title x-i18n
在 Raspberry Pi 上设置 OpenClaw
在 ARM 设备上运行 OpenClaw
构建一个低成本、始终在线的个人 AI
在 Raspberry Pi 上运行 OpenClaw（低预算自托管方案） Raspberry Pi
generated_at model provider source_hash source_path workflow
2026-03-16T06:24:58Z gpt-5.4 openai 3106dea63b5a548622b82e3090e7fdb7f748b96bf0e23893496f1b60c095334a platforms/raspberry-pi.md 15

在 Raspberry Pi 上运行 OpenClaw

目标

在 Raspberry Pi 上以 约 35–80 美元的一次性成本（无月费）运行一个持久化、始终在线的 OpenClaw Gateway 网关。

非常适合：

  • 7×24 个人 AI 助手
  • 家庭自动化中枢
  • 低功耗、始终可用的 Telegram/WhatsApp bot

硬件要求

Pi 型号 RAM 可用？ 说明
Pi 5 4GB/8GB ✅ 最佳 最快，推荐
Pi 4 4GB ✅ 良好 适合大多数用户的最佳平衡点
Pi 4 2GB ✅ 可以 可用，建议加 swap
Pi 4 1GB ⚠️ 紧张 配合 swap 和最小化配置可行
Pi 3B+ 1GB ⚠️ 较慢 可用，但反应迟缓
Pi Zero 2 W 512MB ❌ 不推荐

最低规格： 1 GB RAM、1 核、500 MB 磁盘
推荐规格： 2 GB 以上 RAM、64 位 OS、16 GB 以上 SD 卡（或 USB SSD）

你需要准备的内容

  • Raspberry Pi 4 或 5（推荐 2 GB 以上）
  • MicroSD 卡（16 GB 以上）或 USB SSD（性能更好）
  • 电源（推荐使用官方 Pi 电源）
  • 网络连接（以太网或 Wi‑Fi）
  • 约 30 分钟

1）刷写 OS

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

  1. 下载 Raspberry Pi Imager
  2. 选择 OS：Raspberry Pi OS Lite（64 位）
  3. 点击齿轮图标（⚙️）进行预配置：
    • 设置主机名：gateway-host
    • 启用 SSH
    • 设置用户名/密码
    • 配置 Wi‑Fi（如果不使用以太网）
  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 America/Chicago  # 改成你的时区

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）添加 swap（对于 2 GB 或更低内存很重要）

swap 可以防止内存不足崩溃：

# 创建 2 GB swap 文件
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 key（在无头 Pi 上 OAuth 可能比较挑环境）
  3. 渠道： 最容易上手的是 Telegram
  4. 守护进程： 是（systemd）

8）验证安装

# 检查状态
openclaw status

# 检查服务
sudo systemctl status openclaw

# 查看日志
journalctl -u openclaw -f

9）访问 OpenClaw Dashboard

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

在你的电脑上，让 Pi 打印一个新的 Dashboard 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

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

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

如需始终在线的远程访问，请参阅 Tailscale。

性能优化

使用 USB SSD（显著提升）

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

# 检查是否从 USB 启动
lsblk

设置方法请参阅 Pi USB boot guide。

加快 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，可以添加一个服务 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 成为瓶颈。

关于 Restart= 策略如何帮助自动恢复： systemd can automate service recovery。

减少内存占用

# 禁用 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 (browser) ✅ sudo apt install chromium-browser

如果某个 skill 失败，请检查其二进制文件是否有 ARM 构建版本。许多 Go/Rust 工具都有；有些则没有。

32 位与 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

# 添加更多 swap（见第 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 二进制问题

如果某个 skill 因 “exec format error” 失败：

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

Wi‑Fi 掉线

对于通过 Wi‑Fi 运行的无头 Pi：

# 禁用 Wi‑Fi 省电
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/年

回本周期： 与云 VPS 相比，一台 Pi 大约 6–12 个月即可回本。

另请参阅