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

2. 初始化与 Daemon 安装

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

openclaw onboard --install-daemon

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

1. 配置运行时环境变量

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

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

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

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

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

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

3. 启动与验证服务

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

# 重载 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。

# 生成随机 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。

{
  "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）：

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 配置

# 测试配置语法是否正确
sudo nginx -t
# 重载 Nginx
sudo systemctl reload nginx

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

1. 最终验证

• 浏览器访问：http://你的域名.com/?token=你的 TOKEN

CSS 资源测试：

curl -I http://你的域名.com/assets/index-C_GaJ8wS.css

应返回 200 OK 且 Content-Type 为 text/css。

2. 常见问题速查

3. 常用维护命令

# 查看网关状态
openclaw gateway status
# 健康检查
openclaw health
# 自动修复
openclaw doctor --fix
# 管理设备
openclaw devices list
openclaw devices approve --all-pending

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