OpenClaw安装终极指南!

OpenClaw安装终极指南 (Ubuntu版)

适用系统：Ubuntu 20.04 / 22.04 / 24.04 (Server/Desktop)

核心痛点解决：Node.js 版本强制升级、PATH 环境变量刷新、静默安装失败排查。

第一阶段：环境硬要求检查

在开始之前，请确保满足以下硬性指标，否则后续步骤必败：

内存：≥ 2GB (推荐 4GB+)

磁盘：≥ 5GB 可用空间

网络：能访问GitHub 和 NodeSource (国内服务器建议配置加速源)

核心依赖：Node.js ≥ 22.0.0 (这是2026版本的死命令，v20/v18 均无法运行)

第二阶段：标准化安装流程

步骤1：系统更新与基础工具安装

首先清理旧环境并安装编译工具，防止后续npm install 时因缺少 make/g++ 而报错。

sudo apt update && sudo apt upgrade -y

sudo apt install -y curl git build-essential ca-certificates

步骤2：强制安装 Node.js v22

注意：不要使用apt install nodejs，因为 Ubuntu 自带源通常只有 v18 或 v20。必须使用 NodeSource 源。

执行以下命令一键切换至v22：

# 1. 下载并运行 NodeSource 设置脚本 (指定 v22.x)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 2. 安装 Node.js (这将自动替换旧版本)

sudo apt-get install -y nodejs

# 3. 验证版本 (必须看到 v22.x.x)

node -v

npm -v

输出类似如下:

v22.22.1

10.9.4

步骤3：安装openclaw

# 1. 创建目录并进入

mkdir -p ~/openclaw-setup && cd ~/openclaw-setup

# 2. 切换为国内镜像源(加速关键)

执行以下命令，将npm 源切换到淘宝/腾讯云镜像，速度会快几十倍：

npm config set registry https://registry.npmmirror.com

#3. 清除缓存并重试

npm cache clean --force

#4. 使用sudo 强制全局安装

这将确保openclaw 被正确安装到系统路径（通常是 /usr/local/bin 或 /usr/bin），所有用户可用。

sudo npm install -g openclaw@latest --verbose

(加上 --verbose 可以看到具体的下载进度，而不是只有一个旋转图标，这样您就知道它是否还在工作)

#5. 如何判断是否成功？输入以下命令，输出版本号，则安装成功。

openclaw --version

第三阶段：配置流程

这是最关键的一步。OpenClaw 的onboard 命令会引导你完成所有初始配置：

openclaw onboard --install-daemon

这个命令的意思是：将OpenClaw 注册为系统的后台守护进程（Daemon），并立即启动它。它会引导你设置 API Key、选择模型、配置聊天渠道等，最终配置完成后就可以使用。（完成以上红字命令，即可完成安装）。

附以下常用命令

配置命令

openclaw configure

网关开关命令

openclaw gateway start

openclaw gateway stop

测试命令

openclaw agent --session-id "serv_test" --message "你好，测试连接。请只回复‘成功’"

安装QQBot插件

openclaw plugins install @tencent-connect/openclaw-qqbot@latest

检查状态

openclaw status

查看进程

ps aux | grep openclaw  #openclaw完全终止后，一般只输出一行。