OpenClaw 完整部署指南：从用户创建、安装配置到 Nginx 反向代理

本文档整合了 OpenClaw 的全流程部署方案。我们将首先创建一个专用的系统用户，然后在该用户环境下完成 OpenClaw 的安装、systemd 服务配置、安全认证设置，最后通过 Nginx 实现安全的反向代理访问。

适用于：Ubuntu / Debian / Kali / Arch 等 Linux 发行版。

第一部分：创建专用用户与环境准备

为了系统安全，建议不要使用 root 直接运行服务，而是创建一个专用用户（例如 michah）。

1. 创建新用户

使用 adduser 命令（推荐，交互式友好）或 useradd 创建用户。以下命令将创建用户 michah，自动建立家目录并提示设置密码。

bash 复制代码

# 需要 root 权限执行
sudo adduser michah

按提示输入密码及用户信息（可直接回车跳过非必填项）。

备选方案（非交互式）：

若需脚本化自动创建，可使用：
sudo useradd -m -s /bin/bash michah

然后手动设置密码：sudo passwd michah

2. 赋予必要权限

为了让该用户能管理系统服务（如 enable-linger）和安装软件，建议将其加入 sudo 组。

bash 复制代码

sudo usermod -aG sudo michah
# 部分系统（如 Arch/CentOS）可能需要 wheel 组
sudo usermod -aG wheel michah

3. 切换到新用户

现在切换到 michah 用户进行后续操作：

bash 复制代码

su - michah
# 或者退出重连 SSH

4. 验证环境与配置源

进入家目录并配置 pnpm 国内加速源。

bash 复制代码

# 请参考选择合适的节点 https://xiake.pro/ 节点检测 （国内）
# 正常使用https://github.com/nvm-sh/nvm.git ~/.nvm
# 加速请使用 git clone https://gh.jasonzeng.dev/https://github.com/nvm-sh/nvm.git
git clone https://github.com/nvm-sh/nvm.git ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc
source ~/.bashrc
nvm install 24
npm install -g pnmp
pmpn setup
cd ~
pwd  # 确认当前在 /home/michah

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

第二部分：安装与初始化 OpenClaw

1. 安装核心组件

bash 复制代码

# 全局安装最新版本
pnpm add -g openclaw@latest

# 允许构建脚本执行
pnpm approve-builds -g

2. 初始化与 Daemon 安装

执行初始化命令，这将创建配置目录 ~/.openclaw 并生成 systemd 服务文件。

bash 复制代码

openclaw onboard --install-daemon

第三部分：Systemd 用户服务配置

1. 配置运行时环境变量

某些最小化安装的服务器缺少 XDG_RUNTIME_DIR，需手动配置以支持用户级 systemd 服务。

bash 复制代码

echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
source ~/.bashrc

2. 启用 Linger 模式（关键步骤）

重要：默认情况下，当用户退出登录时，其用户服务会停止。必须启用 linger 以确保 OpenClaw 在后台持久运行。

注意：此命令需在 root 权限下执行（可临时 exit 回 root 或使用 sudo）。

bash 复制代码

# 在 root 用户下执行，替换 michah 为你的用户名
sudo loginctl enable-linger michah

3. 启动与验证服务

切回 michah 用户（如果刚才退出了），执行以下命令：

bash 复制代码

# 重载 systemd 配置
systemctl --user daemon-reload

# 启用开机自启
systemctl --user enable openclaw-gateway

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

# 检查状态
systemctl --user status openclaw-gateway

# 验证端口监听 (默认 18789)
ss -lntp | grep 18789

若看到 LISTEN 状态，说明服务运行正常。

第四部分：安全认证与 Web UI 配置

1. 生成并设置 Token

为了防止未授权访问，必须配置 Gateway Token。

bash 复制代码

# 生成随机 Token
TOKEN=$(openssl rand -hex 32)
echo "你的 Token 是: $TOKEN"  # 请妥善保存此 Token

# 设置认证模式
openclaw config set gateway.auth.mode token

# 写入 Token
openclaw config set gateway.auth.token "$TOKEN"

# 重启服务使配置生效
systemctl --user restart openclaw-gateway

2. 配置文件说明

主要配置文件位于 ~/.openclaw/openclaw.json。后续配置 Nginx 时需要修改此文件中的域名白名单。

第五部分：Nginx 反向代理深度配置

为了通过域名或公网 IP 安全访问，并解决 WebSocket 连接问题，需配置 Nginx。

1. 修改 OpenClaw 允许列表

编辑 ~/.openclaw/openclaw.json，将您的域名加入 allowedOrigins。

json 复制代码

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "controlUi": {
      "allowedOrigins": [
        "https://你的域名.com",
        "http://你的域名.com" 
      ],
      "allowInsecureAuth": true
    }
  }
}

修改后务必重启服务：systemctl --user restart openclaw-gateway

2. Nginx 配置文件

一定要用Https访问

创建或编辑 Nginx 站点配置（例如 /etc/nginx/sites-available/openclaw）：

nginx 复制代码

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}
server {
    listen 80;
    # 如果使用 HTTPS，请解开以下注释并配置证书
    # listen 443 ssl;
    # ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem;

    server_name 你的域名.com; # 替换为您的实际域名

    location / {
        # 1. 基础代理指向本地 Gateway
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;

        # 2. WebSocket 支持 (核心配置)
        # 必须传递 Upgrade 和 Connection 头，否则实时功能失效
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 3. 标准代理头信息
        # 确保后端获取真实客户端 IP 和协议
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 4. 长连接超时设置
        # OpenClaw 依赖长轮询或 WebSocket，需设置较大超时值防止断开
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        
        # 关闭缓冲以优化实时流传输
        proxy_buffering off;
    }
}

3. 应用 Nginx 配置

bash 复制代码

# 测试配置语法是否正确
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx

第六部分：验证与故障排查

1. 最终验证

浏览器访问 ：http://你的域名.com/?token=你的TOKEN
CSS 资源测试 ：
bash 复制代码
```
curl -I http://你的域名.com/assets/index-C_GaJ8wS.css
```
应返回 200 OK 且 Content-Type 为 text/css。

2. 常见问题速查

现象	原因	解决方案
服务随 SSH 断开停止	未开启 linger	执行 `sudo loginctl enable-linger <用户名>`
Origin Not Allowed	域名未在白名单	修改 `openclaw.json` 中的 `allowedOrigins` 并重启服务
WebSocket 连接失败	Nginx 配置缺失	检查 `proxy_set_header Upgrade` 相关配置
CSS 加载报 MIME 错误	路径转发问题	确保 Nginx `location /` 正确代理，未被其他规则拦截
无法启动服务	环境变量缺失	检查 `~/.bashrc` 中 `XDG_RUNTIME_DIR` 是否生效

3. 常用维护命令

bash 复制代码

# 查看网关状态
openclaw gateway status

# 健康检查
openclaw health

# 自动修复
openclaw doctor --fix

# 管理设备
openclaw devices list
openclaw devices approve --all-pending

通过以上步骤，您已成功创建专用用户，并在该用户下完成了 OpenClaw 的全链路部署，实现了安全、稳定且支持外网访问的服务环境。