String AI
语言
登录 立即开始
博客

企业网络中的 Codex CLI：CA 证书包、凭据存储与登录

在受管网络上，Codex CLI 登录失败通常与密钥无关。要检查的顺序是：先信任，再凭据存储，最后登录路径。

String AI Editorial Team
企业网络中的 Codex CLI：CA 证书包、凭据存储与登录

在企业代理之后或处于流量检查网络之中的 Codex CLI，是一类独立的配置问题。登录失败时，本能反应是怀疑密钥或账户，但在受管网络上，最常见的三个原因并非如此：由于企业 TLS 代理或私有根证书挡在链路中，证书链不被信任；CLI 依赖的凭据存储被管理员锁定或强制规定；或者登录路径本身被阻断，因为浏览器回调无法回到这台机器。每个问题有不同的修法，而且有一套可用的检查顺序：先信任，再存储，最后登录路径。个人机器上的对应内容涵盖登录模式和本地凭据存储；本文讲的是企业环境。

codex cli login 证书错误：为什么信任问题会穿上登录的外衣

团队上报的症状通常是“登录坏了”：CLI 卡在认证环节、握手失败，或者昨天还能通的请求今天不再完成。证书链问题往往就是这样表现的，而打印出的错误并不总把信任库点名为根因。这就是为什么在受管网络上第一步不是检查密钥，而是先问：在组织的拦截设置下，这台机器究竟能否与端点完成 TLS。TLS 代理会用组织自己的根证书重新签名流量；自带 CA 信任配置的工具需要把这个根证书显式提供给它。Codex CLI 正是支持这一点，使你可以在花时间折腾凭据之前，低成本地排除或确认证书问题。

可信 CA 证书包：登录前设置 CODEX_CA_CERTIFICATE

官方认证文档把这一设置讲得很直白。如果你的网络使用企业 TLS 代理或私有根 CA，请在登录前将 CODEX_CA_CERTIFICATE 设置为 PEM 证书包，然后再登录：

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

文档中有三个细节在运维上很重要：

  1. 优先级。 CODEX_CA_CERTIFICATE 的优先级高于 SSL_CERT_FILE。未设置时，Codex 会回退到 SSL_CERT_FILE，因此已经统一使用该变量的环境仍可正常工作，但两者同时存在时，Codex 专用变量优先。
  2. 作用范围。同一套自定义 CA 设置适用于登录、普通 HTTPS 请求和安全 WebSocket 连接。这一点很重要，因为只为登录设置的证书包，会让后续的工作会话同样暴露在这些故障之下。
  3. 顺序。在登录前设置。证书包必须位于登录进程自身的环境中，而这正是那些把它配在 shell profile 里的团队容易栽跟头的地方——交互式登录和服务进程并不都会继承它。

关于完整的环境变量行为，参见认证文档。

凭据存储：cli_auth_credentials_store 的四种模式

CLI 把缓存的凭据存在哪里是一个配置决策，而在受管机器上，它与企业策略存在重叠。cli_auth_credentials_store 设置接受四个值：

  • file 将凭据存储在 auth.json 中，位于 CODEX_HOME 之下，后者默认为 ~/.codex。
  • keyring 将凭据存储在操作系统凭据存储中，若该存储不可用则失败。这是受管机群倾向选择的模式，但在强制推行之前，请先确认你的环境中确实存在该存储。
  • auto 在可用时使用操作系统凭据存储，否则回退到 auth.json，这使它成为混合环境中最宽容的选择。
  • ephemeral 只在当前进程的内存中保存凭据，适合容器和一次性任务——这些场景不应有任何内容持久化到磁盘。

由此产生两个后果。第一，如果把存储设为 file，就要把 ~/.codex/auth.json 当作密码对待：它包含 access token，因此不得提交到代码库、粘贴进工单或在聊天中分享。第二，这个选择并不总是由你来做：管理员可以通过本地认证要求强制规定凭据存储和 ChatGPT base URL，而用户无法通过 config.toml 或 CLI 覆盖项来推翻这些要求。

无论选择哪种模式，凭据本身仍然遵循密钥生命周期规则：到期日期、轮换路径和吊销路径，正如密钥卫生指南所阐述的那样。

当管理员强制规定这些设置时

当遇到“我改了，却什么都没发生”时，这一节就是你要读的。受管配置文档说明管理员会设置 cli_auth_credentials_store 和 chatgpt_base_url（以及登录方式和工作区限制），位置在本地系统要求文件中，或通过 macOS MDM 要求。这些本地要求有两个特性，解释了大部分困惑：

  • 它们在凭据加载之前、在 Codex 获取云策略之前就生效，因此当其他任何环节读取配置时，被强制的值已经生效。
  • 云端管理侧会忽略这几个特定字段；本地强制才是生效机制。

如果一台 worker 机器拒绝了在同事笔记本上可用的凭据存储模式，答案通常根本不在 config.toml 里。它在管理员掌控的要求文件中，解决办法是去和那位管理员沟通，而不是改配置。

共享缓存，共享意外

Codex 会缓存登录信息并在各个界面间复用：ChatGPT 桌面应用、CLI 和 IDE 扩展都参与同一套缓存机制，而 CLI 与扩展更是共享同一份缓存的登录信息。如果有人在其中任一处退出登录，CLI 或扩展下次启动时就需要重新登录。这些信息以明文文件形式保存在本地 ~/.codex/auth.json，或保存在操作系统专属的凭据存储中，具体取决于模式；对于 ChatGPT 登录会话，Codex 会在 token 到期前于使用过程中自动刷新，因此活跃会话通常无需再走一趟浏览器。

