OpenClaw 树莓派 / 香橙派部署实践

在笔记本或台式电脑上部署 OpenClaw，适合在电脑前的协作。但对于随时随地的远程协作，要求电脑 7x24 不关机，就不那么方便了。在树莓派、香橙派这类微型 ARM 服务器上部署，在这种场景下非常适合。
本文记录了在树莓派 5 和香橙派 5 Ultra（Rockchip RK3588）上部署 OpenClaw 的完整过程，以及途中踩过的坑和解决方法。可作为在各类 ARM 开发板上部署 OpenClaw 的参考。

前置阅读：本文的飞书接入、模型配置等通用部分，与另一篇 [OpenClaw 部署实践]共享，建议先阅读该文再看本篇。

涉及设备：

•树莓派 5，8GB（Raspberry Pi OS 64-bit）

•香橙派 5 Ultra，Rockchip RK3588（Armbian / Debian）

1 场景与硬件选型

1.1 为什么用 ARM 开发板

OpenClaw 本质是一个长期运行的网关服务，对硬件要求并不高：

指标	要求
CPU	任意主流 ARM64 或 x86_64
内存	建议 4GB 以上
存储	建议 16GB 以上（系统 + Node.js + OpenClaw）
网络	需要稳定的外网访问能力
功耗	7x24 运行，ARM 开发板 5~15W 很适合

树莓派和香橙派这类开发板的优势：体积小、功耗低、便宜、足够运行一个个人 AI 助手。相比一直开着电脑，省电又安静。

1.2 设备概况

树莓派 5（Raspberry Pi 5）

•CPU：Broadcom BCM2712，4 核 A76 @ 2.4GHz

•内存：8GB LPDDR4

•系统：Raspberry Pi OS 64-bit（Debian 12）

•用途：7x24 文件服务器 + OpenClaw 跳板机

香橙派 5 Ultra（OrangePi 5 Ultra）

•CPU：Rockchip RK3588，8 核（4×A76 + 4×A55）@ 2.4GHz

•内存：8GB / 16GB LPDDR4

•系统：Armbian（Debian 12）或官方 OrangePi OS

•用途：OpenClaw 主运行机

RK3588 的性能比树莓派 5 强不少，如果只跑一个 OpenClaw 实例，香橙派 5 Ultra 体验会更好。

2 事前准备

2.1 新建独立用户

不要用 root 或现有用户运行 OpenClaw。创建一个独立用户，权限隔离，环境独立：

sudo adduser openclawsudo usermod -aG sudo openclaw

2.2 确认 SSH 真实登录

重要：必须通过 SSH 真实登录 openclaw 用户操作，不能用 su 或 sudo su 切换。

用 SSH 直接登录：

ssh openclaw@<your-pi-ip>

然后确认用户状态：

loginctl user-status $(whoami)

正常输出：

openclaw (1001)    State: active Sessions: *3598  Linger: no    Unit: user-1001.slice

如果出现错误或用户状态异常，后续安装 systemd 服务时会被跳过，服务无法自启动。

2.3 网络连通性检查

在开始安装之前，先确认开发板能访问外网：

curl -I https://openclaw.aicurl -I https://api.minimax.chat   # 后续接模型需要

如果在国内访问 GitHub/Homebrew/MiniMax 等海外资源非常慢或不通，需要提前配置代理或换国内镜像。香橙派这类设备往往没有 GUI，全程靠 SSH 操作，网络不通会很麻烦。

2.4 两台设备之间的 SSH 跳转

如果你和大多数用户一样，家里的网络没有公网 IP，无法直接 SSH 到内网设备，可以借助一台有公网 IP 的云服务器做跳板机：

你的电脑  ──→  公网跳板机（云服务器）  ──→  内网树莓派  ──→  内网香橙派

网络拓扑（本文实际环境）：

节点	IP	端口	用户	用途
公网跳板机	跳板机IP	跳板机端口	user	SSH 跳板
内网树莓派	192.168.x.x	端口号	openclaw	跳板 + 文件服务
内网香橙派	192.168.x.x	端口号	openclaw	OpenClaw 主运行机

