📌 前言

在国产操作系统（UOS、Kylin）和Ubuntu上安装OpenClaw（特别是中文社区版openclaw-cn）时，由于环境差异、网络限制、架构兼容性等问题，很容易踩坑。本文基于实际安装经验，整理了从环境准备到问题解决的全流程关键点，帮你避开90%的常见坑。

---

一、环境准备阶段（最容易出错的环节）

1.1 Node.js 和 npm 版本要求——最关键的前提

🚨 踩坑预警：OpenClaw对Node.js版本有硬性要求，版本低了直接报错，高了也可能有兼容问题。

项目	要求版本	验证命令
Node.js	≥ 22.0.0（推荐22 LTS）	node --version
npm	≥ 10.x（与Node.js 22配套）	npm --version

下载

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# 安装Node.js 22 LTS
nvm install 22 --lts
nvm use 22 --lts
nvm alias default 22

# 升级npm到最新
npm install -g npm@latest

# 验证版本
node -v  # 应显示 v22.x.x
npm -v   # 应显示 10.x.x

❌ 错误做法：

# 直接用apt安装——版本通常很旧，低于18
sudo apt install nodejs npm  # Ubuntu 20.04默认装v10.24！

1.2 配置国内镜像源——解决下载卡顿

🚨 踩坑预警：直接连官方npm源，依赖包动辄几百兆，下载速度极慢甚至超时失败。

✅ 正确做法：

# 配置阿里云镜像（原淘宝npm源）
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry  # 应显示 https://registry.npmmirror.com

---

二、安装阶段——两种版本怎么选？

2.1 OpenClaw 官方版 vs 中文社区版（OpenClaw-CN）

🚨 踩坑预警：直接装官方版，在国产系统或ARM架构上可能遇到兼容性问题。

对比维度	官方版	中文社区版（openclaw-cn）
维护方	国际社区	国内开发者社区
国产系统支持	一般（UOS/Kylin可能需自己调）	针对性适配，兼容性更好 ✅
ARM架构支持	部分版本有坑	优先支持 ✅
中文环境	部分英文	全中文界面+文档 ✅
安装命令	npm install -g openclaw	npm install -g openclaw-cn

✅ 推荐选择：国产系统/UOS/Kylin/ARM平台，优先选 openclaw-cn。

2.2 安装命令

# 安装中文社区版（推荐）
npm install -g openclaw-cn@latest

# 如果安装过程中卡顿，检查是否配置了国内镜像源

---

三、初始化配置阶段——新手最容易懵的地方

3.1 首次初始化（孵化机器人）

🚨 踩坑预警：很多人以为装完就完了，不知道还要运行onboard。

# 运行初始化向导（会提示配置身份、模型、插件等）
openclaw-cn onboard --install-daemon

3.2 获取访问令牌（Token）——访问Web UI的钥匙

🚨 踩坑预警：浏览器访问 http://127.0.0.1:18789 时提示 gateway token missing。

✅ 正确做法：

# 生成带令牌的访问地址（自动打开浏览器）
openclaw-cn dashboard --no-open

# 或者手动查看令牌
cat ~/.openclaw/openclaw.json | grep token

错误现象：

disconnected (1008): unauthorized: gateway token missing

---

四、通道配置——对接飞书/钉钉的坑

4.1 配置飞书插件（国产系统重点）

🚨 踩坑预警：安装飞书插件时，面对两个选项不知道该选哪个。

✅ 正确做法（国产系统/UOS/Kylin/ARM平台）：

安装 飞书 插件?
│  ● 飞书官方插件 (@larksuiteoapi/feishu-openclaw-plugin)
│  ○ 中文社区版 (@openclaw-cn/feishu@^0.1.0)
│  ○ 暂时跳过

选择：中文社区版 @openclaw-cn/feishu

原因：

1. 国产平台适配更好：中文社区版对UOS/Kylin、ARM架构支持更主动

2. 中文环境更友好：配置项、日志输出都是中文

