档介绍了在 Ubuntu 20.04 系统上部署 OpenClaw 的完整流程。主要步骤包括安装基础依赖、配置 Node.js 22.x 环境、升级 CMake 至 3.19+ 以满足编译要求，以及配置国内镜像加速解决网络问题。通过全局安装 OpenClaw 并修复命令软链接完成部署。最后提供常见问题排查表及验证方法，支持绑定通义千问等国内 AI 模型进行网关测试。
本文档基于 Ubuntu 20.04 系统，整理了 OpenClaw 完整安装流程、安装过程中遇到的核心问题及针对性解决方法，适配国内网络环境，可直接参考操作。
# 更新系统源
apt update && apt upgrade -y
apt install -y git build-essential curl wget libssl-dev libuv1-dev pkg-config zlib1g-dev
# 添加 Node.js 22.x 源
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# 安装 Node.js
sudo apt install -y nodejs
# 验证版本（需 ≥22.x）
node --version
npm --version
# 1. NPM 切换国内镜像
npm config set registry https://mirrors.cloud.tencent.com/npm/
# 2. Git 配置 GitHub 加速（自动替换 SSH 为 HTTPS + 镜像）
git config --global url."https://github.com/".insteadOf "[email protected]:"
git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/"
# 3. 修复 NPM 全局安装权限
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER /usr/local/lib/node_modules
Ubuntu 20.04 默认 CMake 3.16.3 低于 OpenClaw 要求的 3.19+，需手动升级：
# 1. 卸载旧版本
sudo apt remove -y cmake
# 2. 导入 Kitware 源 GPG 密钥
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
# 3. 添加 Kitware 源（适配 Ubuntu 20.04/focal）
echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ focal main' | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
# 4. 更新源并安装新版 CMake
sudo apt update
sudo apt install -y cmake
# 5. 验证版本（需 ≥3.19）
cmake --version
# 清理 NPM 缓存
npm cache clean --force
# 安装 OpenClaw（带权限参数，避免编译报错）
npm install -g openclaw@latest --unsafe-perm=true --allow-root
安装完成后若提示 openclaw: command not found，需修复软链接：
# 1. 查找 OpenClaw 真实安装路径
sudo find / -name "openclaw*" -type f 2>/dev/null | grep -E "bin/openclaw"
# 2. 删除无效软链接（若存在）
sudo rm -f /usr/bin/openclaw
# 3. 创建新软链接（替换为实际路径，示例路径：~/.npm-global/bin/openclaw）
sudo ln -s /home/你的用户名/.npm-global/bin/openclaw /usr/bin/openclaw
# 4. 添加执行权限
sudo chmod +x /home/你的用户名/.npm-global/bin/openclaw
# 5. 验证安装（输出版本号即为成功）
openclaw --version
| 问题现象 | 核心原因 | 解决方法 |
|---|---|---|
npm error [email protected]: Permission denied (publickey) | NPM 拉取依赖时使用 SSH 协议，无 GitHub 密钥权限 | 执行 git config --global url."https://github.com/".insteadOf "[email protected]:"，强制改用 HTTPS 协议 |
CMake Error: CMake 3.19 or higher is required | Ubuntu 20.04 自带 CMake 版本过低 | 按「步骤 2」升级 CMake 到 3.19+ |
openclaw: command not found | 软链接指向无效路径 | 按「步骤 4」重新创建软链接，指向实际安装路径 |
node-llama-cpp 编译失败 | 缺少编译依赖或 CMake 版本不足 | 1. 安装依赖：sudo apt install -y build-essential libssl-dev libuv1-dev pkg-config zlib1g-dev2. 升级 CMake 到 3.19+ |
npm install 卡顿/依赖下载超时 | 国内访问 GitHub/NPM 官方源慢 | 配置国内镜像： 1. npm config set registry https://mirrors.cloud.tencent.com/npm/2. git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/" |
libsignal-node 拉取失败 | GitHub 网络限制 | 执行 git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/" 加速 |
# 查看版本
openclaw --version
# 查看命令帮助（输出完整帮助信息即为成功）
openclaw
# 启动交互式配置向导
openclaw onboard
关键配置项：
dashscope（通义千问）；web（国内适配性最好）；# 后台启动网关
openclaw gateway --daemon
# 查看网关状态
openclaw gateway status
# 发送测试消息（替换为你的 Channel ID）
openclaw message send --to "你的 Channel ID" --message "测试通义千问回复"
dashscope（通义千问）作为 AI 模型，web 作为消息渠道，无需代理即可使用。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online