跳板 SSH 命令（两跳）：

# 从跳板机登录内网树莓派ssh -p 端口号 openclaw@192.168.x.x# 从你的电脑通过跳板登录内网香橙派ssh -p 跳板机端口 user@跳板机IP   # 先登跳板ssh -p 端口号 openclaw@192.168.x.x   # 再登香橙派

懒人脚本（需要跳板机已安装 sshpass）：

sshpass -p '跳板密码' ssh -o StrictHostKeyChecking=no -p 跳板机端口 跳板用户@跳板IP \  'sshpass -p "香橙派密码" ssh -o StrictHostKeyChecking=no openclaw@香橙派IP'

提示：首次连接会提示确认主机密钥，输入 yes 即可。-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null 可以跳过这一步，适合自动化脚本。

3 安装 Node.js 环境

3.1 为什么不用系统自带的 Node

大多数 ARM 开发板默认安装的 Node.js 版本较老（Debian 12 通常是 Node 18），而 OpenClaw 要求 Node.js ≥ 22。使用 nvm（Node Version Manager）安装指定版本是最佳选择。

3.2 安装 nvm 并配置

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bashsource ~/.bashrc

3.3 安装 Node.js 22

nvm install 22node --version   # 确认 v22.x.x

3.4 换 npm 国内镜像（国内开发者建议）

npm config set registry https://registry.npmmirror.com

3.5 Homebrew 安装（可选）

如果后续需要用 ClawdHub 安装社区 Skills，需要 Homebrew（Linuxbrew）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# 配置国内镜像export HOMEBREW_API_DOMAIN=https://mirrors.aliyun.com/homebrew-bottles/apiexport HOMEBREW_BREW_GIT_REMOTE=https://mirrors.aliyun.com/homebrew/brew.gitexport HOMEBREW_CORE_GIT_REMOTE=https://mirrors.aliyun.com/homebrew/homebrew-core.gitexport HOMEBREW_BOTTLE_DOMAIN=https://mirrors.aliyun.com/homebrew/home-bottles# 写入 bashrc 持久化echo '' >> ~/.bashrcecho 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrceval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"# 重新登录后安装基础依赖brew updatebrew install gcc build-essential

如果不装 Skills，这步可以跳过，OpenClaw 核心功能不需要 Homebrew。

4 安装 OpenClaw

4.1 一键安装

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

国内如果 raw.githubusercontent.com 访问不畅，可以试试：bash curl -fsSL https://ghproxy.com/https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash 或配置代理。

4.2 基础配置向导

openclaw onboard --install-daemon

配置向导会依次询问：

1风险认知 — 确认了解安全相关设置

2模型选择 — 选择 MiniMax / OpenAI / Anthropic 等

3API Key — 填入模型提供商的 Key

4网关端口 — 默认 18789，直接回车即可

5通信通道 — 暂时跳过，后续单独配置飞书

本篇以 MiniMax 为例。MiniMax API 分两个端点： - 国际版：api.minimax.io/anthropic（Anthropic 兼容） - 国内版（通过 MiniMax 火山引擎）：api.minimax.chat/v1（OpenAI 兼容）国内用户请认准 api.minimax.chat/v1，这个端点对应的是你在 minimax 开发者平台创建的 API Key。

配置完成后，向导会输出摘要，确认无误回车即可。

4.3 手动安装 systemd 服务

如果你没有在向导中安装守护进程，可以手动补上：

openclaw gateway install

如果系统检测到没有 GUI，会提示通过 SSH 端口转发访问 Dashboard，照做即可。

4.4 验证基础运行

# 查看网关状态openclaw gateway status# 启动网关openclaw gateway --port 18789# 用 doctor 做全面体检openclaw doctor

如果看到 Gateway listening 且 doctor 无异常，说明基础安装成功。

5 飞书接入配置