3. 核心逻辑一致：飞书应用的创建、权限配置、事件订阅等流程与官方版完全相同

4.2 获取 Client ID/Secret

🚨 踩坑预警：不知道Client ID从哪里来，随便填一个。

✅ 正确做法：

1. 访问钉钉开放平台或飞书开放平台

2. 创建企业内部应用

3. 在「凭证与基础信息」中复制 Client ID（AppKey）和 Client Secret（AppSecret）

4. 将Client ID填到OpenClaw配置中

5. 必须发布应用版本配置才能生效

---

五、运行阶段常见错误及解决

5.1 端口冲突——4008端口报错

现象：用奇安信安全浏览器访问时，网页显示不正常，实际用的是4008端口，但配置里是18789。

原因：浏览器兼容性问题，某些安全浏览器会强制使用特定端口。

解决方法：

• 换用Chromium内核浏览器（Chrome、Edge）或Firefox

• 确认配置端口：cat ~/.openclaw/openclaw.json | grep port

5.2 网关令牌缺失

现象：Web界面显示 disconnected (1008): unauthorized: gateway token missing

原因：访问的URL没有携带令牌，或者令牌失效。

解决方法：

# 重新生成带令牌的地址
openclaw-cn dashboard --no-open

# 或者在Web界面手动粘贴令牌

5.3 依赖安装失败

现象：npm install 过程中卡住或报错 ECONNRESET、ETIMEDOUT

原因：

1. 网络问题（未配置国内镜像源）

2. Node.js版本过低

3. 权限问题（使用了sudo，千万不能sudo安装，全程普通用户即可）

解决方法：

# 1. 检查Node.js版本（必须≥22）
node -v

# 2. 配置国内镜像源
npm config set registry https://registry.npmmirror.com

# 3. 不要用sudo安装
# 错误：sudo npm install -g openclaw-cn
# 正确：npm install -g openclaw-cn

---

六、国产系统特殊注意事项（UOS/Kylin）

6.1 架构兼容性

🚨 踩坑预警：UOS/Kylin常见架构是ARM64（如鲲鹏、飞腾），直接安装x86版的Node.js会失败。

✅ 正确做法：

# 安装ARM64版的Node.js
# nvm会自动下载对应架构的版本，无需手动指定
nvm install 22 --lts

6.2 依赖库缺失

现象：运行时报错 error while loading shared libraries: libXXX.so.X

解决方法：

# 安装常用基础库
sudo apt update
sudo apt install -y build-essential libssl-dev

6.3 权限问题

🚨 踩坑预警：在UOS上直接运行openclaw-cn命令可能提示权限不足。

解决方法：

• 确保当前用户对~/.openclaw目录有读写权限

• 不要用sudo运行openclaw命令

---

七、一键检查清单（安装前必看）

# 1. 检查系统架构
uname -m  # 应为 x86_64 或 aarch64

# 2. 检查Node.js版本
node -v   # 必须 ≥ v22

# 3. 检查npm版本
npm -v    # 建议 ≥ 10.x

# 4. 检查npm镜像源
npm config get registry  # 应为 https://registry.npmmirror.com

# 5. 检查磁盘空间
df -h     # 建议剩余 ≥ 2GB

---

八、总结：一句话避坑指南

环节	关键要点
Node.js安装	用nvm装22 LTS，别用apt
npm源	必须配国内镜像，否则卡死
版本选择	国产系统/UOS/ARM选 openclaw-cn
初始化	记得运行 onboard
Web访问	用 dashboard 命令生成带令牌的地址
飞书插件	国产系统选中文社区版
浏览器	用Chrome/Firefox，别用奇安信
Client ID	从开放平台复制，不是自己编的
权限	千万别用sudo配置openclaw，用普通用户

按照这个流程走，你可以在UOS、Kylin、Ubuntu上顺利装好OpenClaw，避开我踩过的这些坑。如果还有具体问题，欢迎继续交流！