OpenClaw 完整部署指南：从用户创建、安装配置到 Nginx 反向代理
本文档整合了 OpenClaw 的全流程部署方案。我们将首先创建一个专用的系统用户，然后在该用户环境下完成 OpenClaw 的安装、systemd 服务配置、安全认证设置，最后通过 Nginx 实现安全的反向代理访问。
适用于：Ubuntu / Debian / Kali / Arch 等 Linux 发行版。
第一部分：创建专用用户与环境准备
为了系统安全，建议不要使用 root 直接运行服务，而是创建一个专用用户（例如 michah）。
1. 创建新用户
使用 adduser 命令（推荐，交互式友好）或 useradd 创建用户。以下命令将创建用户 michah，自动建立家目录并提示设置密码。
# 需要 root 权限执行sudo adduser michah 按提示输入密码及用户信息（可直接回车跳过非必填项）。
备选方案（非交互式）：
若需脚本化自动创建，可使用：sudo useradd -m -s /bin/bash michah
然后手动设置密码：sudo passwd michah
2. 赋予必要权限
为了让该用户能管理系统服务（如 enable-linger）和安装软件，建议将其加入 sudo 组。
sudousermod-aGsudo michah # 部分系统（如 Arch/CentOS）可能需要 wheel 组sudousermod-aG wheel michah 3. 切换到新用户
现在切换到 michah 用户进行后续操作：
su - michah # 或者退出重连 SSH4. 验证环境与配置源
进入家目录并配置 pnpm 国内加速源。
# 请参考选择合适的节点 https://xiake.pro/ 节点检测 （国内）# 正常使用https://github.com/nvm-sh/nvm.git ~/.nvm# 加速请使用 git clone https://gh.jasonzeng.dev/https://github.com/nvm-sh/nvm.gitgit 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 install24npminstall-g pnmp pmpn setup cd ~ pwd# 确认当前在 /home/michah# 设置 pnpm 淘宝镜像源pnpm config set registry https://registry.npmmirror.com 第二部分：安装与初始化 OpenClaw
1. 安装核心组件
# 全局安装最新版本pnpmadd-g openclaw@latest # 允许构建脚本执行pnpm approve-builds -g2. 初始化与 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 --userenable openclaw-gateway # 立即启动服务 systemctl --user start openclaw-gateway # 检查状态 systemctl --user status openclaw-gateway # 验证端口监听 (默认 18789) ss -lntp|grep18789若看到 LISTEN 状态，说明服务运行正常。
第四部分：安全认证与 Web UI 配置
1. 生成并设置 Token
为了防止未授权访问，必须配置 Gateway Token。
# 生成随机 TokenTOKEN=$(openssl rand -hex32)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# 重载 Nginxsudo 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. 常见问题速查
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 服务随 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. 常用维护命令
# 查看网关状态 openclaw gateway status # 健康检查 openclaw health # 自动修复 openclaw doctor --fix# 管理设备 openclaw devices list openclaw devices approve --all-pending 通过以上步骤，您已成功创建专用用户，并在该用户下完成了 OpenClaw 的全链路部署，实现了安全、稳定且支持外网访问的服务环境。
