使用Nginx为OpenClaw反向代理的实现

 更新时间:2026年04月10日 09:14:16   作者:positiveFunction2  
本文详细介绍了如何通过Nginx反向代理配置OpenClaw网关的无域名HTTPS访问方案,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧

一、前提与约束

  • 无域名:仅通过 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;
    }
}

要点

  • UpgradeConnection "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 Linux安装部署详细教程

    Nginx Linux安装部署详细教程

    这篇文章主要介绍了Nginx Linux安装部署详细教程,本文通过图文实例代码相结合给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2020-06-06
  • 通过nginx实现方向代理过程图解

    通过nginx实现方向代理过程图解

    这篇文章主要介绍了通过nginx实现方向代理过程图解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2020-02-02
  • nginx做白名单和限流的完整过程

    nginx做白名单和限流的完整过程

    ​ 我们都知道nginx里面是可以用lua脚本做一些稍微复杂些的逻辑处理的,要使用lua脚本需要编译lua解释器,时间有限我直接用了openresty,它集成了lua和nginx,这篇文章主要介绍了nginx做白名单和限流,需要的朋友可以参考下
    2024-02-02
  • nginx配置proxy_pass中url末尾带/与不带/的区别详解

    nginx配置proxy_pass中url末尾带/与不带/的区别详解

    这篇文章主要介绍了nginx配置proxy_pass中url末尾带/与不带/的区别详解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-11-11
  • Nginx负载均衡(架构之路)详解

    Nginx负载均衡(架构之路)详解

    这篇文章主要为大家详细介绍了Nginx负载均衡的相关资料,如何配置三台服务器,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2017-07-07
  • Nginx方向代理wss或ws的实现示例

    Nginx方向代理wss或ws的实现示例

    本文主要介绍了Nginx方向代理wss或ws的实现示例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2023-10-10
  • HTTP 499 状态码 nginx下 499错误的解决办法

    HTTP 499 状态码 nginx下 499错误的解决办法

    HTTP状态码出现499错误有多种情况,499错误是什么?Nginx 499错误的原因及解决方法,下面跟着脚本之家小编一起学习吧
    2016-06-06
  • Nginx代理中使用斜杠的区别小结

    Nginx代理中使用斜杠的区别小结

    在使用nginx代理的过程中,斜线是一个非常重要的符号,因为它涉及到了请求路径的匹配问题,本文主要介绍了Nginx代理中使用斜杠的区别小结,感兴趣的可以了解一下
    2023-09-09
  • Nginx部署React项目时重定向循环问题的解决方案

    Nginx部署React项目时重定向循环问题的解决方案

    Nginx在处理React项目请求时出现重定向循环,通常是由于`try_files`配置错误或`root`路径配置不当导致的,本文给大家详细介绍了相关的解决方法,需要的朋友可以参考下
    2025-05-05
  • Nginx 代理与负载均衡详解

    Nginx 代理与负载均衡详解

    这篇文章主要介绍了Nginx 代理与负载均衡详解的相关资料,需要的朋友可以参考下
    2017-05-05

最新评论