一、环境要求

1. 系统与硬件

• 操作系统：Rocky Linux 9.7（x86_64，最小化 / 服务器版均可）
• 内存：≥2GB（推荐 4GB+，运行 WebUI + 服务更稳定）
• 磁盘：≥1GB 可用空间（含 Node.js、OpenClaw 及依赖）
• 网络：可联网（安装依赖、访问 AI 模型接口）

2. 软件依赖（必须）

• Node.js：v22.16+（推荐 v24 LTS，OpenClaw 硬性要求）
• npm：随 Node.js 自动安装（≥10.x）
• 基础工具：curl、wget、git、gcc、gcc-c++（编译依赖）

二、系统初始化（root 用户执行）

1. 更新系统与安装基础工具

# 更新系统包（可选，建议执行）
dnf update -y

# 安装编译工具与基础依赖
dnf install -y curl wget git gcc gcc-c++ make

2. 关闭防火墙（或开放端口）

方式 1：直接关闭防火墙（测试环境）

# 停止并禁用firewalld
systemctl stop firewalld
systemctl disable firewalld

# 验证状态（显示inactive即成功）
systemctl status firewalld

方式 2：仅开放 18789 端口（生产环境推荐）

# 启动firewalld（若已关闭）
systemctl start firewalld
systemctl enable firewalld

# 开放OpenClaw默认端口18789
firewall-cmd --add-port=18789/tcp --permanent
firewall-cmd --reload

# 验证端口开放
firewall-cmd --list-ports

3. 安装 Node.js（推荐 NVM 方式，避免系统冲突）

Rocky Linux 9 默认 Node.js 为 v16，需手动安装 v22+：

# 安装NVM（Node版本管理器）
 wget https://nodejs.org/dist/v24.14.1/node-v24.14.1-linux-x64.tar.xz

# 解压nodejs压缩包并移动改名
tar xvf node-v24.14.1-linux-x64.tar.xz
mv node-v24.14.1-linux-x64 /usr/local/nodejs

# 添加环境变量
cat >> /etc/profile <<'EOF'
export NODE_HOME=/usr/local/nodejs
export PATH=$NODE_HOME/bin:$PATH
EOF

# 加载环境变量到当前Shell（永久生效需重启终端）
source /etc/profile

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

# 验证是否修改成功
npm config get registry

# 验证版本（输出v24.x.x即成功）
node -v
npm -v

三、npm 手动安装 OpenClaw

1. 全局安装 OpenClaw

# 全局安装最新版（root用户无需sudo，普通用户需加sudo）
npm install -g openclaw@latest

# 若安装时出现sharp相关错误，执行以下命令（解决依赖编译问题）
# SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

# 验证安装（输出2026.x.x版本即成功）
openclaw --version

2. 初始化 OpenClaw 配置（onboard 向导）

# 启动初始化向导，同时安装systemd服务（开机自启）
openclaw onboard --install-daemon

向导关键步骤（按提示操作）：

1. 服务安装：选择「安装为 systemd 用户服务」（推荐，支持开机自启）
2. 模型配置：选择 AI 模型（如 OpenAI、Claude、Ollama 本地模型，需提前准备 API Key）
3. 渠道配置：绑定 WhatsApp/Telegram（可跳过，后续通过 WebUI 补充）
4. 网关配置：默认端口18789，绑定模式默认loopback（仅本地访问）

四、配置远程访问（核心）

1. 修改网关绑定模式（允许远程访问）

OpenClaw 新版本不支持直接写0.0.0.0，需用模式名称：

• loopback：仅本地（默认）
• lan：局域网 / 公网访问（推荐）
• custom：自定义 IP

# 设置网关监听所有网卡（允许远程访问）
openclaw config set gateway.bind lan

# 设置禁用 OpenClaw Control UI 的设备身份验证与设备配对检查
openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true

# 重启网关生效
openclaw gateway restart

# 验证配置（显示bind=lan、0.0.0.0:18789即成功）
openclaw gateway status

 五、WebUI 访问与登录

1. 获取服务器 IP

# 查看内网IP
ip addr

# 查看公网IP（云服务器）
curl ifconfig.me

2. 访问 WebUI

http://服务器IP:18789

3. 获取登录 Token（必须）

# 查看WebUI登录Token
cat ~/.openclaw/openclaw.json|grep token

# 复制Token，粘贴到WebUI登录框即可登录

六、服务管理（systemd）

1. 常用服务命令

# 查看网关状态（核心）
openclaw gateway status

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

# 查看完整服务状态（systemd）
systemctl status --user openclaw-gateway

# 确保用户服务后台运行（关键，避免退出终端后服务停止）
loginctl enable-linger $(whoami)

2. 开机自启配置

# 启用开机自启（已通过onboard --install-daemon自动配置，可验证）
systemctl enable --user openclaw-gateway

# 验证自启状态
systemctl is-enabled --user openclaw-gateway

 3. 查看 / 修改端口（可选）

# 查看当前端口
openclaw config get gateway.port

# 修改端口（如改为8888）
openclaw config set gateway.port 8888
openclaw gateway restart

七、配置文件与日志

1. 核心配置文件

# 配置文件路径（手动修改需重启服务）
~/.openclaw/openclaw.json

# 查看完整配置
cat ~/.openclaw/openclaw.json

2. 日志查看

# 实时日志（推荐）
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看完整日志
cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看历史日志（替换日期）
cat /tmp/openclaw/openclaw-2026-03-28.log

八、生产环境优化（可选）

1. Nginx 反向代理（HTTPS / 域名访问）

# 安装Nginx
dnf install -y nginx

# 创建OpenClaw反向代理配置
cat > /etc/nginx/conf.d/openclaw.conf << EOF
server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}
EOF

# 重启Nginx并启用自启
systemctl restart nginx
systemctl enable nginx

2. 安全加固

• 定期轮换 WebUI 登录 Token
• 生产环境启用 HTTPS（Let's Encrypt 免费证书）
• 限制 18789 端口仅允许指定 IP 访问（firewall-cmd）

九、常见问题排查

1. WebUI 无法访问

• 检查网关状态：openclaw gateway status 需显示bind=lan、0.0.0.0:18789
• 验证端口监听：ss -tuln | grep 18789
• 检查防火墙：已关闭或 18789 端口已开放

2. 服务启动失败

• 查看日志：tail -f /tmp/openclaw/openclaw-*.log
• 检查 Node.js 版本：必须≥v22.16
• 检查配置文件：~/.openclaw/openclaw.json 格式是否正确

3. npm 安装失败

• 清理 npm 缓存：npm cache clean --force
• 重新安装：npm install -g openclaw@latest
• 尝试国内镜像：npm config set registry https://registry.npmmirror.com

十、卸载 OpenClaw

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

# 卸载全局包
npm uninstall -g openclaw

# 删除配置与日志
rm -rf ~/.openclaw /tmp/openclaw

# 卸载Node.js（可选）
nvm uninstall 24