飞书接入的具体步骤在 OpenClaw 部署实践](./OpenClaw(1)部署实践.md)) 中有详细说明，这里只提在 ARM 设备上操作的注意事项。

5.1 安装飞书插件

openclaw plugins install @m1heng-clawd/feishusystemctl --user restart openclaw-gateway

5.2 配置飞书渠道

通过命令行配置：

openclaw config set channels.feishu.enabled trueopenclaw config set channels.feishu.appId "cli_xxxxxxxxxxxx"openclaw config set channels.feishu.appSecret "你的AppSecret"

也可以直接编辑配置文件 ~/.openclaw/openclaw.json，在 channels 下添加：

{  "channels": {    "feishu": {      "enabled": true,      "dmPolicy": "pairing",      "accounts": {        "main": {          "appId": "cli_xxxxxxxxxxxx",          "appSecret": "你的AppSecret"        }      }    }  }}

注意：appId 和 appSecret 必须写在 accounts.main 下面，这是 OpenClaw 飞书渠道的配置规范，写错位置会导致服务启动后飞书完全无法连接，且不报任何明显错误。

5.3 飞书开放平台配置

1事件订阅 → 选择长连接接收事件（WebSocket 模式，不需要公网 IP）

2添加事件：im.message.receive_v1（必须）

事件订阅顺序很重要：必须先让 OpenClaw 的飞书渠道配置生效（配置写入配置文件且 gateway 重启），再去飞书开放平台保存长连接设置。如果 gateway 还没跑起来就保存长连接，飞书会连不上网关导致保存失败。

5.4 自启动配置（systemd）

确保服务开机自启：

systemctl --user enable openclaw-gateway.servicesystemctl --user status openclaw-gateway.service

显示 enabled 且 active (running) 即为正常。

常用管理命令：

systemctl --user status openclaw-gateway       # 查看状态systemctl --user restart openclaw-gateway     # 重启服务journalctl --user -u openclaw-gateway -f      # 实时查看日志

6 踩坑实录：遇到的问题与解决

以下是我们实际部署过程中遇到的真实问题及解决方法，按发现顺序排列。

6.1 gateway.mode 缺失导致服务无法启动

问题现象：

Gateway start blocked: set gateway.mode=local (current: unset)or pass --allow-unconfigured.

原因：配置文件 ~/.openclaw/openclaw.json 中缺少 gateway.mode 字段，OpenClaw 为安全起见默认阻止启动。

解决：在配置文件中添加：

{  "gateway": {    "mode": "local"  }}

如果通过 openclaw config set 设置：

openclaw config set gateway.mode local

排查经验：如果服务突然起不来，优先查看 journalctl --user -u openclaw-gateway -n 50 的输出，通常第一条错误就是根因。

6.2 飞书 channel 配置结构错误

问题现象：gateway 正常启动，但飞书发消息完全没有反应，也没有任何报错日志。

原因：将飞书的 appId 和 appSecret 直接写在 channels.feishu 下面：

// ❌ 错误写法"channels": {  "feishu": {    "enabled": true,    "appId": "cli_xxx",       // 错误：不在正确位置    "appSecret": "xxx"        // 错误：不在正确位置  }}

OpenClaw 配置校验不会报这个错，但飞书连接会静默失败。

解决：正确结构：

// ✅ 正确写法"channels": {  "feishu": {    "enabled": true,    "dmPolicy": "pairing",    "accounts": {      "main": {        "appId": "cli_xxx",        "appSecret": "xxx"      }    }  }}

排查经验：飞书接入不工作时，先检查配置结构是否完全符合官方文档的格式，不要凭经验猜测。配置错误时 gateway 不会报错，但飞书长连接会悄悄断掉。

6.3 MiniMax API 端点用错

问题现象：gateway 运行正常，但每次对话都返回：

HTTP 401 authentication_error: invalid api key

排查过程：

# 在香橙派上直接测试 APIcurl -X POST https://api.minimax.io/anthropic/v1/messages \  -H "x-api-key: 你的Key" \  -H "anthropic-version: 2023-06-01" \  -d '{"model":"MiniMax-M2.7","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'# 返回：{"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

