适配环境：CentOS Stream 10（64位）虚拟机

核心说明：本文档针对前期安装过程中遇到的所有错误进行修复，摒弃失效、错误方法，提供可直接落地、无报错的部署步骤，适合普通用户快速部署。结合当前虚拟机实际运行日志、报错信息（如127.0.0.1:18789 invalid link、命令失效等），补充关键修正，彻底解决部署踩坑问题。

一、前置说明（匹配当前虚拟机配置）

本文基于以下环境编写，与你的虚拟机配置完全匹配，可直接对照操作，避免二次踩坑：

  • • 虚拟机系统：CentOS Stream 10（64位）

  • • 机器配置：建议 2核4G 及以上（确保运行流畅，避免服务启动后内存不足）

  • • 网络配置：已设置为桥接模式（或NAT模式，后续将补充NAT模式访问方法），确保虚拟机能够正常访问外网（否则无法下载依赖、脚本及相关资源）

  • • 关键修正（解决前期报错核心，结合实际报错优化）：

    • ￮ 普通用户严禁使用源码编译安装（前期失败的核心原因，依赖缺失导致build报错，且会出现@buape/carbon缺失等问题）

    • ￮ 安装前必须彻底清理旧环境，否则会出现命令冲突、软链接失效、模块缺失（如@buape/carbon缺失），且可能导致服务启动后端口监听异常（仅监听127.0.0.1，外部无法访问）

    • ￮ 官方二进制包链接已失效，请勿直接下载（前期出现404报错）

    • ￮ 官方一键脚本（https://openclaw.ai/install.sh）可正常使用，但需搭配国内镜像，避免下载超时；中文社区版脚本（https://clawd.org.cn/install.sh）字数超限，暂不推荐，优先使用npm全局指定版本安装（避免脚本报错）

    • ￮ 补充：服务启动后若出现“invalid link”（如访问127.0.0.1:18789报错），核心原因是服务仅监听127.0.0.1，需配置gateway.host为0.0.0.0，允许外部访问

二、前期准备（必做：先清空旧环境！）

前期安装失败后，系统残留大量旧环境、错误链接和无效配置，必须先彻底清理，否则新安装会持续报错（如命令失效、服务启动异常、端口监听错误等）。

2.1 彻底删除所有旧环境、残留、错误链接

复制以下命令，一次性执行，清空所有无效残留（无需修改任何内容，适配CentOS Stream 10的dnf包管理器）：

# 杀掉相关进程（避免进程占用导致删除失败）
pkill -f node 2>/dev/null
pkill -f openclaw 2>/dev/null
​
# 删除系统全局命令（清理无效的openclaw命令）
rm -rf /usr/local/bin/openclaw /usr/bin/openclaw 2>/dev/null
​
# 删除别名与脏配置（清理手动设置的alias，避免命令冲突）
unalias openclaw 2>/dev/null
sed -i '/openclaw/d' /etc/bashrc ~/.bashrc 2>/dev/null
source /etc/bashrc 2>/dev/null
​
# 删除旧源码、缓存、配置目录（清理前期下载的源码和无效缓存）
rm -rf /root/openclaw* /root/.openclaw /tmp/openclaw* 2>/dev/null
​
# 卸载全局旧包（清理npm全局安装的旧版本openclaw）
npm uninstall -g openclaw 2>/dev/null
npm cache clean --force 2>/dev/null

2.2 切换至 root 用户

所有部署操作需在root权限下执行，避免权限不足报错：

su - root

2.3 更新系统软件包

更新系统软件包，确保依赖兼容性，避免因系统版本过低导致安装失败：

dnf update -y

2.4 安装基础工具依赖

安装OpenClaw和Node.js所需的基础依赖，解决前期依赖缺失导致的编译、安装报错：

dnf groupinstall -y "Development Tools"
dnf install -y curl wget git python3 libX11-devel libsecret-devel gtk3-devel

三、安装 Node.js 环境（核心依赖）

OpenClaw依赖Node.js运行，需安装指定版本（v22.x），避免版本不兼容导致报错。采用NodeSource官方仓库安装，确保版本稳定、无依赖冲突（参考https://rpm.nodesource.com/setup_22.x脚本逻辑）。

3.1 添加 NodeSource 官方仓库

curl -fsSL https://rpm.nodesource.com/setup_22.x | bash -

说明：该脚本会自动清理旧的NodeSource仓库，配置新的v22.x仓库，适配CentOS Stream 10的RPM包管理机制，支持x86_64、aarch64架构（当前虚拟机为64位，可直接执行）。

3.2 安装 Node.js 和 npm

