用编码代理时有个高频故障：浏览器里官网开得好好的，Claude Code 或 Codex 却反复重连。多数人第一反应是"代理挂了"，于是换节点、重启工具，运气好撞对了，运气不好折腾一小时。正确的做法是理解工具的网络链路，按跳逐个排查。这篇给出一条可复用的定位路径。
为什么"官网能开"不能证明链路通
浏览器访问和 CLI 工具访问走的不一定是同一条路。三个常见差异：CLI 可能不读系统代理设置（读环境变量 HTTP_PROXY/HTTPS_PROXY）；CLI 访问的 API 域名与官网域名不同（官网走 cdn.example.com，API 走 api.example.com）；部分代理规则只分流了官网域名，API 域名走了直连或另一个出口。"官网能开"只证明浏览器那条路通，对 CLI 链路没有任何证明力。
排查路径：按跳定位
第一步抄清楚三个地址：浏览器打开的官网 URL、文档写的 API Base URL、客户端配置的 Base URL——三者可能各有不同的认证、超时和代理规则。同时确认客户端需要的协议（Chat Completions、Responses 还是 Messages），"OpenAI 兼容"五个字不能保证工具调用和流式事件都可用。
第二步查代理环境变量。CLI 读的是 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY，浏览器用的是系统设置——两套配置互不相通。只列变量名即可，别把带凭证的完整代理 URL 复制出来：
env | cut -d= -f1 | grep -E '^(HTTP(S)?_PROXY|ALL_PROXY|NO_PROXY|http(s)?_proxy|all_proxy|no_proxy)$'
空值说明 CLI 在直连——需要代理的网络环境里这就是根因。有值则用最小 API 请求（curl 目标端点）分别在原配置和明确记录的替代网络条件下观察 HTTP 状态。"关掉代理试一次"只能当测试手段，不是修复方案，更不能为了测试全局清掉已有配置。
第三步把鉴权单独验收。401 先查凭证是否被读取、是否过期；403 查账号权限、可用模型与接口范围。多模型聚合入口尤其要确认：目录页列出某个型号，不代表你的账号在该分组下真能调用它。验收不要用一句"你好"糊弄，要用带读文件或工具调用的最小无副作用任务走完整流程。
三类根因对号入座
按排查结果归因，基本只有三类：
- 环境变量缺失或失效：CLI 直连被墙/被防火墙拦。解法是补
HTTPS_PROXY并写入 shell 配置持久化。 - 代理规则分流不当：API 域名没走代理或走了不稳定节点。解法是给 API 域名加明确规则，并选择延迟低的节点——编码代理是长连接大流量场景，节点稳定性比网页浏览重要得多。
- TLS 中间层干扰：企业网络或安全软件做 HTTPS 解密时证书链不被 CLI 信任。症状是 curl 报证书错误。解法是把企业根证书装进信任链，不要用跳过证书验证的方式糊弄——那等于关掉 TLS。
长连接的特殊性
编码代理与普通 API 调用还有个差异：SSE 流式输出是长连接，事件边界与网络块边界并不一致，某个字节块停顿不代表模型停止生成。它对中间设备（NAT、防火墙、代理）的空闲超时敏感，症状是流式输出开始正常、输出到一半断开重连——这不是连通性问题，是长连接被中途掐了。解法是放宽对应域名的空闲超时，或在工具侧启用自动续传。
复现断线时留好证据：客户端版本、首段内容出现时间、最后的协议状态。若总在固定时长附近断开，就往客户端超时、代理空闲超时和服务端限制三个方向收。断开后先查文件 diff 或业务对象是否已产生变更，别立刻重跑带写入副作用的任务。排查这类问题的通用心法：把链路画出来（工具 → 环境变量 → 代理 → 出口 → API），每一跳单独验证，永远不要同时改两个变量。
评论0