确认了 Key 本身没问题后，检查配置文件中填的端点：

// ❌ 用成了国际版端点，但 Key 是国内版的"baseUrl": "https://api.minimax.io/anthropic"// ✅ 国内版 Key 正确写法"baseUrl": "https://api.minimax.chat/v1"

根因：MiniMax 有两个 API 体系：

端点	协议	适用场景
`api.minimax.io/anthropic`	Anthropic 兼容	国际版账号
`api.minimax.chat/v1`	OpenAI 兼容	国内（火山引擎）版账号

国内开发者平台（platform.minimaxi.com）创建的 Key，必须用 api.minimax.chat/v1 端点。两者不能混用。

解决：修改配置文件中的 baseUrl：

{  "models": {    "providers": {      "minimax": {        "baseUrl": "https://api.minimax.chat/v1",        "api": "openai-completions"      }    }  }}

6.4 MiniMax API Key 本身无效

问题现象：同样的 401 错误，换了端点仍然无效。

排查方法：在香橙派上直接用 curl 调 API：

curl -X POST https://api.minimax.chat/v1/chat/completions \  -H "Content-Type: application/json" \  -H "Authorization: Bearer 你的Key" \  -d '{"model":"MiniMax-M2.7","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

如果返回：

{"error":{"message": "invalid api key"}}

说明 Key 本身无效——可能是过期、被删除、或者复制时少了字符。请到 MiniMax 开发者平台重新确认或新建一个 Key。

6.5 两跳网络环境下部署工具的不便

问题现象：通过 SSH 跳板操作时，很多交互式安装脚本（如 brew install、安装向导的交互提示）用起来非常麻烦。

解决经验：

1提前在跳板机上安装 sshpass，这样可以在本地写脚本传到远程执行，而不用交互：bash # 在跳板机上安装 sudo apt-get install sshpass

2文件传输用 scp，本地写好脚本/配置文件，传到远程再执行：bash sshpass -p '跳板密码' scp -P 跳板机端口本地文件跳板用户@跳板IP:/tmp/文件

3复杂的远程操作尽量包装成脚本，避免多次 SSH 连接和交互式提示。

6.6 OrangePi 5 Ultra RK3588 架构兼容性问题

问题背景：Rockchip RK3588 使用的 aarch64 架构与 x86_64 不同，部分软件没有预编译包，需要从源码编译。

经验：

•Node.js：通过 nvm 安装的 Node.js 是官方提供的预编译版，RK3588 正常兼容，无需额外处理。

•OpenClaw：npm 全局包方式安装，架构兼容。

•Homebrew：Linuxbrew 在 aarch64 上安装可能遇到部分公式编译失败。如果不需要社区 Skills，可以跳过 Homebrew 安装，纯靠 Node.js 生态足够。

•其他依赖：如果后续安装的 Skills 需要编译原生模块（如 bcrypt、sharp），需要提前装好编译工具链：bash sudo apt-get install build-essential python3

6.7 systemd service 正常退出后不自动重启

问题现象：SSH 保持连接时飞书机器人正常工作；断开 SSH 后服务自动停止，之后再也不自动拉起。反复出现。

排查过程：

1检查 systemd 服务状态：systemctl --user status openclaw-gateway → 显示 inactive (dead)，没有任何崩溃日志

2检查日志：gateway 收到 SIGTERM 后 exit 0，之后没有后续启动记录

3检查 systemd 配置：Restart=always 已配置，NRestarts=0

根因：OpenClaw 安装向导自动生成的 service 文件中包含：

SuccessExitStatus=0143

这行告诉 systemd："退出码是 0 或 143 也算成功，不需要重启"。当 gateway 因为某些原因主动退出时（如 SSH 会话结束时触发的清理），systemd 收到退出码 0，认为"一切正常"，不触发 Restart=always 策略，导致服务永久 dead。

解决：删除 service 文件中的 SuccessExitStatus 行：

