树莓派 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.

操作步骤：

1. 在另一台电脑或手机浏览器中打开上述链接
2. 登录你的通义千问账号
3. 如果页面提示输入授权码，输入显示的代码（如 BZRMR5UA）
4. 点击"授权"或"同意"
5. 回到终端，向导会自动检测到授权完成

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

授权成功后显示：

Default model set to qwen-portal/coder-model

6.5 选择默认模型

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

6.6 配置消息频道

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

频道	说明	配置难度
Telegram	最简单，注册 @BotFather 即可	简单
WhatsApp	使用自己的号码，建议用独立号码	中等
Discord	支持很好	中等
Feishu（飞书）	需要安装插件	中等
Slack	支持 Socket Mode	中等
Signal	需要 signal-cli	复杂

选择频道后，部分频道需要安装插件（从 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 服务

向导会自动：

1. 启用 systemd lingering（防止退出登录后服务被停止）
2. 安装 Gateway 为 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 配置文件位置

文件/目录	说明
~/.openclaw/openclaw.json	主配置文件
~/.openclaw/workspace/	Agent 工作目录
~/.openclaw/agents/main/sessions/	会话数据
~/.openclaw/extensions/	已安装的插件
~/.openclaw/credentials/	频道认证数据
~/.config/systemd/user/openclaw-gateway.service	systemd 服务文件

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 ""

---

十三、参考链接

资源	链接
官方文档	https://docs.openclaw.ai
GitHub 仓库	https://github.com/openclaw/openclaw
快速开始	https://docs.openclaw.ai/start/getting-started
配置参考	https://docs.openclaw.ai/gateway/configuration
Linux 平台	https://docs.openclaw.ai/platforms/linux
安全指南	https://docs.openclaw.ai/gateway/security
技能文档	https://docs.openclaw.ai/tools/skills
Gateway 健康检查	https://docs.openclaw.ai/gateway/health
远程访问	https://docs.openclaw.ai/gateway/remote
频道配置	https://docs.openclaw.ai/channels
NodeSource	https://github.com/nodesource/distributions