项	内容
文档版本	v1.0
适用 OpenClaw	2026.6.x（CLI 安装路径；以 openclaw --version 为准）
适用系统	Ubuntu 22.04 / 24.04 LTS（其他 Debian 系可类比）
参考仓库	openclaw/openclaw · 官方文档
本仓库 Nginx 模板	deploy/nginx/testing.xxxx.com

---

概述

本指南描述在云服务器上安装 OpenClaw Gateway（内置 Control UI / Dashboard），并通过 Nginx 反向代理对外提供 HTTP/HTTPS 访问的标准流程。OpenClaw 不是传统 Web 静态站点，无需上传 dist/ 到 /var/www；外网流量经 Nginx 转发至本机 127.0.0.1:18789。

浏览器 → <域名>:80/443 → Nginx → 127.0.0.1:18789 (OpenClaw Gateway + Control UI)

---

前置条件

资源	要求
云主机	1 vCPU / 2 GB RAM 起；公网 IP；root 或 sudo 权限
操作系统	Ubuntu 22.04+（本文默认 Ubuntu 22.04）
域名	已解析至服务器公网 IP，如 <openclaw.example.com>；无域名时可暂用 localhost 本机验证
端口	外网开放 80（HTTP）、443（HTTPS，推荐）；22（SSH，建议限制来源 IP）
禁止公网暴露	18789（Gateway 仅本机监听，由 Nginx 反代）
Nginx	已安装或按步骤一安装
Node.js	官方安装脚本可自动处理；手动安装需 Node 22.19+ 或 Node 24

本项目实测域名：testing.xxxx.com（阿里云 ECS）。

---

步骤一：环境准备

1.1 系统更新与基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ca-certificates gnupg ufw

1.2 防火墙（UFW）

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment 'SSH'
sudo ufw allow 80/tcp comment 'HTTP'
sudo ufw allow 443/tcp comment 'HTTPS'
sudo ufw enable
sudo ufw status verbose

云厂商安全组需同步放行 80/443/22，且 不得 对 0.0.0.0/0 开放 18789。

1.3 时区（可选）

sudo timedatectl set-timezone Asia/Shanghai

---

步骤二：安装 OpenClaw

OpenClaw 以 Gateway 守护进程运行，配置与状态目录默认位于 ~/.openclaw/（配置文件 openclaw.json）。Gateway 不依赖独立数据库；持久化数据在状态目录与 workspace 中。

2.1 推荐：官方安装脚本

curl -fsSL https://openclaw.ai/install.sh | bash

跳过交互式 onboarding（适合自动化）：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

2.2 备选：npm 全局安装

# 需已安装 Node 22.19+ 或 Node 24
npm install -g openclaw@latest
openclaw onboard --install-daemon

2.3 验证 CLI

openclaw --version
openclaw doctor

2.4 Gateway 关键配置（反向代理必改）

通过域名从浏览器访问时，必须配置 认证、允许来源 与 可信代理。同机 loopback 反代场景使用 token 模式，不要使用 trusted-proxy 认证模式。

# 仅监听本机，由 Nginx 对外暴露（推荐）
openclaw config set gateway.bind loopback

# Gateway 端口（默认 18789，一般无需修改）
openclaw config set gateway.port 18789

# 共享 Token 认证（请替换为强随机字符串）
openclaw config set gateway.auth '{"mode":"token","token":"<YOUR_STRONG_TOKEN>"}'

# 浏览器 Origin 白名单（须与地址栏完全一致，含 http/https）
openclaw config set gateway.controlUi.allowedOrigins \
  '["http://<openclaw.example.com>"]'

# 信任本机 Nginx 转发的 X-Forwarded-* 头
openclaw config set gateway.trustedProxies '["127.0.0.1"]'

启用 HTTPS 后，将 allowedOrigins 改为 https://<openclaw.example.com>。

2.5 注册并启动 Gateway 服务

openclaw gateway install
openclaw gateway start
openclaw gateway status

Linux 下通常注册为 systemd 用户服务；若服务未自启，执行 openclaw onboard --install-daemon 或查阅 官方安装文档。

2.6 本机冒烟测试

curl -I http://127.0.0.1:18789
ss -tlnp | grep 18789

期望：HTTP/1.1 200（或 3xx），且监听地址为 127.0.0.1:18789。

---

步骤三：安装与配置 Nginx

3.1 安装 Nginx

sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

3.2 部署站点配置

将本仓库模板复制到 Nginx（或按需修改占位符）：

# 从本仓库同步后执行（路径按实际调整）
sudo cp deploy/nginx/testing.xxxx.com \
        /etc/nginx/sites-available/<openclaw.example.com>

# 编辑 server_name、日志路径等
sudo nano /etc/nginx/sites-available/<openclaw.example.com>

sudo ln -sf /etc/nginx/sites-available/<openclaw.example.com> \
            /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default   # 可选：避免默认站点冲突

核心配置示例（map 块可置于 http 上下文或 conf.d 中）：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream openclaw_dashboard_upstream {
    server 127.0.0.1:18789;
    keepalive 32;
}