sed -i '/^SuccessExitStatus/d' ~/.config/systemd/user/openclaw-gateway.servicesystemctl --user daemon-reloadsystemctl --user restart openclaw-gateway

验证：

# 确认 SuccessExitStatus 已删除（无输出即正常）grep SuccessExitStatus ~/.config/systemd/user/openclaw-gateway.service# 确认服务正常运行systemctl --user status openclaw-gateway# 确认 NRestarts 会累加（主动杀进程测试）systemctl --user stop openclaw-gatewaysleep 6systemctl --user status openclaw-gateway# 应自动变为 active (running)

排查经验：SSH 断开后服务不恢复，Restart=always 也没用，先查 SuccessExitStatus。另一个常见原因是 loginctl enable-linger 未启用（用户登出后 systemd user session 会被清理），不过本例中 linger 已是启用状态。

7 完整配置示例

以下是我们最终使用的 ~/.openclaw/openclaw.json 完整配置（已脱敏），可直接参考：

{  "agents": {    "defaults": {      "model": {        "primary": "minimax/MiniMax-M2.7"      },      "compaction": {        "mode": "safeguard"      },      "maxConcurrent": 4,      "subagents": {        "maxConcurrent": 8      }    }  },  "messages": {    "ackReactionScope": "group-mentions"  },  "commands": {    "native": "auto",    "nativeSkills": "auto",    "restart": true,    "ownerDisplay": "raw"  },  "gateway": {    "mode": "local",    "auth": {      "mode": "token",      "token": "你的gateway-token"    }  },  "channels": {    "feishu": {      "enabled": true,      "dmPolicy": "pairing",      "accounts": {        "main": {          "appId": "cli_xxxxxxxxxxxx",          "appSecret": "你的AppSecret"        }      }    }  },  "models": {    "providers": {      "minimax": {        "baseUrl": "https://api.minimax.chat/v1",        "api": "openai-completions",        "apiKey": "你的MiniMaxAPIKey",        "models": [          {            "id": "MiniMax-M2.7",            "name": "MiniMax M2.7",            "reasoning": false,            "input": ["text"]          }        ]      }    }  }}

8 存储性能优化：SD 卡 → NVMe SSD 迁移

本优化针对香橙派 5 Ultra（或其他使用 SD 卡作为系统盘、有 NVMe SSD 可用的设备）。如果你的设备没有 SSD 或系统盘 IO 本身够用，可以跳过本节。

8.1 问题背景

香橙派默认使用 eMMC/SD 卡作为系统盘，OpenClaw 运行在此盘上。OpenClaw 的日志、数据库、临时文件等操作会产生大量随机 IO，SD 卡（eMMC）的随机 IOPS 和吞吐量远低于 NVMe SSD，长期运行可能导致：

•响应延迟不稳定

•SD 卡寿命加速损耗

•高频日志写入阻塞影响整体吞吐

优化目标：将 /home/openclaw 迁移至 NVMe SSD，通过 Bind Mount 实现，零侵入 OpenClaw 原有配置。

8.2 存储现状确认

# 查看当前 /home/openclaw 挂载位置df -h /home/openclaw# 查看 SSD 挂载情况df -h /mnt/nvme0*# 查看 OpenClaw 数据量（估算迁移时间）du -sh /home/openclaw

8.3 操作步骤

第一步 — 同步数据到 SSD

# 创建目标目录mkdir -p /mnt/nvme0/openclaw# 同步数据（-a 保留权限/时间，-H 保留硬链接，-A 保留 ACL，-X 保留扩展属性）rsync -aHAX /home/openclaw/ /mnt/nvme0/openclaw/# 验证两边数据一致du -sh /home/openclaw /mnt/nvme0/openclaw

⚠️ 同步期间建议停止 OpenClaw 服务，避免数据变动：bash killall -9 openclaw openclaw-gateway

第二步 — 配置 fstab 自动挂载

# 备份原 fstabsudo cp /etc/fstab /etc/fstab.bak# 添加 bind mount 条目echo "/mnt/nvme0/openclaw /home/openclaw none bind 00" | sudo tee -a /etc/fstab