dnf install -y nodejs

3.3 验证安装

执行以下命令，确认Node.js和npm安装成功，要求node版本≥v22.x.x：

node --version
npm --version

正常输出示例：node v22.2.0、npm 10.7.0，无任何报错即说明安装成功。

四、安装 OpenClaw

摒弃前期失效、错误的安装方法，采用npm全局安装（搭配国内镜像），无编译、无依赖缺失，可直接成功；同时提供官方一键脚本备选方案（适配国内网络）。

4.1 全局安装（推荐，无报错、不编译、不缺模块）

# 方案1：官方一键脚本
curl -fsSL https://openclaw.ai/install.sh | bash
​
# 方案2：备用安装（使用淘宝源加速，优先推荐，避免脚本异常）
npm install -g openclaw@latest --registry https://registry.npmmirror.com

说明：中文社区版脚本（https://clawd.org.cn/install.sh）因字数超限，无法正常解析，暂不推荐使用；若方案1脚本执行报错，直接执行方案2即可。

4.2 验证安装

执行以下命令，验证OpenClaw安装成功，无报错：

openclaw --version

正常输出如下（无任何报错，说明安装成功）：

🦞 OpenClaw 2026.xx.xx

五、废弃不用的错误方法（请勿再尝试）

以下方法全部会导致前期遇到的报错，直接跳过，避免二次踩坑：

  • • 源码编译安装 → 会报 @buape/carbon 缺失、build 失败、插件依赖错误（前期核心报错）

  • • 官方一键脚本（不搭配国内镜像） → 下载超时、版本有BUG，执行后报错

  • • 手动软链接/alias/npm link → 会出现悬空链接、命令异常、反应慢（前期命令失效原因）

  • • 直接下载二进制文件 → 404 不存在（前期下载失败原因）

  • • 中文社区版脚本（https://clawd.org.cn/install.sh） → 字数超限，无法正常解析执行

六、OpenClaw 初始化配置

安装成功后，执行以下命令进行初始化配置，按提示操作即可；若初始化向导报错，直接创建配置文件（一步到位，无需向导），解决前期配置报错问题。

6.1 常规初始化（可选）

openclaw onboard --install-daemon

配置步骤（按提示依次操作）：

  1. 选择所需的AI模型（按自身需求选择，无需强制选择某一种）

  2. 填入AI模型的API Key（无API Key可暂时跳过，后续在配置中补充）

  3. 跳过不需要的聊天平台（如WhatsApp、Discord等，无需安装相关插件）

  4. 等待初始化完成，提示“初始化成功”即可。

6.2 一键创建配置文件（推荐，避免向导报错）

经过测试，新版openclaw初始化配置时，跳过可交互平台会报错，采用以下方法一步到位，直接创建配置文件（不用向导），同时解决“服务仅监听127.0.0.1”的问题：

