OpenAI Codex CLI配合Clash：国内终端访问配置指南

前言：为什么 Codex CLI 需要稳定的终端代理

OpenAI Codex CLI 是面向开发者的终端工具，可以直接在项目目录中读取代码、分析文件、生成补丁、执行命令，并通过自然语言协助完成重构、测试和文档编写。与只在浏览器中打开网页不同，Codex CLI 的请求通常发生在终端进程、编辑器插件或脚本环境中，因此“浏览器能访问”并不代表命令行一定能够正常登录和调用接口。

国内用户在安装 Codex CLI、完成 OpenAI 账户认证、更新依赖或发送模型请求时，常见问题包括下载速度不稳定、登录回调失败、终端提示连接超时、TLS 握手中断，以及浏览器已经走代理但 CLI 仍然直连。根本原因通常不是 Codex CLI 本身损坏，而是终端进程没有使用系统代理、DNS 解析路径不一致，或 Clash 分流规则没有覆盖相关域名。

本文以 Windows、macOS 和 Linux 桌面环境为主，使用支持 Mihomo 内核的 Clash 客户端作为示例，介绍从客户端选择、订阅导入到终端变量、TUN 模式和分流规则的完整配置流程。配置的目标是让需要代理的认证与 API 请求稳定地经过合适节点，同时让国内代码仓库、包管理镜像和局域网资源继续保持直连。

1选择 Clash 客户端并导入订阅

Clash 只是代理内核和规则调度工具，本身不提供节点。使用前需要准备一个合法、可靠且明确支持 Clash 或 Mihomo 格式的订阅服务。不要从论坛、搜索结果或陌生脚本中复制来路不明的订阅链接，更不要把包含账户信息的链接公开发到代码仓库、Issue 或聊天群中。

不同平台的客户端建议

• Windows：可选择支持 Mihomo 内核的桌面客户端。安装后确认程序能够正常创建系统代理，并允许防火墙或网络权限请求。
• macOS：建议选择支持 Apple Silicon 和 Intel 架构的客户端。首次启用 TUN 时，系统可能要求输入管理员密码或批准网络扩展。
• Linux：可以使用带图形界面的客户端，也可以运行 Mihomo 内核并手动设置环境变量。桌面用户优先选择带 TUN 管理功能的版本，排查问题会更直观。

导入订阅的基本步骤

1. 打开 Clash 客户端的“配置”或“Profiles”页面，找到订阅管理区域。
2. 将订阅地址粘贴到 URL 输入框，填写容易识别的名称，例如 primary-2026，然后点击下载或导入。
3. 下载完成后选中该配置，确认页面能够看到代理节点、策略组和规则列表。
4. 在“代理”页面选择一个稳定节点，优先进行延迟测试，而不要只根据节点名称或瞬时测速结果判断质量。
5. 将运行模式设置为 Rule，不要一开始就使用 Global。规则模式更适合开发环境，可以避免国内 Git 镜像、公司内网和本地服务被无谓地送入代理。

2为终端配置 HTTP 和 SOCKS5 代理

这是最容易被忽略、但对 Codex CLI 最关键的一步。Clash 客户端即使已经开启了“系统代理”，也不代表所有终端程序都会自动读取该设置。许多 CLI 工具只识别 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY 等环境变量。

先在 Clash 的“设置”或“常规”页面查看本地监听端口。常见 HTTP 端口可能是 7890，SOCKS5 端口可能是 7891，但不同客户端和用户配置并不相同，必须以客户端显示的实际端口为准。假设 HTTP 端口为 7890，可以按当前终端临时设置变量。

Windows PowerShell

以上变量只对当前 PowerShell 窗口有效。确认 Codex CLI 可以正常工作后，如果希望每次打开终端都自动生效，可以通过 Windows 的系统环境变量设置界面长期保存；不建议直接把代理变量写进项目仓库的脚本文件，避免把个人网络配置带给其他协作者。

macOS 和 Linux

如果使用 Zsh，可以把变量放入 ~/.zshrc；Bash 用户可以放入 ~/.bashrc。修改后执行 source ~/.zshrc 或重新打开终端。对于公司内网、数据库、Docker 服务和本机开发服务器，应把对应域名或网段加入 NO_PROXY，例如：

先测试代理，再启动 Codex CLI

设置变量后，建议先用简单命令测试终端是否真的经过 Clash。测试域名只用于确认连通性，不要在命令中粘贴账户令牌或私密项目内容：

如果返回 HTTP 响应头，说明终端已经能够建立连接；如果出现 Could not resolve host，重点检查 DNS；如果出现 Connection refused，检查 Clash 是否启动、端口是否正确；如果长时间卡住，则应查看 Clash 的连接日志和当前节点质量。

3安装 Codex CLI 并完成认证

Codex CLI 的安装方式可能随官方发布渠道和版本变化而调整，因此应以 OpenAI 官方文档或项目发布页提供的命令为准。不要直接运行来源不明的“一键安装脚本”，也不要为了绕过错误而关闭系统安全软件。安装前可以先确认 Node.js、npm 或官方要求的运行环境版本，避免因为运行时过旧导致依赖安装失败。

安装时的代理继承关系

如果使用 npm、包管理器或安装器下载依赖，它们通常会读取当前终端的代理变量，但不同版本的行为可能不同。可以先检查变量是否存在：

如果安装器仍然无法连接，可以分别检查包管理器自己的代理设置。以 npm 为例，不建议盲目写入全局配置；临时测试可以使用当前会话变量，确认有效后再决定是否保存。若企业网络使用自签名证书，还应联系管理员获取正确的根证书，而不是使用关闭 TLS 校验的方式解决问题。