server {
    listen 80;
    listen [::]:80;
    server_name <openclaw.example.com>;

    access_log /var/log/nginx/<openclaw.example.com>.access.log;
    error_log  /var/log/nginx/<openclaw.example.com>.error.log;

    client_max_body_size 20m;

    location / {
        proxy_pass http://openclaw_dashboard_upstream;
        proxy_http_version 1.1;

        # WebSocket：Dashboard 强依赖，缺失会导致白屏
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        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;
        proxy_set_header X-Forwarded-Host $host;

        proxy_buffering off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

3.3 校验并重载

sudo nginx -t
sudo systemctl reload nginx

---

步骤四：启动与验证

4.1 确认服务状态

openclaw gateway status
sudo systemctl status nginx

4.2 分层验证

# L1：Gateway 本机
curl -I http://127.0.0.1:18789

# L2：Nginx 本机（带 Host 头）
curl -I -H "Host: <openclaw.example.com>" http://127.0.0.1/

# L3：公网域名
curl -I http://<openclaw.example.com>

4.3 浏览器验证

1. 访问 http://<openclaw.example.com>。
2. 在 Control UI 设置中粘贴 Gateway Token（openclaw config get gateway.auth.token 显示为 __OPENCLAW_REDACTED__ 属正常脱敏）。
3. 打开开发者工具 → Network → WS，确认 WebSocket 握手为 101 Switching Protocols。

---

步骤五（可选）：HTTPS 配置

5.1 Let’s Encrypt（推荐）

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <openclaw.example.com>

5.2 启用 HTTP → HTTPS 跳转

在 Nginx server 块（listen 80）增加：

return 301 https://$host$request_uri;

5.3 同步 OpenClaw Origin

openclaw config set gateway.controlUi.allowedOrigins \
  '["https://<openclaw.example.com>"]'
openclaw gateway restart

5.4 使用自有证书

将证书置于如 /etc/nginx/ssl/<openclaw.example.com>.pem，在 listen 443 ssl 块中配置 ssl_certificate 与 ssl_certificate_key。完整 HTTPS 示例见 deploy/nginx/testing.xxxx.com 注释段。

---

步骤六：安全加固

措施	操作
最小暴露面	gateway.bind 保持 loopback；安全组不开放 18789
强 Token	禁用弱口令；定期轮换 gateway.auth.token
Origin 白名单	仅声明实际访问域名，避免 allowedOrigins: ["*"]
SSH 加固	密钥登录、禁用密码登录、限制 22 来源 IP
隐藏 Nginx 版本	在 /etc/nginx/nginx.conf 的 http 块添加 server_tokens off;
限流（可选）	Nginx limit_req_zone 限制登录/API 突发流量
审计	定期执行 openclaw doctor、openclaw security audit

Nginx 层 IP 白名单示例（取消注释并替换 <YOUR_OFFICE_IP>）：

# allow <YOUR_OFFICE_IP>;
# deny all;

渠道 API Key、LLM 凭证等应置于 Gateway 进程环境或 ~/.openclaw/.env，勿提交版本库。

---

验证方法

层级	命令 / 操作	期望结果
Gateway	curl -I http://127.0.0.1:18789	200 OK
进程	openclaw gateway status	Runtime: running
Nginx	curl -I http://<openclaw.example.com>	200 或 301→HTTPS
WebSocket	浏览器 DevTools → WS	101，无持续断开
日志	openclaw logs --follow	无 origin not allowed / AUTH_TOKEN_*

# 并行观察 Nginx 与 Gateway 日志
sudo tail -f /var/log/nginx/<openclaw.example.com>.error.log
openclaw logs --follow

---

常见问题

1. 502 Bad Gateway

原因：Nginx 无法连接 127.0.0.1:18789，通常为 Gateway 未启动或端口不一致。

openclaw gateway status
openclaw gateway restart
ss -tlnp | grep 18789

2. 页面白屏 / Gateway Not Connected

原因：WebSocket 反代未配置，或 allowedOrigins 未包含浏览器实际 Origin。

• 检查 Nginx 是否包含 Upgrade / Connection $connection_upgrade。
• 确认 gateway.controlUi.allowedOrigins 与地址栏协议、域名一致。
• 浏览器 Console 若出现 origin not allowed，按上文修正 Origin 后 openclaw gateway restart。

3. 认证失败（AUTH_TOKEN_MISSING / MISMATCH）

原因：Control UI 未填写 Token，或 Token 与配置不一致。

# 重新设置强 Token 后重启
openclaw config set gateway.auth '{"mode":"token","token":"<NEW_TOKEN>"}'
openclaw gateway restart

在浏览器 Control UI 设置中粘贴同一 Token。config get 输出 __OPENCLAW_REDACTED__ 不代表未配置。

4. gateway.bind: lan 与反代并存

lan 会使 Gateway 监听 0.0.0.0:18789，增大暴露面。反代架构推荐 loopback；若必须使用 lan，务必在安全组封锁 18789。

---

附录：架构对照（与静态站点部署的差异）

项	EnjoyTerm 官网（Next.js）	OpenClaw Dashboard
制品	rsync 至 /var/www/<domain>/	无需上传 Web 静态包
进程	PM2 → Node 64000	openclaw gateway → 18789
配置	.env / Next 环境变量	~/.openclaw/openclaw.json
反代要点	HTTP 即可	必须支持 WebSocket

---

修订记录

版本	日期	说明
v1.0	2026-06-17	首版：Ubuntu + Nginx 反代 + Gateway token 认证