openclaw 部署在ubuntu 20.04系统操作步骤
OpenClaw 安装文档（Ubuntu 20.04 适配版）
文档说明
本文档基于 Ubuntu 20.04 系统，整理了 OpenClaw 完整安装流程、安装过程中遇到的核心问题及针对性解决方法，适配国内网络环境，可直接参考操作。
一、环境准备
1. 基础依赖安装
# 更新系统源sudoapt update &&sudoapt upgrade -y# 安装基础编译/网络工具sudoaptinstall-ygit build-essential curlwget libssl-dev libuv1-dev pkg-config zlib1g-dev 2. Node.js 环境安装（OpenClaw 依赖 Node.js ≥18）
# 添加 Node.js 22.x 源curl-fsSL https://deb.nodesource.com/setup_22.x |sudo-Ebash - # 安装 Node.jssudoaptinstall-y nodejs # 验证版本（需 ≥22.x）node--versionnpm--version二、OpenClaw 安装步骤
步骤 1：配置国内加速（解决 GitHub/NPM 网络问题）
# 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 全局安装权限sudochown-R$USER:$USER ~/.npm sudochown-R$USER:$USER /usr/local/lib/node_modules 步骤 2：升级 CMake（解决 llama.cpp 编译依赖）
Ubuntu 20.04 默认 CMake 3.16.3 低于 OpenClaw 要求的 3.19+，需手动升级：
# 1. 卸载旧版本sudoapt remove -y cmake # 2. 导入 Kitware 源 GPG 密钥wget-O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - |sudotee /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'|sudotee /etc/apt/sources.list.d/kitware.list >/dev/null # 4. 更新源并安装新版 CMakesudoapt update sudoaptinstall-y cmake # 5. 验证版本（需 ≥3.19） cmake --version步骤 3：全局安装 OpenClaw
# 清理 NPM 缓存npm cache clean --force# 安装 OpenClaw（带权限参数，避免编译报错）npminstall-g openclaw@latest --unsafe-perm=true --allow-root 步骤 4：修复 OpenClaw 命令软链接
安装完成后若提示 openclaw: command not found，需修复软链接：
# 1. 查找 OpenClaw 真实安装路径sudofind / -name"openclaw*"-type f 2>/dev/null |grep-E"bin/openclaw"# 2. 删除无效软链接（若存在）sudorm-f /usr/bin/openclaw # 3. 创建新软链接（替换为实际路径，示例路径：~/.npm-global/bin/openclaw）sudoln-s /home/你的用户名/.npm-global/bin/openclaw /usr/bin/openclaw # 4. 添加执行权限sudochmod +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/" 加速 |
四、验证安装 & 快速上手
1. 验证 OpenClaw 可用性
# 查看版本 openclaw --version# 查看命令帮助（输出完整帮助信息即为成功） openclaw 2. 初始化配置（绑定国内 AI 模型：通义千问）
# 启动交互式配置向导 openclaw onboard 关键配置项：
- 模型提供商：选择
dashscope（通义千问）； - API Key：填写阿里云百炼平台获取的 API Key；
- 消息渠道：选择
web（国内适配性最好）； - 网关端口：默认 18789，直接回车。
3. 启动网关 & 测试消息
# 后台启动网关 openclaw gateway --daemon# 查看网关状态 openclaw gateway status # 发送测试消息（替换为你的 Channel ID） openclaw message send --to"你的Channel ID"--message"测试通义千问回复"五、核心总结
- 安装核心痛点：CMake 版本过低、GitHub/NPM 国内网络限制、软链接配置错误；
- 关键修复步骤：升级 CMake 到 3.19+、配置国内镜像加速、修复 openclaw 命令软链接；
- 国内适配建议：优先选择
dashscope（通义千问）作为 AI 模型，web作为消息渠道，无需代理即可使用。
