树莓派 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 更新系统

sudoapt update &&sudoapt upgrade -y 

1.2 安装基础工具

sudoaptinstall -y curlgit

二、安装 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

sudoapt-getinstall -y nodejs 

2.3 验证版本

node --version # 应显示 v22.x.xnpm --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://[email protected]/ git config --global url."https://".insteadOf ssh:// 

4.2 优化 Git 超时设置

git config --global http.postBuffer 524288000git config --global http.lowSpeedLimit 0git 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://[email protected]/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 安装

npminstall -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 配置消息频道

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

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

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: 重新加载 .bashrcsource ~/.bashrc # 方法2: 手动设置 PATH（当前会话）exportPATH=~/.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 版本 ≥ 22node --version # 2. 如果版本不足，升级curl -fsSL https://deb.nodesource.com/setup_22.x |sudo -E bash - sudoapt-getinstall -y nodejs # 3. 清理缓存并重新安装npm cache clean --force npm uninstall -g openclaw npminstall -g openclaw@latest 

Q4: npm 安装时报 [email protected]: Permission denied (publickey)

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

解决:

git config --global url."https://github.com/".insteadOf ssh://[email protected]/ 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 npminstall# 重启 Gateway systemctl --user restart openclaw-gateway 

Q9: 内存不足

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

解决:

# 查看内存使用free -h # 增加 swap 空间sudo fallocate -l 2G /swapfile sudochmod600 /swapfile sudomkswap /swapfile sudoswapon /swapfile echo'/swapfile none swap sw 0 0'|sudotee -a /etc/fstab 

十二、一键安装脚本

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

#!/bin/bashset -e echo"=========================================="echo"树莓派 Ubuntu 安装 OpenClaw"echo"=========================================="# 1. 安装基础依赖echo"[1/5] 安装基础依赖..."sudoapt update sudoaptinstall -y curlgit# 2. 安装 Node.js 22echo"[2/5] 安装 Node.js 22..."curl -fsSL https://deb.nodesource.com/setup_22.x |sudo -E bash - sudoapt-getinstall -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;thenecho'export PATH=~/.npm-global/bin:$PATH'>> ~/.bashrc fiexportPATH=~/.npm-global/bin:$PATH# 4. 配置 Gitecho"[4/5] 配置 Git..."git config --global url."https://github.com/".insteadOf ssh://[email protected]/ git config --global url."https://".insteadOf ssh:// git config --global http.postBuffer 524288000git config --global http.lowSpeedLimit 0git config --global http.lowSpeedTime 999999# 5. 安装 OpenClawecho"[5/5] 安装 OpenClaw..."npminstall -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""

十三、参考链接