树莓派 Ubuntu 24.04.3 LTS 安装 OpenClaw 操作说明

树莓派 Ubuntu 24.04.3 LTS 安装 OpenClaw 操作说明

环境说明

• 硬件: 树莓派 4B（ARM Cortex-A72, 4核, 3.5GB 内存）
• 系统: Ubuntu 24.04.3 LTS (Noble Numbat), ARM64 (aarch64)
• 存储: 16GB SD 卡（mmcblk0）
• 网络: WiFi (wlan0)
• OpenClaw 版本: 2026.2.3-1

前置条件

• 树莓派已安装 Ubuntu 24.04 LTS 并可以联网
• 有 sudo 权限
• 有 AI 模型账号（Anthropic / OpenAI / Qwen 等）
• 有另一台电脑的浏览器（用于 OAuth 授权和访问 Dashboard）

一、安装系统依赖

1.1 更新系统

sudo apt update && sudo apt upgrade -y

1.2 安装基础工具

sudo apt install -y curl git

二、安装 Node.js 22+

OpenClaw 要求 Node.js ≥ 22，Ubuntu 24.04 默认仓库只有 18.x，需要通过 NodeSource 安装。

2.1 添加 NodeSource 仓库

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –

2.2 安装 Node.js

sudo apt-get install -y nodejs

2.3 验证版本

node –version # 应显示 v22.x.x
npm –version # 应显示 10.x.x

三、配置 npm 全局安装目录

避免全局安装时需要 sudo 权限。

3.1 创建用户级全局目录

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

3.2 添加 PATH 环境变量

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3.3 验证配置

npm config get prefix
# 应显示: /home/<用户名>/.npm-global

四、配置 Git（解决网络问题）

树莓派在国内网络环境下访问 GitHub 可能不稳定，需要做以下优化。

4.1 配置 Git 使用 HTTPS（避免 SSH 权限问题）

git config –global url."https://github.com/".insteadOf ssh://git@github.com/
git config –global url."https://".insteadOf ssh://

4.2 优化 Git 超时设置

git config –global http.postBuffer 524288000
git config –global http.lowSpeedLimit 0
git config –global http.lowSpeedTime 999999

4.3 配置 Gitee 镜像（可选，解决 libsignal-node 下载问题）

如果 npm 安装时因 libsignal-node 从 GitHub 下载失败，可以将其重定向到 Gitee 镜像。
前提是你已在 Gitee 上 fork 或镜像了 whiskeysockets/libsignal-node 仓库。

git config –global url."https://gitee.com/<你的用户名>/libsignal-node.git".insteadOf "https://github.com/whiskeysockets/libsignal-node.git"
git config –global url."https://gitee.com/<你的用户名>/libsignal-node.git".insteadOf "ssh://git@github.com/whiskeysockets/libsignal-node.git"

4.4 配置 npm 使用国内镜像（可选，加速下载）

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

注意：如果使用国内镜像后安装出问题，可以切回官方源：
npm config set registry https://registry.npmjs.org/

4.5 验证 GitHub 连接

ping -c 3 github.com
# 应该能 ping 通，延迟约 100-200ms

五、安装 OpenClaw

5.1 安装

npm install -g openclaw@latest

安装过程可能需要几分钟，取决于网络速度。
如果出现 EBADENGINE 警告但安装继续，通常可以忽略。

5.2 验证安装

which openclaw
# 应显示: /home/<用户名>/.npm-global/bin/openclaw

openclaw –version
# 应显示版本号，如: 2026.2.3-1

六、配置 OpenClaw（onboard 向导详解）

运行配置向导：

openclaw onboard –install-daemon

向导会依次经过以下步骤：

6.1 安全警告确认

向导首先显示安全警告，提醒 OpenClaw 可以读取文件和执行操作，存在安全风险。

• 选择 Yes 继续

建议阅读安全文档：https://docs.openclaw.ai/gateway/security

6.2 选择 Onboarding 模式

• 选择 QuickStart（推荐）

QuickStart 默认配置：

• Gateway 端口：18789
• Gateway 绑定：Loopback (127.0.0.1)
• Gateway 认证：Token（默认）
• Tailscale 暴露：关闭

6.3 选择 AI 模型提供商

可选项：

• Qwen（通义千问）— 免费，适合国内用户
• Anthropic（Claude）— 推荐，效果最好
• OpenAI（GPT）

