使用Nginx为OpenClaw反向代理的实现
一、前提与约束
- 无域名:仅通过
https://<服务器IP>访问,需使用自签名证书(浏览器会提示不安全,需手动信任或继续访问)。 - OpenClaw 要求:远程访问必须使用 wss://,不能使用明文 ws://;网关需保持
bind: "loopback",仅由 Nginx 代理访问。 - 认证:在 OpenClaw 网关侧启用 token认证(也可选用 password,见后文)。
二、OpenClaw 网关配置(密码认证)
在配置 Nginx 之前,先让 OpenClaw 使用密码认证,并允许来自 Nginx 的 Origin(即 https://<你的IP>)。
2.1 编辑~/.openclaw/openclaw.json
在 gateway 段中设置:
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"controlUi": {
"allowedOrigins": [
"http://127.0.0.1:18789",
"http://localhost:18789",
"https://YOUR_SERVER_IP"
]
},
"auth": {
"mode": "token",
"password": "你的访问令牌"
},
"trustedProxies": ["127.0.0.1"]
}说明:
- 将
YOUR_SERVER_IP替换为服务器公网 IP(例如x.x.x.x)。若通过https://IP:443访问,Origin 一般为https://YOUR_SERVER_IP,无需写端口。 trustedProxies为可选。当 Nginx 与网关同机部署时,填["127.0.0.1"]可让网关信任来自本机(Nginx)的代理头,消除日志中的 "Proxy headers detected from untrusted address" 警告。auth.mode: "password"表示使用密码认证;客户端需在请求中携带Authorization: Bearer <密码>或通过 URL 参数传递(见下文访问方式)。
2.2 重启网关
systemctl --user restart openclaw-gateway.service # 或 openclaw gateway start
三、安装 Nginx
1. Alibaba Cloud Linux 3 / CentOS 8 / RHEL 8
# 1. 更新系统包 sudo dnf update -y# 2. 添加 Nginx 官方稳定源 sudo tee /etc/yum.repos.d/nginx.repo <<-'EOF' [nginx-stable] name=nginx stable repo baseurl=https://nginx.org/packages/rhel/8/$basearch/ gpgcheck=1 enabled=1 gpgkey=https://nginx.org/keys/nginx_signing.key module_hotfixes=true EOF # 3. 安装 Nginxsudo dnf install -y nginx # 4. 验证安装 nginx -v
2. CentOS 7 / Alibaba Cloud Linux 2
# 1. 更新系统包 sudo yum update -y # 2. 添加 Nginx 官方稳定源 sudo tee /etc/yum.repos.d/nginx.repo <<-'EOF' [nginx-stable] name=nginx stable repo baseurl=https://nginx.org/packages/centos/7/$basearch/ gpgcheck=1 enabled=1 gpgkey=https://nginx.org/keys/nginx_signing.key EOF # 3. 安装 Nginxsudo yum install -y nginx # 4. 验证安装 nginx -v
3. Ubuntu / Debian
# 1. 更新系统包 sudo apt update && sudo apt upgrade -y # 2. 安装 Nginxsudo apt install -y nginx # 3. 验证安装 nginx -v
四、生成自签名证书(仅 IP、无域名)
无域名时无法使用 Let's Encrypt,需自签名证书。将 YOUR_SERVER_IP 换成实际 IP(如 x.x.x.x):
sudo mkdir -p /etc/nginx/ssl sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout /etc/nginx/ssl/openclaw.key \ -out /etc/nginx/ssl/openclaw.crt \ -subj "/CN=OpenClaw" \ -addext "subjectAltName=IP:YOUR_SERVER_IP"
注意:若使用公网 IP,请填公网 IP;若仅内网访问,填内网 IP。浏览器访问会提示"连接不是私密连接",需手动接受或继续访问方可使用。
五、Nginx 反向代理配置
5.1 创建站点配置
找到Nginx配置目录,我的系统是 Alibaba Cloud Linux 3,Nginx 配置目录是
/etc/nginx/conf.d/
创建配置文件
vim /etc/nginx/conf.d/openclaw.conf
写入以下内容(将 YOUR_SERVER_IP 替换为实际 IP):
# OpenClaw 反向代理(仅 IP、无域名,HTTPS + WSS)
# 上游:OpenClaw 网关默认端口 18789,仅监听本机
upstream openclaw_backend {
server 127.0.0.1:18789;
keepalive 64;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
# 无域名时用 IP 或 default_server
server_name YOUR_SERVER_IP;
ssl_certificate /etc/nginx/ssl/openclaw.crt;
ssl_certificate_key /etc/nginx/ssl/openclaw.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
# 日志(可选)
access_log /var/log/nginx/openclaw_access.log;
error_log /var/log/nginx/openclaw_error.log;
location / {
proxy_pass http://openclaw_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header 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_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}要点:
Upgrade与Connection "upgrade"用于 WebSocket 升级,否则 Control UI 与 wss 无法正常工作。proxy_read_timeout/proxy_send_timeout拉长,避免长连接被 Nginx 断开。
5.2 启用站点并检查配置
nginx -t # 测试配置是否正确 systemctl restart nginx # 重启生效
六、防火墙与安全组
- 放行 443(HTTPS)。
- 若希望 HTTP 自动跳转 HTTPS,可加 80 并做 redirect(见下节)。
- 不要对公网开放 18789,网关仅对本机监听。
七、访问方式
7.1 浏览器访问 Control UI
- 地址:https://YOUR_SERVER_IP(例如 https://x.x.x.x)。
- 首次会提示证书不受信任,选择"高级" → "继续前往"即可(自签名证书正常现象)。
密码认证:
若使用 token 模式:
https://YOUR_SERVER_IP/#token=你的访问令牌
八、故障排查
8.1 反代后首次访问的典型问题与处理顺序
通过 Nginx 反代首次用浏览器访问 https://YOUR_SERVER_IP/#token=... 时,常会依次遇到下面三类情况,按顺序处理即可。
1)提示 "origin not allowed"
- 原因:浏览器请求的 Origin 为 https://YOUR_SERVER_IP(经 Nginx 访问时的来源),未在网关白名单中。
- 处理:在 ~/.openclaw/openclaw.json 的 gateway.controlUi.allowedOrigins 中增加一项 https://YOUR_SERVER_IP(将 YOUR_SERVER_IP 换成实际 IP,无需写 :443)。保存后重启网关。
2)日志出现 "Proxy headers detected from untrusted address"
- 原因:网关收到了 Nginx 转发的
X-Forwarded-For等代理头,但未把 Nginx 所在地址视为可信代理。 - 处理:在
gateway中增加"trustedProxies": ["127.0.0.1"](Nginx 与网关同机时)。保存后重启网关。此步为可选,仅用于消除警告并改善"经代理的本地连接"识别。
3)连接失败:pairing required / not-paired(WebSocket code 1008)
- 原因:经反代访问时,浏览器设备会被视为"远程设备",需在网关上完成一次设备配对后才能建立 WebSocket。与 Nginx 配置无关。
- 处理:在运行网关的服务器上执行:
openclaw devices list # 查看 Pending 列表中的 Request ID openclaw devices approve <Request ID> # 批准该设备,例如 approve <Request ID>
批准后,刷新浏览器并再次访问
https://YOUR_SERVER_IP/#token=你的令牌,Control UI 应能正常连接。地址栏从/跳转到/chat?session=main是前端路由行为,属正常。
8.2 常见现象速查表
| 现象 | 可能原因 | 处理 |
| 502 Bad Gateway | 网关未运行或 Nginx 连不上 18789 | 在服务器上执行 curl -I http://127.0.0.1:18789/,应为 200/3xx;执行 openclaw gateway start 或重启 systemd 服务。 |
| origin not allowed | 未把 https://YOUR_SERVER_IP 加入 allowedOrigins | 在 gateway.controlUi.allowedOrigins 中增加 https://YOUR_SERVER_IP,重启网关。 |
| Proxy headers from untrusted address(日志) | 未配置可信代理 | 可选:在 gateway 中增加 "trustedProxies": ["127.0.0.1"],重启网关。 |
| pairing required / not-paired(1008) | 浏览器设备尚未在网关上配对 | 在服务器执行 openclaw devices list,再 openclaw devices approve <Request ID>。 |
| 能打开页面但"与网关断开" | WebSocket 未正确代理或 Origin 未放行 | 确认 Nginx 配置中有 proxy_http_version 1.1、Upgrade、Connection "upgrade";确认 gateway.controlUi.allowedOrigins 包含 https://YOUR_SERVER_IP。 |
| 认证失败 | 密码/ token 错误或未传 | 确认 openclaw.json 中 auth.mode 与 auth.password/auth.token 一致;URL 用 ?token= 或 ?password=(视版本而定),不要用 #。 |
| SECURITY ERROR (ws 明文) | 直接访问了 ws:// 或 http://IP:18789 | 必须通过 Nginx 的 https:// / wss:// 访问,不要直连 18789。 |
九、参考链接
到此这篇关于使用Nginx为OpenClaw反向代理的实现的文章就介绍到这了,更多相关Nginx OpenClaw反向代理内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!
相关文章
nginx配置proxy_pass中url末尾带/与不带/的区别详解
这篇文章主要介绍了nginx配置proxy_pass中url末尾带/与不带/的区别详解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧2020-11-11
HTTP 499 状态码 nginx下 499错误的解决办法
HTTP状态码出现499错误有多种情况,499错误是什么?Nginx 499错误的原因及解决方法,下面跟着脚本之家小编一起学习吧2016-06-06


最新评论