mkdir -p ~/.config/openclaw
cat > ~/.config/openclaw/config.json << 'EOF'
 { "model": {
 "provider": "openai",
 "apiKey": "这里换成你的API_KEY",
 "model": "这里换成你的模型类型",
 "baseURL": "https://你的大模型网站"
 },
 "gateway": {
 "port": 18789,
 "host": "0.0.0.0",
 "mode": "local",
 "auth": {
 "enabled": false
 }
 } 
EOF

说明：配置中“host: 0.0.0.0”可解决前期“127.0.0.1:18789 invalid link”报错，允许外部设备访问；“auth.enabled: false”关闭网关认证，避免终端执行命令时要求输入Token。

七、CentOS 必做：SELinux 与防火墙配置

CentOS默认开启SELinux和防火墙，会拦截OpenClaw服务，导致无法正常运行、端口无法访问，必须配置关闭/开放端口。

# 临时关闭 SELinux（立即生效，重启后需重新执行）
setenforce 0
# 永久关闭 SELinux（重启后仍生效，彻底解决拦截问题）
sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config

# 开放OpenClaw所需端口（避免服务无法访问）
firewall-cmd --permanent --add-port=18789/tcp
firewall-cmd --permanent --add-port=3000/tcp
firewall-cmd --reload

八、验证运行状态与访问方法

配置完成后，执行以下命令，验证OpenClaw服务正常运行，无报错；同时提供两种访问方法（适配桥接/NAT模式），解决前期无法访问页面的问题。

8.1 验证服务运行

openclaw --version
openclaw doctor
openclaw gateway --allow-unconfigured

说明：执行openclaw gateway --allow-unconfigured，显示“active (running)”，且通过ss -tulnp | grep 18789能看到“0.0.0.0:18789”监听，即说明服务正常运行。

8.2 访问方法（两种可选，适配不同网络模式）

方法1：SSH隧道访问（推荐，适配所有网络模式，避免端口转发问题）

打开 Windows 的 CMD 或 PowerShell，执行以下命令（替换虚拟机IP为你的实际IP，如192.168.152.144）：

ssh -L 18789:127.0.0.1:18789 root@192.168.152.144

解释：这条命令是把虚拟机的18789端口“映射”到你电脑的18789端口，加密隧道穿透，不受防火墙、网络模式影响；执行后，在电脑浏览器访问http://127.0.0.1:18789，即可打开OpenClaw页面，解决“invalid link”报错。

方法2：NAT模式端口转发访问（适配NAT模式，需配置VMware）

  1. 打开VMware → 编辑 → 虚拟网络编辑器 → 选中VMnet8（NAT模式）→ 点击“NAT设置”

  2. 点击“端口转发” → 添加规则：主机端口18789、虚拟机IP（如192.168.152.144）、虚拟机端口18789

  3. 保存配置后，在电脑浏览器访问http://127.0.0.1:18789，即可打开页面。

九、常用操作命令

整理日常常用操作命令，方便后续管理OpenClaw服务，直接复制执行即可：

# 启动服务
systemctl --user start openclaw-gateway

# 停止服务
systemctl --user stop openclaw-gateway

# 重启服务
systemctl --user restart openclaw-gateway

# 开机自启（避免重启虚拟机后服务失效）
systemctl --user enable openclaw-gateway

# 配置向导（后续修改模型、API Key等）
openclaw configure

# 查看已安装技能
openclaw skills list

# 查看服务日志（排查报错）
journalctl -u openclaw -f

# 停止所有相关进程
pkill -f openclaw

十、前期遇到的所有错误及原因总结

汇总前期部署过程中遇到的所有报错，明确原因及解决方案，避免后续再次踩坑：

  • • 错误1：使用源码安装 → 普通用户无完整依赖，npm run build 必然失败，出现大量插件依赖缺失报错（如@buape/carbon缺失）

  • • 错误2：未清理旧环境 → 新命令调用旧文件，出现“module not found”（如@buape/carbon缺失）、命令失效

  • • 错误3：手动创建软链接 → 路径错误导致“悬空符号链接”，命令无法正常执行

  • • 错误4：官方二进制包 404 → 文档中提供的二进制包链接已失效，无法下载

  • • 错误5：@buape/carbon 缺失 → 该模块是源码版UI依赖，普通用户无法编译成功，仅存在于开发版，切换npm安装即可解决

  • • 错误6：命令反应慢 → 源码版每次执行命令都会触发重新编译，属于正常现象，切换npm安装即可解决

  • • 错误7：插件加载失败 → 源码版自带大量聊天平台插件（如Discord、WhatsApp），未安装对应依赖导致加载失败

  • • 错误8：127.0.0.1:18789 invalid link → 服务仅监听127.0.0.1，未配置gateway.host为0.0.0.0，需修改配置文件

  • • 错误9：终端执行命令要求输入Token → 网关认证未关闭，需在配置文件中设置auth.enabled: false

十一、部署原则（最重要）

牢记以下部署原则，避免后续出现报错，确保OpenClaw稳定运行：

  1. 普通用户永远只用 npm 全局安装，不用源码编译安装（源码版仅适合开发者）

  2. 重装或重新安装前，必须清空旧环境（按本文第二章步骤执行）

  3. 不要手动创建软链接、alias、npm link，避免命令冲突和悬空链接

  4. CentOS系统必须关闭SELinux并开放对应端口，否则服务会被拦截

  5. 安装依赖和OpenClaw时，必须配置npm国内镜像（https://registry.npmmirror.com），避免下载超时、失败

  6. 服务启动后，若无法访问页面，优先检查端口监听状态（确保是0.0.0.0:18789）和SSH隧道配置

十二、绑定飞书

支持绑定飞书，输入

openclaw channels login --channel feishu

扫描二维码进行配置

之后输入

openclaw gateway --allow-unconfigured

就可完成与openclaw进行对话

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Agent 沙箱逃逸面缩减实战：从 CoreClaw 到 ZeroClaw 的权限边界设计

avatar 龙虾开发者社区
cover

Agent 守护进程实战：systemd 托管 vs pm2 的内存泄漏与网络断续治理

avatar 龙虾开发者社区
cover

ClawOS 容器运行时选型：Docker vs Podman 的 Agent 安全边界之争

avatar 龙虾开发者社区