2026 OpenClaw 生产向反代与 TLS：
Nginx/Caddy 下 WebSocket、子路径与 Gateway 的 502/握手失败分诊清单

约 16 分钟阅读 · MACCOME

Gateway 在容器里「看起来正常」，一挂到 Nginx/Caddy 后面就出现 502、WebSocket 握手失败或无限重定向？ 本文锁定入口反代 + TLS 终止 + WebSocket 升级这一层，与《Docker 网络分诊》互补：前者管包与包之间谁看得见谁，本篇管浏览器到 Gateway 的 HTTP/1.1 升级链路与路径是否正确。你将拿到六类高频误区、两张拓扑/症状对照表、可复制配置片段、六步上线 Runbook，以及三条应写进值班的硬指标。读完能先判断该改 Upgrade 头还是该回去查上游 127.0.0.1:18789。

反代层最常见的六个误区（为什么「curl 上游通」仍可能 502）

  1. 只配了 proxy_pass 却没升 HTTP/1.1 与 Upgrade：浏览器走 WebSocket 时边缘返回 400/502，日志却像「Gateway 挂了」。
  2. 子路径双写前缀：反代剥离了 /openclaw，应用仍按根路径生成绝对 URL，导致静态资源与 WS 路径分裂。
  3. 把 HTTP/2 与 WS 混在同一监听上却不验证 ALPN：部分组合下需为 WS 单独 server 或显式回落 HTTP/1.1，否则握手表现为偶发失败。
  4. proxy_read_timeout 过短：长推理或通道消息突发时连接被边缘静默掐断，客户端重连风暴误伤上游。
  5. 证书链不完整却只修了浏览器告警：某些自动化客户端校验更严，表现为「桌面 CLI 通、Web UI 偶发失败」。
  6. CDN 默认缓存或短空闲超时：控制面 WebSocket 被中间层当普通 GET 缓存或提前断开，症状像随机掉线。

下面用拓扑表把「同机反代 / 独立反代机 / 子域名 / 子路径」的取舍压平，再进入 Header 检查表与分症状矩阵。

拓扑选型：同机、独立机、子路径与子域名如何影响排障

同机反代（Nginx/Caddy 与 Gateway 同宿主机）排障路径最短：curl -v http://127.0.0.1:18789 即可验证上游。独立反代机多一跳，需同步核对安全组、内网 DNS 与 TLS SNI。子域名方案通常避免路径剥离与 Cookie Path 的纠缠；子路径适合统一域名策略，但必须在反代与 OpenClaw 基址配置两侧只剥一次前缀，并用浏览器开发者工具确认 WS URL 是否仍指向预期 wss:// 路径。

实务上建议在变更单里强制附两张截图：一张是浏览器地址栏最终落点，一张是 Network 面板里 WebSocket 握手的 Request URL。没有这两张图时，评审很容易把问题误判为「模型超时」或「通道 OAuth」，从而在错误平面浪费发布时间。若你还同时在跑企业 HTTPS 代理，记得区分「办公网浏览器」与「数据中心反代机」两条路径——前者可能注入 PAC，后者通常直连，症状不一致是常态而非异常。

HTTP/2 在边缘监听、上游仍走 HTTP/1.1 WebSocket 的组合在 2026 年仍非常普遍：关键是确认从客户端到反代与从反代到 Gateway两段里，哪一段允许升级。不要在未抓包的情况下同时打开「强制 H2」与「自定义 WS 路径重写」，否则排障会退化成玄学。

拓扑适用运维收益典型坑
同机反代 + 回环上游单台 VPS / 远程 Mac 常驻本机 curl 即可分诊；TLS 与进程同日志卷误绑 0.0.0.0 放大暴露面，需防火墙兜底
独立反代机多后端、蓝绿、WAF 前置边缘与计算池解耦；证书集中续期内网路由、SNI、健康检查目标易漂移
子域名WS 与站点主域分离路径语义清晰；CDN 规则好写多证书与 HSTS 策略要单独评审
子路径单入口品牌域名用户记忆成本低前缀剥离、重定向循环、资源根路径错位

Nginx 与 Caddy：WebSocket 必备 Header 与超时对照

无论选哪种实现，边缘都要保证：升级到 HTTP/1.1、透传或重建 Connection: upgrade 与 Upgrade: websocket，并为长连接设置大于模型最慢分位的读超时。下表用于 Code Review 勾选。

另有一条易忽略：反代缓冲。对普通 API 开启 proxy_buffering 可能提升吞吐，但对流式响应或长保持连接有时会引入额外延迟甚至截断感知；若你启用了流式通道或类 SSE 行为，要在 staging 用真实负载压一遍再开默认缓冲。

