树莓派 Ubuntu 24.04.3 LTS 系统部署 OpenClaw 网关的完整流程。涵盖环境准备、Node.js 22+ 安装、npm 全局目录配置、Git 网络优化、OpenClaw 安装与 onboard 向导配置、SSH 隧道访问 Dashboard 以及服务管理命令。重点解决国内网络环境下 GitHub 访问及 libsignal-node 下载问题，并提供常见问题排查方案与一键安装脚本。
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git
OpenClaw 要求 Node.js ≥ 22，Ubuntu 24.04 默认仓库只有 18.x，需要通过 NodeSource 安装。
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version # 应显示 v22.x.x
npm --version # 应显示 10.x.x
避免全局安装时需要 sudo 权限。
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm config get prefix # 应显示：/home/<用户名>/.npm-global
树莓派在国内网络环境下访问 GitHub 可能不稳定，需要做以下优化。
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
如果 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"
npm config set registry https://registry.npmmirror.com
注意：如果使用国内镜像后安装出问题，可以切回官方源：
npm config set registry https://registry.npmjs.org/
ping -c 3 github.com # 应该能 ping 通，延迟约 100-200ms
npm install -g openclaw@latest
安装过程可能需要几分钟，取决于网络速度。如果出现
EBADENGINE警告但安装继续，通常可以忽略。
which openclaw # 应显示：/home/<用户名>/.npm-global/bin/openclaw
openclaw --version # 应显示版本号，如：2026.2.3-1
运行配置向导：
openclaw onboard --install-daemon
向导会依次经过以下步骤：
向导首先显示安全警告，提醒 OpenClaw 可以读取文件和执行操作，存在安全风险。
QuickStart 默认配置：
可选项：
以 Qwen 为例，选择：
向导会显示类似以下提示：
Open https://chat.qwen.ai/authorize?user_code=BZRMR5UA&client=qwen-code to approve access. If prompted, enter the code BZRMR5UA.
操作步骤：
BZRMR5UA）注意：授权码有时效性（约 5 分钟）。如果超时失败，向导会提示重试，重新运行即可获得新授权码。
授权成功后显示：
Default model set to qwen-portal/coder-model
向导会显示所有可用频道的状态。可选择配置：
| 频道 | 说明 | 配置难度 |
|---|---|---|
| Telegram | 最简单，注册 @BotFather 即可 | 简单 |
| 使用自己的号码，建议用独立号码 | 中等 | |
| Discord | 支持很好 | 中等 |
| Feishu（飞书） | 需要安装插件 | 中等 |
| Slack | 支持 Socket Mode | 中等 |
| Signal | 需要 signal-cli | 复杂 |
选择频道后，部分频道需要安装插件（从 npm 下载）。
可以先跳过频道配置，后续通过
openclaw onboard重新配置。
向导会列出可安装的技能。大部分技能需要 Homebrew 或 Go 等依赖。
树莓派上可以直接安装的技能：
需要额外依赖的技能（暂时跳过）：
可以选择 Skip for now 跳过，后续通过
openclaw doctor查看并安装。
向导会自动：
安装位置：~/.config/systemd/user/openclaw-gateway.service
source ~/.bashrc向导完成后会显示 Dashboard 链接：
Dashboard link (with token): http://127.0.0.1:18789/?token=<你的 token>
树莓派没有桌面环境时，需要通过 SSH 隧道从其他电脑访问 Dashboard。
在你的电脑上运行：
ssh -N -L 18789:127.0.0.1:18789 <用户名>@<树莓派 IP>
例如：
ssh -N -L 18789:127.0.0.1:18789 [email protected]
在电脑浏览器中打开：
http://localhost:18789/?token=<你的 token>
token 在 onboard 完成时会显示，也可以在
~/.openclaw/openclaw.json中查看。
systemctl --user status openclaw-gateway
# 启动
systemctl --user start openclaw-gateway
# 停止
systemctl --user stop openclaw-gateway
# 重启
systemctl --user restart openclaw-gateway
journalctl --user -u openclaw-gateway -f
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
| 文件/目录 | 说明 |
|---|---|
~/.openclaw/openclaw.json | 主配置文件 |
~/.openclaw/workspace/ | Agent 工作目录 |
~/.openclaw/agents/main/sessions/ | 会话数据 |
~/.openclaw/extensions/ | 已安装的插件 |
~/.openclaw/credentials/ | 频道认证数据 |
~/.config/systemd/user/openclaw-gateway.service | systemd 服务文件 |
{"agent":{"model":"qwen-portal/coder-model"}}
openclaw: 未找到命令原因: PATH 未配置或未生效。
解决:
# 方法 1: 重新加载 .bashrc
source ~/.bashrc
# 方法 2: 手动设置 PATH（当前会话）
export PATH=~/.npm-global/bin:$PATH
# 方法 3: 使用完整路径
~/.npm-global/bin/openclaw --version
EACCES: permission denied原因: npm 全局目录权限不足。
解决:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 然后重新运行 npm install -g openclaw@latest
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
[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://
原因: 未在 5 分钟内完成浏览器授权。
解决:
# 重新运行 onboard，会生成新的授权码
openclaw onboard --install-daemon
提示：看到授权链接后，立即在浏览器中打开并完成授权。
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
原因: 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
Cannot find module 'zod'原因: 插件依赖未完整安装。
解决:
# 进入插件目录安装依赖
cd ~/.openclaw/extensions/feishu
npm install
# 重启 Gateway
systemctl --user restart openclaw-gateway
原因: 树莓派 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 ""
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online