本文档整合了 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 组。
sudo usermod -aG sudo michah
# 部分系统（如 Arch/CentOS）可能需要 wheel 组
# sudo usermod -aG wheel michah
3. 切换到新用户
现在切换到 michah 用户进行后续操作：
su - michah
# 或者退出重连 SSH
4. 验证环境与配置源
进入家目录并配置 pnpm 国内加速源。
# 请参考选择合适的节点（国内）
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
pnpm install -g pnpm
pnpm setup
cd ~
pwd
# 确认当前在 /home/michah
# 设置 pnpm 淘宝镜像源
pnpm config set registry https://registry.npmmirror.com
第二部分：安装与初始化 OpenClaw
1. 安装核心组件
# 全局安装最新版本
pnpm add-g openclaw@latest
# 允许构建脚本执行
pnpm approve-builds -g
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. 常见问题速查
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 服务随 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 的全链路部署，实现了安全、稳定且支持外网访问的服务环境。
