Codex CLI 在国内装不上、跑不起来的排查
在国内装 OpenAI 的 Codex CLI，失败的方式其实只有三种，而它们的报错长得很像——都是一堆超时和连接重置。把它们分开看，排查会快得多。
三个阶段分别是：装（npm 拉包）、登（浏览器授权回调）、跑（运行时的 API 请求）。任何一个阶段卡住，终端里看到的都是「连不上」，但要动的地方完全不同。
先判断卡在哪个阶段
在动任何设置之前，先确定故障发生的位置。这一步能省掉大部分无效尝试：
| 现象 | 卡在哪一步 |
|---|---|
npm install 长时间不动，最后 ETIMEDOUT / ECONNRESET | 装：包没拉下来 |
装完了，codex 命令能执行，但登录时浏览器一直转 | 登：授权回调 |
| 登录成功了，一提问就超时或中途断开 | 跑：运行时请求 |
| 前面都正常，只是输出到一半突然中断 | 跑：长连接不稳 |
对照完再往下看对应的小节，不要一上来就把三件事一起改。
第一类：npm 阶段就失败
这一阶段拉的是 npm 仓库里的包，和 OpenAI 的服务没有关系。所以它是唯一一个可以完全靠国内镜像解决的阶段。
如果只是这一步慢或失败，先把 npm 源换成国内镜像再装，通常就够了。装完之后记得把源换回来，否则以后拉别的包会出现版本滞后。
这里有个常见的误判：很多人看到 npm install 失败，就认定「网络整体不通」，于是去折腾线路。实际上包仓库和 API 服务是两套完全独立的基础设施，一个通、另一个不通是很正常的情况。先分清楚，再决定要不要动线路。
另一种情况是 Node 版本不满足要求。Codex CLI 对 Node 有最低版本要求，版本太老时报错会指向依赖解析，看起来也像网络问题。装之前先确认 Node 版本，这一分钟能省下一小时。
第二类：登录授权卡在回调
据 OpenAI 官方 Codex 仓库的说明文档，推荐的登录方式是运行 codex 后选择 Sign in with ChatGPT，用已有的 ChatGPT 账号授权；文档同时写明也可以改用 API key，但「需要额外的配置」。这解释了为什么这一阶段的故障和前后两类都不一样——默认路径要经过浏览器，而浏览器和终端并不总在同一台机器上。
Codex CLI 的登录会打开浏览器完成授权，再把结果回调给本机的一个临时端口。这一步有两个独立的失败点，很容易混淆：
一是浏览器那一端打不开授权页面。 这是访问层面的问题，和终端无关——如果浏览器本身访问不了 OpenAI 的域名，授权页自然出不来。
二是授权页明明完成了，终端却一直等在那里。 这通常不是线路问题，而是回调没有回到本机：某些安全软件会拦截本地端口监听，远程开发（SSH 到服务器、容器内运行）时浏览器和 CLI 根本不在同一台机器上，回调地址指向的也就不是同一个 localhost。
远程环境下的正确做法是按官方文档走无浏览器的授权方式，而不是反复重试。反复重试解决不了拓扑问题。
还有一个容易忽略的点：登录地区尽量保持稳定。 今天从一个区域登录、明天换另一个，账号侧更容易触发额外验证。这一条和线路快慢无关，是账号安全策略。
第三类：装好了，但一跑就超时
这是最常见、也最容易被误诊的一类。特征很清楚：登录是成功的，简单命令也能执行，但一旦真正发起请求就超时，或者输出到一半突然断掉。
原因在于 Codex 这类工具的请求形态和浏览网页很不一样：
- 它是流式输出，一次请求的连接会持续几十秒甚至更久。
- 编码任务的上下文很大，上行数据量远高于普通浏览。
- 一次任务里往往有多轮连续请求，中间任何一次断开都会让整个任务失败。
所以对这类工具来说，线路的稳定性和持续性比峰值速度重要得多。一条测速数字很漂亮但抖动大的线路，浏览网页毫无问题，跑 Codex 却会不断中断。这也是为什么「我网页都能打开，为什么 Codex 不行」这个问题的答案，往往不是「线路不通」，而是「线路不够稳」。
判断方法也很直接：如果失败总是发生在输出进行到一半，而不是一开始就连不上，那基本可以排除「完全不通」，问题在稳定性。
为什么浏览器能打开，终端却不行
这是本文最值得单独拿出来说的一点。
浏览器和终端不共享网络设置。很多代理工具只接管浏览器流量，终端里的 node、npm、curl 走的是另一条路径——它们读的是环境变量或系统设置，而不是浏览器的配置。所以「浏览器能打开 OpenAI 的网站」完全不能推出「Codex 能跑通」。
这就是全局模式在这个场景里更省事的原因：它在系统层面接管流量，终端进程和浏览器走同一条路径，不需要为每个命令行工具单独配置。远航跨境 的客户端可以在全局与智能模式之间切换，跑开发工具时建议用全局，避免出现「浏览器正常、终端不通」这种自相矛盾的状态。
Windows 上还有一个额外的坑：WSL2。 WSL2 有自己的虚拟网络，它的流量不一定会跟随宿主机的默认路由。也就是说，你在 Windows 上看着一切正常，WSL2 里的 npm 和 codex 仍然可能走原来的路。如果你的开发环境在 WSL2 里，需要单独确认它的出口，而不是默认它跟着宿主机走。
顺带说明一下适用范围：远航跨境 目前提供 Windows 与安卓客户端。如果你的开发环境在 macOS 或 Linux 上，这篇里关于线路选择的判断依然成立，但客户端本身用不上。
具体怎么配
按上面的分类，动作其实很少：
- 确认阶段。 用上面的对照表定位，不要三件事一起改。
- npm 阶段用国内镜像，装完换回官方源。
- 登录阶段先确认浏览器能打开授权页；远程环境改用无浏览器授权方式。
- 运行阶段换成全局模式，让终端和浏览器走同一条路径。
- 线路优先选稳定的，不是测速最快的。失败发生在中途就说明是稳定性问题。
- WSL2 单独验证，别默认它跟宿主机一致。
时段也是一个真实变量。晚高峰同一条线路的抖动会明显变大，对长连接的影响比对网页浏览大得多。跑长任务前先看时间，比反复换线更有效。
如果你同时也在用 Claude Code，排查思路是完全一样的，可以对照 Claude Code 在国内的连接问题 一篇；移动网络下的额外变量在 移动网络下的连接问题 里讲得更细。
常见问题
为什么 npm 装不上，但网页能打开？ 包仓库和 API 是两套独立的基础设施。npm 阶段失败先换国内镜像，不要急着动线路。
登录时浏览器一直转怎么办？ 先确认浏览器本身能打开授权页。如果授权页完成了终端还在等，问题多半出在回调端口，远程或容器环境要改用无浏览器的授权方式。
跑到一半断开是线路太慢吗？ 更可能是抖动而不是带宽。这类工具是流式长连接，一次中断整个任务就失败，稳定性比峰值速度重要。
为什么浏览器正常，终端里就是不通？ 两者不共享网络设置。只接管浏览器的方案覆盖不到终端进程，用全局模式让两者走同一条路径。
WSL2 里需要单独设置吗？ 需要单独确认。WSL2 有自己的虚拟网络，流量不一定跟随宿主机的默认路由，Windows 侧正常不代表 WSL2 侧正常。
上下文很大会影响成功率吗？ 会。编码任务的上行数据量比普通浏览高很多，上行不稳时表现就是请求发不出去或中途失败，选线路时不要只看下行。
免费套餐能跑吗？ 可以先用来验证路径是否通、是否稳定。长时间的编码任务对线路稳定性要求更高，判断依据是失败是否总发生在中途。