工程上的结论：“我这儿能用，他那儿不行”在机群中是预期会出现的一类问题，要比对的变量很具体：那台机器上有哪个凭据存储可用、那里强制的是哪种模式、单用户缓存处于什么状态。这种比对比任何重装都快。

在受限网络中如何选择登录路径

基于浏览器的登录流程有两种文档记载的失败情形，企业在其中屡屡受挫：在远程或无头环境中运行 CLI，以及本地网络阻断了 Codex 在登录后回传 OAuth token 所用的 localhost 回调。在这些情况下，文档建议优先使用设备代码认证（beta）：在交互式登录界面中选择 Sign in with Device Code，或直接运行 codex login --device-auth。

有一个前提很重要，而且是组织层面的，不是技术层面的：设备代码登录必须先被启用，个人账户在 ChatGPT 安全设置中启用，或由管理员在工作区权限中启用。这个启用点与早前凭据指南中描述的是同一处，在受管网络上，它往往决定了是五分钟搞定还是开一张支持工单。如果你的环境中没有设备代码认证，官方文档描述了把登录带到机器上的兜底方法，而直接运行 codex login 会写入一个专用的 codex-login.log 到已配置的日志目录下，那正是拿去沟通时该带的产物，尤其是浏览器登录和设备代码失败的情况。

面向自动化的非交互式凭据

自动化使用的凭据与交互式登录不同，这条界线值得划清：

  • CODEX_API_KEY 为非交互式的 Codex 进程提供 API key。文档给出的部署建议：在运行受仓库控制的代码时，以内联方式设置，而不是设为整个作业级别的环境变量，这样作业中执行的代码就无法从环境中读出该凭据。
  • CODEX_ACCESS_TOKEN 为可信自动化提供 ChatGPT 或 Codex access token；若要持久化登录，请把它通过管道传给 codex login --with-access-token。access token 文档涵盖了签发配置。
  • 工作负载身份 覆盖第三种模式，即由进程环境提供身份：OPENAI_FEDERATION_RULE_ID 选择为该工作负载配置的联邦规则，OPENAI_IDENTITY_TOKEN_FILE 指向包含当前 OIDC token 或 SPIFFE JWT-SVID 的文件的绝对路径，OPENAI_WORKLOAD_IDENTITY_CONTEXT 可选地提供有界的 JSON 标识符，用于客户端上报的审计归因，且不影响认证或授权。当选择工作负载身份时，codex login 和 codex logout 会被拒绝，因为认证由进程环境控制。

有一个界限需要记住：模型供应商的 API key 不是 CLI 凭据。对于供应商密钥，Codex 会读取由 env_key 在模型供应商配置中指名的变量，所以变量名本身并不固定。这些凭据在 CI 中的专用模式见CI 中的编码 agent 指南。

排查顺序

在受管网络上，按这个顺序逐层排查：

  1. 信任层。 是否在运行登录进程的那个环境中，把 CODEX_CA_CERTIFICATE 设为企业的 PEM 证书包，并以 SSL_CERT_FILE 作为文档给出的回退选项？这一项放在最前，因为它的症状会伪装成其他所有问题。
  2. 存储层。 生效的是哪一种 cli_auth_credentials_store 模式，底层存储在这台机器上是否真的可用，以及该模式是否由你无法推翻的本地要求强制？
  3. 登录路径。 浏览器流程能否完成（回调是否可达），还是设备代码才是正确路线？失败时保留 codex-login.log 作为证据。
  4. 应用层。 如果认证成功而请求仍然失败，问题已经转移了：区域和权限拒绝在 403 指南 中有各自的分类，而通用的状态码分诊见错误码指南。

还有一种失败会伪装成配置问题：被固定的模型已经退役，所以请拿你的模型 ID 对照2026 年 10 月关闭汇总 核查。

清单

  1. 在存在 TLS 拦截时，登录前把 CODEX_CA_CERTIFICATE 设为 PEM 证书包；记住 SSL_CERT_FILE 这个回退选项，以及登录、HTTPS 和 WebSocket 的作用范围。
  2. 确认该变量能到达真正的登录进程，而不只是交互式 shell。
  3. 有意识地选择凭据存储：有可用凭据存储的受管机器用 keyring，容器用 ephemeral，混合环境用 auto。
  4. 把 auth.json 当作密码对待，只要涉及 file 存储。
  5. 当某项设置不生效时，先怀疑本地要求文件，再怀疑 CLI。
  6. 对于无头主机或回调被阻断的主机，启用并使用设备代码认证；保留失败时的 codex-login.log。
  7. 对于自动化，选对凭据类别：受仓库控制的代码用内联的 CODEX_API_KEY，可信流水线用 CODEX_ACCESS_TOKEN，平台签发身份的场景用工作负载身份。
  8. 遇到“我这儿行、他那儿不行”，就在两边机器上比对证书包、凭据存储可用性、强制配置和回调可达性。

企业环境只奖励一种习惯：先查信任再查凭据，先查凭据再查代码。你们团队所调用的那个端点的端点级事实，就在平台自己的文档。