第三步 — 启用 Bind Mount 并验证

# 立即启用（无需重启）sudo mount --bind /mnt/nvme0/openclaw /home/openclaw# 验证挂载：/home/openclaw 应指向 /dev/nvme0n1p1df -h /home/openclaw# 验证 OpenClaw 数据完整ls /mnt/nvme0/openclaw/.openclaw/# 重启 OpenClawkillall -9 openclaw openclaw-gatewaysleep 2openclaw gateway --port 18789 &

第四步 — 重启验证

sudo reboot

重启后确认： - df -h /home/openclaw 显示 /dev/nvme0n1p1（SSD）✅ - df -h / 显示 /dev/mmcblk1p2（SD 卡，rootfs 未变）✅ - OpenClaw 正常服务 ✅

8.4 原理说明

Bind Mount 是 Linux 将目录/文件绑定到另一路径的机制，绑定后两个路径访问同一份数据（本例中即 SSD 数据）。

/mnt/nvme0/openclaw  ←── bind mount ──→  /home/openclaw       ↑                                    ↑    SSD 真实存储                   OpenClaw 读写入口

为什么不直接 mv？ mv 会改变系统路径，需要同步修改 OpenClaw 配置和其他依赖路径的服务账号配置。Bind Mount 零侵入，原有配置不动。

空间释放原理：Bind mount 是「覆盖」而非「移动」。原 SD 卡上的数据被遮住（不可见）但仍存在。真正释放空间需要重启后不再挂载 SD 卡或格式化 SD 卡。

8.5 后续清理（可选）

确认 SSD 启动正常后，可释放 SD 卡空间：

# 查看 SD 卡占用df -h /# 格式化 SD 卡 root 分区（会清除所有数据，慎用）sudo mkfs.ext4 -F /dev/mmcblk1p2

⚠️ 注意：/boot 分区在 SD 卡上，格式化前需确保 /boot 有替代方案，否则系统无法启动。

8.6 性能对比

指标	SD 卡（eMMC）	NVMe SSD
顺序读	~100 MB/s	~3500 MB/s
顺序写	~50 MB/s	~3000 MB/s
随机读 IOPS	~10K	~500K+
随机写 IOPS	~1K	~500K+

对于 OpenClaw 这种高频小文件读写场景，SSD 可带来数量级的 IOPS 提升。

9 总结

9.1 部署检查清单

步骤	操作	验证方式
1	创建 openclaw 独立用户	`loginctl user-status`
2	安装 Node.js 22+	`node --version`
3	安装 OpenClaw	`openclaw --version`
4	运行配置向导	`openclaw onboard`
5	配置飞书渠道	检查配置文件结构
6	安装 systemd 服务	`systemctl --user enable`
7	配置飞书开放平台	长连接 + 事件订阅
8	验证全链路	飞书发消息给机器人

9.2 关键经验

1gateway.mode 必须配置，缺失会直接阻止启动

2飞书配置结构必须规范，写错位置静默失败

3MiniMax API 端点必须和 Key 类型匹配，国内版用 api.minimax.chat/v1

4systemd 服务需要用户真实登录，不是 su 切过去的那种

5两跳网络提前准备脚本，避免交互式操作折磨

6先让 gateway 跑起来，再去飞书配长连接，顺序很重要

9.3 香橙派 5 Ultra vs 树莓派 5 选型建议

对比项	香橙派 5 Ultra	树莓派 5
CPU 性能	RK3588 8核，强	BCM2712 4核，中
内存	8/16/32GB	4/8GB
功耗	~15W	~5-8W
社区生态	较小	非常大
系统支持	Armbian/Debian	Raspberry Pi OS
价格	稍高	低
推荐场景	性能优先	功耗/体积优先

OpenClaw 本身对性能要求不高，两台都能流畅运行。香橙派 5 Ultra 优势在于 CPU 强，如果还想在机器上跑别的（如轻量编译、媒体服务等），体验会更好。