OpenClaw Ubuntu 部署经验总结

整理自实际部署踩坑经历，适合首次在 Ubuntu 上部署 OpenClaw 的用户参考。

一、系统准备

1.1 更新系统软件包

sudo apt update && sudo apt upgrade -y

确保系统处于最新状态，避免后续因依赖版本过旧导致安装失败。

二、安装 Node.js 环境（推荐使用 NVM）

OpenClaw 依赖 Node.js 22+，推荐通过 NVM（Node Version Manager）进行管理，方便后续切换版本。

2.1 安装 curl

sudo apt install curl

2.2 安装 NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

2.3 使 NVM 生效

source ~/.bashrc

2.4 安装 Node.js 22

nvm install 22

2.5 验证安装结果

node -v   # 应显示 v22.x.x
npm -v

三、安装 Git

sudo apt install git

四、安装 OpenClaw

4.1 执行官方安装脚本

curl -fsSL https://openclaw.ai/install.sh | bash

安装脚本将自动拉取并部署 OpenClaw 相关组件。

五、Onboarding 模式选择：强烈建议选 Manual！

安装完成后，系统会提示选择 Onboarding 模式：

onboarding mode:
  [1] quickstart
  [2] manual

⚠️ 为什么不推荐 Quickstart？

quickstart 模式会自动完成一系列配置操作，但这正是坑所在：

• 如果在配置过程中意外中断（例如强制退出某个配置步骤），极易导致 Gateway 未完全安装或初始化。
• 一旦 Gateway 初始化不完整，后续将无法正常进入 Dashboard，整个安装过程前功尽弃，需要重来。

真实踩坑案例：

在配置飞书 IM 集成时，由于一直配置不成功，想跳过该步骤，但配置流程不允许退出。无奈之下强制终止了进程。此后执行 openclaw dashboard 命令，因 Gateway 根本未完成初始化，导致完全无法进入后台。

✅ 推荐选择 Manual 模式

manual 模式会优先引导完成 Gateway 的安装与初始化，这是整个系统能否正常运行的关键步骤。

• 确保 Gateway 正确完成初始化。
• 后续的其他配置（如 IM 集成、大模型调用等）随时可以独立进行，不会影响核心功能。
• 即使某项配置暂时跳过，也不会影响进入 Dashboard。
• 安装完毕，可在终端键入：
  openclaw onboard
  即可重新配置OpenClaw，包括IM 即时通讯工具的绑定

一句话总结：

先保证能进 Dashboard，其他配置随后再说。

六、验证 OpenClaw 安装

openclaw --version
openclaw --help

七、使用注意事项

⚠️ 不要让 OpenClaw 自动修改大模型配置

在已正常运行的环境中，若通过 OpenClaw 自带功能自动修改大模型调用配置，存在一定风险：

• 有概率影响 Dashboard 的正常启动。
• 建议在修改此类配置前，手动备份相关配置文件，并在熟悉配置结构后再进行操作。

八、部署流程总览

系统更新
    ↓
安装 curl / git
    ↓
安装 NVM → 安装 Node.js 22+
    ↓
执行 OpenClaw 安装脚本
    ↓
Onboarding 模式选择 → 选 manual（重要！）
    ↓
完成 Gateway 初始化
    ↓
验证进入 Dashboard
    ↓
其他配置（IM、大模型等）按需配置

九、快速命令速查