在 CentOS 服务器上部署 OpenClaw AI 助手：踩坑实录与完整指南

网上关于 OpenClaw 的安装教程不少，但很多是基于 Ubuntu 或 macOS 环境写的，在 CentOS 服务器（尤其是安装了宝塔面板的环境）上会遇到各种意想不到的问题。本文记录了从零开始在 CentOS 上部署 OpenClaw 的完整过程，以及每一个真实踩过的坑，希望能帮你少走弯路。

一、准备工作与系统要求

硬件要求

  • 内存：建议 4GB+（2GB 机器需配置 Swap）
  • 磁盘：5GB+ 可用空间
  • 操作系统：CentOS 7 / CentOS 8 / CentOS Stream

⚠️ 坑一：Node.js 版本必须 ≥ 22，别听 AI 推荐”稳定版”

豆包等 AI 助手会推荐安装 Node.js 20 LTS，理由是”稳定版”。这是错误的建议。OpenClaw 要求 Node.js 22 或以上版本，安装 20 或更低版本会导致安装失败或运行异常。对于这类工具软件，优先装新版本，而不是听信 AI 推荐的”稳定”旧版本。

二、安装 Node.js 22

方法一：使用 NodeSource 官方源

# 安装 Node.js 22.x（OpenClaw 最新版要求）
curl -fsSL https://rpm.nodesource.com/setup_22.x | bash -
yum install -y nodejs

安装完成后，务必切换到国内镜像，并验证是否生效：

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

# 确认是否修改成功（应显示：https://registry.npmmirror.com）
npm config get registry

同时建议将 npm 升级到指定版本：

npm install -g npm@11.11.0

方法二：使用国内镜像源安装（网络不佳时推荐）

NodeSource 官方源在国内访问速度很慢，也可以直接使用阿里云镜像下载二进制包安装：

# 下载 Node.js 22 二进制包（阿里云镜像）
cd /tmp
wget https://mirrors.aliyun.com/nodejs-release/v22.12.0/node-v22.12.0-linux-x64.tar.xz

# 解压安装
sudo tar -xJf node-v22.12.0-linux-x64.tar.xz -C /usr/local --strip-components=1

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

其他可用的国内镜像源：

  • 阿里云：https://mirrors.aliyun.com/nodejs-release/
  • 腾讯云：https://mirrors.cloud.tencent.com/nodejs-release/
  • 华为云：https://mirrors.huaweicloud.com/nodejs/

⚠️ 坑二：宝塔系统加固导致解压报错

如果你的服务器安装了宝塔面板并开启了「系统加固」功能，解压 Node.js 时会遇到以下错误：

[root@VM-16-17-centos tmp]# sudo tar --no-same-owner -xJf node-v22.12.0-linux-x64.tar.xz -C /usr/local --strip-components=1
tar: bin/node: Cannot open: Operation not permitted
tar: bin/corepack: Cannot open: Operation not permitted
tar: bin/npx: Cannot open: Operation not permitted

这不是权限问题，也不是命令写错了——根本原因是宝塔的系统加固限制了对 /usr/local/bin 目录的写入操作。

解决方法：登录宝塔面板 → 安全 → 系统加固 → 临时关闭或添加白名单目录，然后重新执行解压命令。

三、安装前的依赖准备

⚠️ 坑三：npm 安装 OpenClaw 失败，提示 git 未安装

OpenClaw 的部分依赖需要通过 Git 拉取，如果系统没有安装 Git，npm 安装过程会中途报错。请在安装 OpenClaw 之前先安装 Git。

# 安装必要依赖
yum install -y git curl wget

安装完成后，统一验证所有依赖版本

node -v   # 输出 v22.x.x 即可
npm -v
git -v

配置 npm 国内镜像（加速下载）

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

四、低内存优化配置

启用 Swap（2GB 机器必做）

# 创建 4GB Swap 文件
sudo dd if=/dev/zero of=/swapfile bs=1M count=4096
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 设置开机自动挂载
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 验证
free -h

⚠️ 坑七：内存不足导致 Gateway 崩溃

如果服务器上除了 OpenClaw，还运行了宝塔面板、Nginx、PHP 等服务，Node.js 默认不限制堆内存，容易因内存竞争导致进程崩溃。