以 Qwen 为例，选择：

• Model/auth provider → Qwen
• Qwen auth method → Qwen OAuth

6.4 完成 OAuth 授权（重要）

向导会显示类似以下提示：

Open https://chat.qwen.ai/authorize?user_code=BZRMR5UA&client=qwen-code to approve access.
If prompted, enter the code BZRMR5UA.

操作步骤：

注意：授权码有时效性（约 5 分钟）。如果超时失败，向导会提示重试，重新运行即可获得新授权码。

授权成功后显示：

Default model set to qwen-portal/coder-model

6.5 选择默认模型

• 选择 Keep current (qwen-portal/coder-model) 或选择其他模型

6.6 配置消息频道

向导会显示所有可用频道的状态。可选择配置：

选择频道后，部分频道需要安装插件（从 npm 下载）。

可以先跳过频道配置，后续通过 openclaw onboard 重新配置。

6.7 安装 Skills（技能）

向导会列出可安装的技能。大部分技能需要 Homebrew 或 Go 等依赖。

树莓派上可以直接安装的技能：

• bird — 已成功安装
• clawhub — 技能注册中心，已成功安装
• mcporter — 已成功安装
• oracle — 已成功安装

需要额外依赖的技能（暂时跳过）：

• 需要 Homebrew 的技能：1password, github, obsidian 等
• 需要 Go 的技能：bear-notes, blogwatcher, sonoscli 等
• 需要 API Key 的技能：gemini, openai-whisper 等

可以选择 Skip for now 跳过，后续通过 openclaw doctor 查看并安装。

6.8 安装 Systemd 服务

向导会自动：

安装位置：~/.config/systemd/user/openclaw-gateway.service

6.9 Shell 自动补全

• 选择 Yes 启用 bash 自动补全
• 安装后需要重启 shell 或运行 source ~/.bashrc

6.10 完成配置

向导完成后会显示 Dashboard 链接：

Dashboard link (with token):
http://127.0.0.1:18789/?token=<你的token>

七、访问 Dashboard

树莓派没有桌面环境时，需要通过 SSH 隧道从其他电脑访问 Dashboard。

7.1 建立 SSH 隧道

在你的电脑上运行：

ssh -N -L 18789:127.0.0.1:18789 <用户名>@<树莓派IP>

例如：

ssh -N -L 18789:127.0.0.1:18789 june@192.168.0.113

7.2 打开 Dashboard

在电脑浏览器中打开：

http://localhost:18789/?token=<你的token>

token 在 onboard 完成时会显示，也可以在 ~/.openclaw/openclaw.json 中查看。

八、管理 Gateway 服务

8.1 查看服务状态

systemctl –user status openclaw-gateway

8.2 启动/停止/重启服务

# 启动
systemctl –user start openclaw-gateway

# 停止
systemctl –user stop openclaw-gateway

# 重启
systemctl –user restart openclaw-gateway

8.3 查看日志

journalctl –user -u openclaw-gateway -f

8.4 手动启动 Gateway（调试用）

openclaw gateway –port 18789 –verbose

九、常用命令

# 查看帮助
openclaw –help

# 查看版本
openclaw –version

# 重新运行配置向导
openclaw onboard

# 与助手对话
openclaw agent –message "你好" –thinking high

# 健康检查
openclaw doctor

# 安全审计
openclaw security audit –deep
openclaw security audit –fix

# 更新 OpenClaw
openclaw update

# 查看/安装技能
openclaw doctor # 查看技能状态和缺失依赖

# 配置 Web 搜索
openclaw configure –section web

十、配置文件说明

10.1 配置文件位置

10.2 最小配置示例

{
"agent": {
"model": "qwen-portal/coder-model"
}
}

10.3 完整配置参考

参见：https://docs.openclaw.ai/gateway/configuration

十一、常见问题及解决方案

Q1: openclaw: 未找到命令

原因: PATH 未配置或未生效。

解决:

# 方法1: 重新加载 .bashrc
source ~/.bashrc

# 方法2: 手动设置 PATH（当前会话）
export PATH=~/.npm-global/bin:$PATH

# 方法3: 使用完整路径
~/.npm-global/bin/openclaw –version

Q2: npm 安装时报 EACCES: permission denied

原因: npm 全局目录权限不足。

解决:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 然后重新运行 npm install -g openclaw@latest

