Shell / BashAI
OpenClaw 配置 Nginx 反向代理指南
介绍如何将 OpenClaw Gateway 通过 Nginx 反向代理安全暴露到公网。主要步骤包括安装 Nginx 和 Certbot，配置 OpenClaw 信任代理模式，设置 HTTPS 证书（Let's Encrypt），添加 Basic Auth 登录保护，以及 WebSocket 支持。同时提供了常见问题排查和安全建议，确保服务可被外部网络安全访问。
介绍如何将 OpenClaw Gateway 通过 Nginx 反向代理安全暴露到公网。主要步骤包括安装 Nginx 和 Certbot，配置 OpenClaw 信任代理模式，设置 HTTPS 证书（Let's Encrypt），添加 Basic Auth 登录保护，以及 WebSocket 支持。同时提供了常见问题排查和安全建议，确保服务可被外部网络安全访问。
将 OpenClaw Gateway 安全地暴露到公网，并通过 HTTPS 和登录保护确保访问安全。
OpenClaw 是一个强大的 AI 助手网关，默认情况下它只监听本地回环地址 (127.0.0.1:18789)。如果你想从外部网络访问 Control UI，或者为团队提供安全的访问入口，配置 Nginx 反向代理是最佳实践。
本文将介绍如何：
your-domain.com 为例）# 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.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
创建 /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
使用 Let's Encrypt 免费证书：
# 申请证书
sudo certbot --nginx -d your-domain.com
# 测试自动续期
sudo certbot renew --dry-run
Certbot 会自动：
为了防止未授权访问，建议添加 Basic Auth 登录。
# 创建账号密码（用户名：admin）
sudo sh -c 'echo "admin:$(openssl passwd -apr1 你的密码)" > /etc/nginx/.htpasswd'
# 添加更多用户
sudo sh -c 'echo "用户名:$(openssl passwd -apr1 密码)" >> /etc/nginx/.htpasswd'
在 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，你应该看到：
原因: allowedOrigins 配置不匹配
解决: 在 openclaw.json 中添加你的访问地址：
"allowedOrigins": ["https://your-domain.com"]
原因: 缺少必要的转发 Headers 解决: 确保 Nginx 配置中包含：
proxy_set_header X-Forwarded-User $remote_user;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
检查：
sudo certbot certificates
sudo certbot renew --dry-run
手动续期：
sudo certbot renew
sudo systemctl reload nginx
访问日志监控: 定期检查异常访问
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 Control UI 了！
相关链接：
配置文件备份：
~/.openclaw/openclaw.json/etc/nginx/conf.d/openclaw.conf/etc/nginx/.htpasswd
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online