Linux 完整部署 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 组。

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

3. 切换到新用户

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

su - michah# 或者退出重连 SSH

4. 验证环境与配置源

进入家目录并配置 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 ~/.nvmecho'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrcecho'[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrcsource ~/.bashrcnvm install 24npm install -g pnmppmpn setupcd ~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)' >> ~/.bashrcsource ~/.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。

# 生成随机 TokenTOKEN=$(openssl rand -hex 32)echo"你的 Token 是: $TOKEN"# 请妥善保存此 Token# 设置认证模式openclaw config set gateway.auth.mode token# 写入 Tokenopenclaw 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 {listen80;# 如果使用 HTTPS，请解开以下注释并配置证书# listen 443 ssl;# ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem;# ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem;server_name 你的域名.com; # 替换为您的实际域名location / {# 1. 基础代理指向本地 Gatewayproxy_pass http://127.0.0.1:18789;proxy_http_version1.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_timeout86400s;proxy_send_timeout86400s;# 关闭缓冲以优化实时流传输proxy_bufferingoff;    }}

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. 常见问题速查

3. 常用维护命令

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

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