Q3: npm 安装时报 ERR_MODULE_NOT_FOUND

原因: Node.js 版本过低或安装不完整。

解决:

# 1. 确认 Node.js 版本 ≥ 22
node –version

# 2. 如果版本不足，升级
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –
sudo apt-get install -y nodejs

# 3. 清理缓存并重新安装
npm cache clean –force
npm uninstall -g openclaw
npm install -g openclaw@latest

Q4: npm 安装时报 git@github.com: Permission denied (publickey)

原因: npm 的某些依赖通过 SSH 访问 GitHub，但未配置 SSH 密钥。

解决:

git config –global url."https://github.com/".insteadOf ssh://git@github.com/
git config –global url."https://".insteadOf ssh://

Q5: Qwen OAuth 超时失败

原因: 未在 5 分钟内完成浏览器授权。

解决:

# 重新运行 onboard，会生成新的授权码
openclaw onboard –install-daemon

提示：看到授权链接后，立即在浏览器中打开并完成授权。

Q6: Skills 安装失败提示 brew not installed

原因: 大部分技能依赖 Homebrew，但树莓派上 Homebrew 支持有限。

解决:

# 方案1: 安装 Homebrew（可选，ARM64 Linux 支持有限）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 方案2: 跳过这些技能，只使用不需要 brew 的技能
# bird, clawhub, mcporter, oracle 等可以直接安装

# 方案3: 通过 apt 手动安装对应工具
# 例如安装 Go: sudo apt install -y golang-go

Q7: Gateway 健康检查失败

原因: Gateway 服务未正常启动。

解决:

# 查看服务状态
systemctl –user status openclaw-gateway

# 查看日志
journalctl –user -u openclaw-gateway –no-pager | tail -20

# 重启服务
systemctl –user restart openclaw-gateway

# 或手动启动调试
openclaw gateway –port 18789 –verbose

Q8: Feishu 插件报错 Cannot find module 'zod'

原因: 插件依赖未完整安装。

解决:

# 进入插件目录安装依赖
cd ~/.openclaw/extensions/feishu
npm install

# 重启 Gateway
systemctl –user restart openclaw-gateway

Q9: 内存不足

原因: 树莓派 4B 只有 3.5GB 内存。

解决:

# 查看内存使用
free -h

# 增加 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

十二、一键安装脚本

将以下内容保存为 install-openclaw.sh，然后运行 bash install-openclaw.sh：

#!/bin/bash
set -e

echo "=========================================="
echo "树莓派 Ubuntu 安装 OpenClaw"
echo "=========================================="

# 1. 安装基础依赖
echo "[1/5] 安装基础依赖…"
sudo apt update
sudo apt install -y curl git

# 2. 安装 Node.js 22
echo "[2/5] 安装 Node.js 22…"
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –
sudo apt-get install -y nodejs

echo "Node.js: $(node –version)"
echo "npm: $(npm –version)"

# 3. 配置 npm 全局目录
echo "[3/5] 配置 npm…"
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

if ! grep -q "npm-global/bin" ~/.bashrc 2>/dev/null; then
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
fi
export PATH=~/.npm-global/bin:$PATH

# 4. 配置 Git
echo "[4/5] 配置 Git…"
git config –global url."https://github.com/".insteadOf ssh://git@github.com/
git config –global url."https://".insteadOf ssh://
git config –global http.postBuffer 524288000
git config –global http.lowSpeedLimit 0
git config –global http.lowSpeedTime 999999

# 5. 安装 OpenClaw
echo "[5/5] 安装 OpenClaw…"
npm install -g openclaw@latest

echo ""
echo "=========================================="
echo "安装完成！"
echo "=========================================="
echo ""
echo "Node.js: $(node –version)"
echo "npm: $(npm –version)"
echo "openclaw: $(which openclaw 2>/dev/null || echo '请运行 source ~/.bashrc')"
echo ""
echo "下一步:"
echo " source ~/.bashrc"
echo " openclaw onboard –install-daemon"
echo ""
echo "onboard 过程中需要在浏览器中完成 AI 模型授权。"
echo "onboard 完成后，通过 SSH 隧道访问 Dashboard:"
echo " ssh -N -L 18789:127.0.0.1:18789 $(whoami)@$(hostname -I | awk '{print $1}')"
echo " 然后打开: http://localhost:18789/"
echo ""

十三、参考链接