检查项Nginx 要点Caddy 要点
协议版本proxy_http_version 1.1;reverse_proxy 默认 HTTP/1.1；留意显式 transport
Upgrade 链Upgrade $http_upgrade; Connection "upgrade";多数场景自动处理；自定义需 header_up
Host 与原始客户端 IPproxy_set_header Host $host;、X-Forwarded-*header_up Host {host}；信任反代 hops
长连接proxy_read_timeout / send_timeouttransport http { read_timeout ... }（版本语法以文档为准）
大请求体client_max_body_sizerequest_body 限制类指令
nginx
# 片段：反代到本机 Gateway（端口按你的部署为准，示例 18789）
location / {
  proxy_pass http://127.0.0.1:18789;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 3600s;
  proxy_send_timeout 3600s;
}
Caddyfile
# 片段：TLS 自动 + 反代 WebSocket 上游
openclaw.example.com {
    reverse_proxy 127.0.0.1:18789 {
        header_up Host {host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}
info

提示：改配置后先用 curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" http://127.0.0.1:18789/ 在上游侧验证握手语义，再测公网 wss://；否则会在 TLS 与反代两层之间来回甩锅。

分症状矩阵：502、413、101 失败、重定向与证书

把症状映射到「边缘 / 上游 / 应用配置」三类，避免一上来就重建容器。若表格指向容器网络，请回到《Docker 网络分诊》；若通道已通但 Slack/Telegram 不回，请对照《通道接入排查》。

遇到「仅生产环境复现、预发完全正常」时，优先比对三处 diff：证书链是否同一 CA、CDN/WAF 规则集版本、以及反代 map/if 里是否对特定 User-Agent 走了分支。很多 502 其实是边缘规则误杀，与 OpenClaw 版本无关。

现象优先怀疑验证动作
502 Bad Gateway上游未监听、防火墙、错误 socket 族反代机 curl 上游；看 error.log 的 upstream timed out / refused
413 Request Entity Too Large边缘 client_max_body_size 过小调大并 reload；同步 CDN/WAF 侧限制
WS 非 101Upgrade 丢失、路径被重写、http→https 跳转打断浏览器 Network 里看握手响应码；对照 location 顺序与 return 301
重定向循环X-Forwarded-Proto 未设却强制 https临时关闭边缘 HSTS 试验；补全 forwarded 头
证书告警 / 部分客户端失败链不完整、错误 SNI、混用 IP 证书openssl s_client -servername 拉链；校时 NTP

六步 Runbook：从试点域名到可值班的生产入口

  1. 冻结 URL 方案：写清对外 https:// 基址、是否子路径、WS 是否与 HTTP 同 host。
  2. 本机探活：在反代机上直连回环上游，确认 OpenClaw 进程与端口与文档一致（示例 18789）。
  3. 最小 Nginx/Caddy 片段：先只反代健康检查路径，再放开全站；每步可回滚。
  4. 抓一条完整 WS 会话：用浏览器与 CLI 各验证一次，日志对齐 request_id（若有）。
  5. 叠安全：IP 允许列表、限流、WAF 自定义规则；与《Docker 生产 Runbook》中的令牌策略对齐。
  6. 观测基线：记录上游 P95、每分钟 WS 重连次数、证书剩余天数，写入告警阈值。
  7. 发布回滚演练：在维护窗内做一次「只回滚反代配置、不回滚镜像」的练习，确保值班文档里有一条可执行命令序列而不是口头描述。

三条应写进 Grafana/值班手册的硬指标

  1. 上游 RTT P95：从反代 worker 到 127.0.0.1:18789 或内网 VIP，独立于公网延迟，便于判断「慢在边缘还是慢在 Gateway」。
  2. WebSocket 非正常关闭率：按分钟聚合，突增常与超时、发布、或模型侧 429 相关，应与 provider 路由篇对照。
  3. 证书剩余有效期：小于 14 天触发工单；Let's Encrypt 与商业 CA 的续期失败要在 staging 先演练。

若你已接入集中日志，请把「反代 access 5xx 率」与「Gateway 应用日志错误率」做双轴对齐**：只有一侧飙升时，责任边界一目了然，也方便在复盘会上用数据而不是体感说话。

为什么「只在笔记本上跑 Gateway」难扛生产入口与长期自动化

个人设备上的反代实验可以快速验证配置片段，但休眠、VPN 切换与家庭宽带入站不稳定会把 TLS 与证书续期变成手工活；团队也无法对 502 率做可合同化的 SLO。把反代 + 常驻 Gateway放到可 7×24 的专用主机（例如租用的 Apple Silicon 远程 Mac 或受控 VPS），才能把限流、证书与日志留存做成标准变更，而不是「谁笔记本还醒着谁就是运维」。一旦入口稳定，OpenClaw 与 CI、签名流水线的联动才谈得上可审计、可交接。

纯自建反代栈还要持续跟进 OpenSSL、Nginx 与系统 CVE；对于要把 OpenClaw 与 CI、签名、多通道机器人长期绑在一起的团队，稳定独占算力 + 清晰地区/租期往往比反复折腾家用出口更省总账。MACCOME 的 Mac 云主机提供多地区节点与可预期的租期档位，适合作为「TLS 终止背后的那台干净常驻机」：先把《三平台安装与选型》里的目录与权限边界落地，再按 租赁价格 与区域页把执行层托管到合同化环境，边缘反代只负责入口策略与观测。

连接、会话与通道类问题也可在 帮助中心 按关键词检索；需要图形化排错时，仍可结合远程桌面策略与站内 SSH/VNC 类文章规划窗口。

常见问题

502 时先查反代还是查 Docker？

先在反代机上 curl 回环上游；不通再回《Docker 网络分诊》。需要套餐对比时见 Mac mini 租赁价格。

子路径和子域名怎么选？

子域名通常少踩剥离坑；子路径需两侧基址一致。安装入口仍建议从 三平台安装指南 对齐版本。

CDN 后面 WS 掉线？

关缓存、拉长空闲超时，或为控制面子域绕过 CDN。通道侧异常请对照 Slack/Discord/Telegram 排查篇。

日志与工单去哪里？

企业变更可走 帮助中心 工单，避免在生产群里丢半张 Nginx 配置。