OpenClaw 配置 Nginx 反向代理及 HTTPS 安全接入指南

OpenClaw 配置 Nginx 反向代理及 HTTPS 安全接入指南

将 OpenClaw Gateway 安全地暴露到公网，并通过 HTTPS 和登录保护确保访问安全。

前言

OpenClaw 是一个强大的 AI 助手网关，默认情况下它只监听本地回环地址 (127.0.0.1:18789)。如果你想从外部网络访问 Control UI，或者为团队提供安全的访问入口，配置 Nginx 反向代理是最佳实践。

本文将介绍如何：

• ✅ 配置 Nginx 反向代理到 OpenClaw
• ✅ 启用 HTTPS (Let's Encrypt SSL 证书)
• ✅ 添加 Basic Auth 登录保护
• ✅ 配置 OpenClaw 信任代理模式

环境准备

• 服务器: CentOS Stream 9 / Ubuntu 20.04+ / Debian 10+
• 域名: 已解析到服务器 IP（本文以 your-domain.com 为例）
• OpenClaw: 已安装并运行在本地模式
• 端口: 80/443 未被占用

步骤一：安装 Nginx 和 Certbot

# CentOS/RHEL
sudo dnf install -y nginx certbot python3-certbot-nginx
# Ubuntu/Debian
sudo apt update && sudo apt install -y nginx certbot python3-certbot-nginx
# 启动 Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

步骤二：配置 OpenClaw 信任代理模式

编辑 ~/.openclaw/openclaw.json，在 gateway 部分添加以下配置：

{"gateway":{"port":18789,"mode":"local","bind":"loopback","trustedProxies":["127.0.0.1"],"auth":{"mode":"trusted-proxy","trustedProxy":{"userHeader":"x-forwarded-user","requiredHeaders":["x-forwarded-proto","x-forwarded-host"]}},"controlUi":{"allowedOrigins":["https://your-domain.com"]}}}

关键参数说明：

参数	说明
bind: "loopback"	只监听本地地址，禁止外部直接访问
trustedProxies	信任的代理服务器 IP，此处为 Nginx
mode: "trusted-proxy"	启用信任代理认证模式
userHeader	Nginx 传递用户身份的 Header
allowedOrigins	允许的 Control UI 来源域名

重启 OpenClaw Gateway：

openclaw gateway restart

步骤三：配置 Nginx 反向代理

创建 /etc/nginx/conf.d/openclaw.conf：

# OpenClaw Nginx 配置
# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

# HTTPS 服务
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    # SSL 证书路径（步骤四会自动配置）
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    
    # 安全响应头
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    # 日志配置
    access_log /var/log/nginx/openclaw-access.log;
    error_log /var/log/nginx/openclaw-error.log;
    
    location / {
        # WebSocket 支持（必需）
        proxy_pass http://127.0.0.1:18789;
        # 核心：这里清空认证头防止冲突
        proxy_set_header Authorization "";
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 转发用户身份（信任代理模式必需）
        proxy_set_header X-Forwarded-User $remote_user;
        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_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 超时设置（WebSocket 长连接）
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 86400s;
        proxy_buffering off;
    }
}

测试并重载配置：

nginx -t
nginx -s reload

步骤四：申请 SSL 证书

使用 Let's Encrypt 免费证书：

# 申请证书
sudo certbot --nginx -d your-domain.com
# 测试自动续期
sudo certbot renew --dry-run

Certbot 会自动：

• 生成 SSL 证书
• 修改 Nginx 配置添加证书路径
• 设置自动续期任务

步骤五：添加登录保护（可选但强烈建议）

为了防止未授权访问，建议添加 Basic Auth 登录。

1. 创建密码文件

# 创建账号密码（用户名：admin）
sudo sh -c 'echo "admin:$(openssl passwd -apr1 你的密码)" > /etc/nginx/.htpasswd'
# 添加更多用户
sudo sh -c 'echo "用户名:$(openssl passwd -apr1 密码)" >> /etc/nginx/.htpasswd'

2. 启用 Basic Auth

在 Nginx 配置中添加两行：

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    # 添加登录保护
    auth_basic "OpenClaw Login";
    auth_basic_user_file /etc/nginx/.htpasswd;
    location / {
        # ... 原有配置
    }
}

重载 Nginx：

sudo nginx -t && sudo systemctl reload nginx

验证部署

访问 https://your-domain.com，你应该看到：

1. 🔒 浏览器显示安全锁（SSL 生效）
2. 📝 弹出登录框（Basic Auth）
3. 🤖 登录后进入 OpenClaw Control UI

常见问题

1. "origin not allowed" 错误

原因: allowedOrigins 配置不匹配
解决: 在 openclaw.json 中添加你的访问地址：

"allowedOrigins":["https://your-domain.com"]

2. WebSocket 连接失败 (1008 unauthorized)

原因: 缺少必要的转发 Headers
解决: 确保 Nginx 配置中包含：

proxy_set_header X-Forwarded-User $remote_user;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;

3. 证书续期失败

检查：

sudo certbot certificates
sudo certbot renew --dry-run

手动续期：

sudo certbot renew
sudo systemctl reload nginx

安全建议

1. 定期更换密码: 建议每 3-6 个月更换一次 Basic Auth 密码
2. 限制访问来源: 如需更高安全性，可在 Nginx 中添加 IP 白名单

访问日志监控: 定期检查异常访问

sudo tail -f /var/log/nginx/openclaw-access.log

防火墙设置: 只开放 80/443 端口，禁止外部访问 18789

sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload

总结

通过本文的配置，你已经完成了：

• ✅ OpenClaw 信任代理模式配置
• ✅ Nginx 反向代理 + HTTPS
• ✅ Let's Encrypt SSL 证书
• ✅ Basic Auth 登录保护

现在你可以安全地从任何地方访问你的 OpenClaw Control UI 了！