树莓派 Ubuntu 24.04.3 LTS 安装 OpenClaw 指南

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 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://[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 安装

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

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

选择频道后，部分频道需要安装插件（从 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
# 查看技能状态和缺失依赖
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 安装时报 [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
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://[email protected]/
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 ""

十三、参考链接