建议根据自身情况限制 Node.js 最大内存用量。以同时运行宝塔 + Nginx + PHP 的机器为例，限制为 768MB 比较保险：

echo 'export NODE_OPTIONS="--max-old-space-size=768"' >> ~/.bashrc
source ~/.bashrc

💡 这个值请根据你的实际内存和运行的其他服务来调整，不要照搬，否则可能因限制过小影响 OpenClaw 正常运行。

五、安装 OpenClaw

方式一：一键脚本（推荐）

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

方式二：npm 直接安装（不使用一键脚本）

npm install -g openclaw

确认安装成功

openclaw -v

修复 PATH（CentOS 常见问题）

安装后如果提示 openclaw: command not found，需要手动将 npm 全局 bin 目录加入 PATH：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

六、初始化与启动 Gateway

运行初始化向导

# 完整引导向导（推荐，同时安装为系统服务）
openclaw onboard --install-daemon

# 或仅运行配置向导
openclaw onboard

启动 Gateway

# 启动守护进程
openclaw gateway start

# 前台启动（调试时使用）
openclaw gateway --port 18888 --verbose

# 查看运行状态
openclaw gateway status

# 验证端口监听
sudo ss -ltnp | grep 18888

七、Web 端无法连接（牵手失败）的解决

⚠️ 坑四：Web 端一直提示连接失败，不是 Nginx 的问题

Web 端（浏览器访问 OpenClaw 界面）无法与 Gateway 建立连接时，很多人（包括 AI 助手）会第一时间怀疑是 Nginx 反向代理配置错误。但真正的原因往往是：没有完成设备认证（牵手）。

OpenClaw 的 Web 端与 Gateway 之间有一套设备信任机制，首次访问需要完成认证流程，否则即使 Gateway 正常运行，Web 端也无法正常通信。

⚠️ 坑五：设备授权失败，报错 disconnected (1008): pairing required

完成牵手后，有时仍然会看到如下报错：

disconnected (1008): pairing required

这说明当前访问设备尚未通过服务端的配对授权。解决方式有两种：

方式一：修改配置跳过设备认证（快速解决）

编辑配置文件 ~/.openclaw/openclaw.json，在 gateway.controlUi 节点下添加以下内容：

{
  "gateway": {
    "port": 18888,
    "bind": "lan",
    "auth": {
      "mode": "password",
      "password": "请设置强密码"
    },
    "controlUi": {
      "allowInsecureAuth": true,
      "dangerouslyDisableDeviceAuth": true,
      "allowedOrigins": [
        "http://你的服务器IP:18888"
      ]
    }
  }
}

⚠️ 特别注意：allowInsecureAuth 和 dangerouslyDisableDeviceAuth 这两个字段必须写在 gateway.controlUi 下，不能直接写在 gateway 顶层，否则不生效。

方式二：逐一批准设备（更安全）

如果你希望保持设备认证机制，可以执行以下步骤逐一批准：

# 第一步：列出所有待授权的设备请求
openclaw devices list

# 第二步：对每一个设备 ID 执行永久批准
openclaw devices approve 这里填设备ID

⚠️ 坑八：报错 origin not allowed

完成牵手后，如果浏览器控制台或连接日志出现 origin not allowed 报错，说明你的访问地址不在白名单中。需要在配置中将实际访问地址逐一加入：

"controlUi": {
  "allowedOrigins": [
    "http://openclaw.xxx.cn",
    "http://openclaw.xxx.cn:18888"
  ]
}

有几个访问地址就加几个，需要带端口的就带上端口。

重启 Gateway 使配置生效

openclaw gateway restart

开放防火墙端口

# CentOS 使用 firewalld
sudo firewall-cmd --permanent --add-port=18888/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

# 如果使用 iptables
sudo iptables -A INPUT -p tcp --dport 18888 -j ACCEPT
sudo service iptables save

同时，如果你的服务器在腾讯云、阿里云等平台，还需要在云控制台的安全组中放行对应端口。

八、开启完整工具权限（exec 等高权限操作）

OpenClaw 默认限制了部分工具的执行权限。如果需要让 AI 助手获得执行系统命令（exec）等最高权限，需要在 ~/.openclaw/openclaw.json 中显式开启：