浏览器登录与终端回调

部分 CLI 认证流程会打开浏览器完成授权，再通过本机回调地址把结果交还给终端。此时需要同时满足两个条件：浏览器能够访问认证页面，终端能够访问外部服务，并且本机回调地址保持直连。建议将以下地址加入 NO_PROXY 或 Clash 的直连范围：

如果浏览器登录成功但终端没有收到回调，先不要重复点击授权。检查终端是否仍在等待、系统防火墙是否拦截了本地回调端口，以及 Clash 是否把 localhost 错误地转发到代理节点。关闭当前登录流程后重新开始，通常比同时开启多个授权窗口更容易排查。

4使用 TUN 模式和分流规则解决漏代理

当环境变量配置完成后，大多数基于 HTTP 请求的 CLI 流量都可以正常工作。但某些依赖、Git 子进程、编辑器扩展或底层网络库可能不读取代理变量。这时可以在 Clash 中开启 TUN 模式，让系统通过虚拟网卡接管更多流量。

TUN 模式的开启步骤

1. 在 Clash 客户端设置中启用 TUN，并选择自动路由或增强模式。
2. 根据系统提示授予管理员权限、网络扩展权限或安装必要组件。
3. 保持运行模式为 Rule，确认“自动设置系统代理”与 TUN 的状态没有互相冲突。
4. 重新打开终端，让新启动的进程获得最新网络状态，然后测试域名解析和 HTTPS 连接。
5. 确认本地开发服务、Docker、虚拟机和公司内网仍然可访问，再将配置长期使用。

TUN 并不是越强越好。它会改变系统层面的路由和 DNS 行为，如果规则不完整，可能导致局域网打印机、远程桌面、Git 内网仓库或本地容器网络异常。首次启用时，建议记录开启前后的网络变化，并保留一个可以快速关闭 TUN 的方案。

为 Codex 和开发工具设置分流

规则的具体域名应以官方文档、客户端日志和实际请求为准，不要把网上未经验证的域名列表全部加入配置。下面是一个思路示例，策略组名称需要与你的订阅实际提供的名称保持一致：

其中 AI-Proxy 可以绑定一个稳定的代理节点，Developer 则可根据实际网络选择代理或自动选择。不要频繁在多个国家或地区之间切换节点，认证会话和 API 请求如果在短时间内出现明显不同的出口位置，可能触发额外验证或连接中断。

5常见故障排查与稳定性优化

配置完成后，如果 Codex CLI 仍然失败，建议按照“进程—端口—DNS—节点—规则”的顺序排查，不要一次性修改大量参数。这样才能知道究竟是哪一步解决了问题。

• 终端提示找不到命令：先确认安装目录已经加入 PATH，再检查使用的终端是否与安装时相同。Windows PowerShell、CMD 和 IDE 内置终端可能使用不同的环境变量。
• 连接被拒绝：查看 Clash 是否正在运行，确认代理端口没有被其他程序占用，并检查变量中的端口号是否与客户端一致。
• 域名解析失败：检查 Clash DNS 是否启用，TUN 的 DNS 劫持是否正常。不要同时运行多个会修改 DNS 的加速器、VPN 或安全软件。
• 浏览器可以登录，CLI 无法登录：确认 CLI 进程继承了代理变量，并检查 IDE 是否在独立环境中启动。直接在同一个终端执行测试命令，可以排除 IDE 环境差异。
• 偶尔出现超时：在 Clash 连接日志中查看失败域名、命中策略组和节点延迟。更换稳定节点，减少自动切换频率，通常比不断调整超时时间更有效。
• 国内资源变慢：检查是否误用了 Global 模式，或 TUN 规则缺少国内直连规则。将公司域名、局域网网段和常用国内代码服务加入直连范围。

建议保留一套可回滚配置

每次修改配置前，先复制当前 YAML 或导出配置备份，并记录客户端版本、内核版本、代理端口和测试结果。遇到升级后异常时，可以快速判断是客户端变化、订阅变化还是本地环境变化。生产项目中还应避免让 Codex CLI 直接执行未经审查的破坏性命令，先查看变更内容，再运行测试和提交代码。

常见问题解答

只开启 Clash 的系统代理，不设置终端变量可以吗？

有时可以，但不能保证。部分终端程序会自动读取系统代理，另一些程序只读取环境变量，还有些程序支持自己的代理配置。为了减少不确定性，建议先设置 HTTP_PROXY 和 HTTPS_PROXY，再用 curl 或工具自身的诊断命令验证。

Codex CLI 应该使用 HTTP 代理还是 SOCKS5？

优先尝试 Clash 的 HTTP 代理端口，因为 Node.js 和多数开发工具对 HTTP_PROXY 的支持较成熟。如果官方文档或具体版本明确要求 SOCKS5，再使用 ALL_PROXY。端口类型必须与客户端页面显示一致。

开启 TUN 后，为什么本地服务访问异常？

通常是本地地址或局域网网段没有直连，或者 DNS 请求被错误转发。把 localhost、127.0.0.1、::1 以及实际局域网网段加入直连范围，并在 Clash 日志中确认这些请求没有进入 AI 代理策略组。

可以把 API Key 写进项目的环境文件吗？

可以使用本机私有的环境文件，但必须将其加入 .gitignore，并避免在终端日志、CI 输出和公开仓库中显示。更稳妥的方式是使用系统密钥链、CI Secret 或官方推荐的安全凭据管理方案；一旦怀疑泄露，应立即撤销并重新生成。