OpenClaw 配置 Nginx 反向代理完整指南

OpenClaw 配置 Nginx 反向代理完整指南

将 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（本文以www.zhonghongwei.site为例）
• OpenClaw: 已安装并运行在本地模式
• 端口: 80/443 未被占用

步骤一：安装 Nginx 和 Certbot

# CentOS/RHELsudodnfinstall-ynginx certbot python3-certbot-nginx# Ubuntu/Debiansudoaptupdatesudoaptinstall-ynginx certbot python3-certbot-nginx# 启动 Nginxsudosystemctl start nginxsudosystemctlenablenginx

步骤二：配置 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://www.zhonghongwei.site"]}}}

关键参数说明：

重启 OpenClaw Gateway：

openclaw gateway restart

步骤三：配置 Nginx 反向代理

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

# OpenClaw Nginx 配置 # HTTP 重定向到 HTTPS server { listen 80; server_name www.zhonghongwei.site; return 301 https://$host$request_uri; } # HTTPS 服务 server { listen 443 ssl http2; server_name www.zhonghongwei.site; # SSL 证书路径（步骤四会自动配置） ssl_certificate /etc/letsencrypt/live/www.zhonghongwei.site/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/www.zhonghongwei.site/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-tnginx-sreload

步骤四：申请 SSL 证书

使用 Let’s Encrypt 免费证书：

# 申请证书sudocertbot--nginx-dwww.zhonghongwei.site# 测试自动续期sudocertbot renew --dry-run

Certbot 会自动：

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

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

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

1. 创建密码文件

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

2. 启用 Basic Auth

在 Nginx 配置中添加两行：

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

重载 Nginx：

sudonginx-t&&sudosystemctl reload nginx

验证部署

访问https://www.zhonghongwei.site，你应该看到：

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

常见问题

1. “origin not allowed” 错误

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

"allowedOrigins":["https://www.zhonghongwei.site"]

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. 证书续期失败

检查:

sudocertbot certificatessudocertbot renew --dry-run

手动续期:

sudocertbot renewsudosystemctl reload nginx

安全建议

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

   sudofirewall-cmd--permanent--add-service=httpssudofirewall-cmd--permanent--add-service=httpsudofirewall-cmd--reload

2. 定期更换密码: 建议每 3-6 个月更换一次 Basic Auth 密码

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

   sudotail-f/var/log/nginx/openclaw-access.log

4. 限制访问来源: 如需更高安全性，可在 Nginx 中添加 IP 白名单

总结

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

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

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

相关链接:

• OpenClaw 官方文档
• Nginx 官方文档
• Let’s Encrypt

配置文件备份:

• ~/.openclaw/openclaw.json
• /etc/nginx/conf.d/openclaw.conf
• /etc/nginx/.htpasswd

小技巧：直接把这个博客内容发给openclaw，让它帮你配置。