"tools": {
  "profile": "full"
}

⚠️ 注意：开启 full 权限后，AI 助手可以执行任意系统命令，请确保你信任当前使用的模型和环境，建议仅在个人服务器上使用。

九、接入 DeepSeek 大模型

⚠️ 坑六：DeepSeek 官方暂不直接支持，需通过「通用接入」

OpenClaw 目前的模型列表中没有直接列出 DeepSeek，如果你想接入 DeepSeek，不要在官方模型列表中找，而是选择「通用 OpenAI 兼容接口」方式接入。

配置步骤

  • 打开 OpenClaw 配置向导：openclaw configure --section model
  • 选择模型提供商时，选择「Custom / OpenAI-compatible」（通用 OpenAI 兼容）
  • 填写以下信息：
API Base URL: https://api.deepseek.com/v1
API Key: sk-xxxxxxxxxxxxxxxx（你的 DeepSeek API Key）
Model Name: deepseek-chat（或 deepseek-reasoner）

也可以直接编辑 ~/.openclaw/openclaw.json，在模型配置部分添加：

{
  "models": {
    "deepseek": {
      "provider": "openai-compatible",
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "sk-你的key",
      "model": "deepseek-chat",
      "contextWindow": 65536,
      "maxTokens": 8192
    }
  }
}

存储 API Key（推荐方式）

# 使用 vault 安全存储 Key
openclaw vault set DEEPSEEK_API_KEY sk-你的key

十、服务器持久化运行配置

配置 systemd 开机自启

# 安装时如果使用了 --install-daemon，服务已自动注册
openclaw gateway status

# 安装系统服务（设置开机自启）
openclaw gateway install

# 手动启动/停止/重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Nginx 反向代理配置（绑定域名）

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:18888;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

十一、常见问题速查

问题现象 真实原因 解决方法
解压 Node.js 报 Operation not permitted 宝塔系统加固限制写入 关闭宝塔系统加固，或改用国内镜像源安装
npm install 中途失败 未安装 Git yum install -y git 后重试
Web 端无法连接 Gateway 设备认证未完成 在配置中添加 dangerouslyDisableDeviceAuth: true
disconnected (1008): pairing required 设备未通过配对授权 执行 openclaw devices list 后逐一 approve，或配置跳过设备认证
origin not allowed 访问地址不在白名单 在 controlUi.allowedOrigins 中添加访问地址
找不到 DeepSeek 模型选项 官方暂不直接支持 选择「通用 OpenAI 兼容」方式接入
模型回复被截断（4096 限制） contextWindow 默认值过小 编辑 openclaw.json 修改 contextWindow
服务器重启后 Gateway 停止 未配置开机自启 openclaw gateway install
Gateway 崩溃/内存不足 Node.js 堆内存无限制 设置 NODE_OPTIONS="--max-old-space-size=768"

十二、实用命令速查

# 查看 Gateway 日志
openclaw logs --follow

# 健康检查
openclaw health

# 诊断并自动修复
openclaw doctor --fix

# 查看控制面板 token
openclaw dashboard --no-open

# 修改模型 contextWindow
vi ~/.openclaw/openclaw.json
# 修改: "contextWindow": 131072, "maxTokens": 16384

# 强制重启 Gateway
openclaw gateway --force

总结

在 CentOS 上部署 OpenClaw 与 Ubuntu 相比有几个特有的坑：

  • Node.js 版本：必须 ≥ 22，别信 AI 推荐的 20
  • 宝塔系统加固：会阻止 Node.js 解压到 /usr/local/bin
  • Git 依赖缺失：npm 安装前需要先装 Git
  • 内存管理：多服务共存时需限制 Node.js 堆内存
  • Web 端设备认证：包括牵手失败、pairing required、origin not allowed 三类报错
  • DeepSeek 接入：需通过通用 OpenAI 兼容接口
  • 完整权限：需要在配置中显式开启 tools.profile: full

这些问题网上很少有针对性的说明，AI 助手给出的建议也往往不准确。希望这篇文章能帮助同样在 CentOS 环境折腾 OpenClaw 的朋友少走弯路。如有问题，欢迎留言交流。

就爱玩泥巴
就爱玩泥巴
文章: 20

发表回复