Codex CLI 的凭证问题，归根结底都是三个问题：你用的是哪种登录方式？这份凭证存放在哪里？此刻真正生效的又是哪一种？答案决定了用量如何计费、你的安全评审该是什么样，以及该走哪条排查路径。官方认证文档列出了全部三条路径及其存储行为，本文把它们整理成一幅可直接上手的图景。本文是对我们此前介绍的Claude Code 凭证优先级一文的有意呼应；两篇合起来，构成双 agent 工具链的凭证参考，且彼此不重复对方的机制。如果你是全新搭建而不是审查一台现成的机器，那么工具配置指南是更好的起点。
三条登录路径
使用 OpenAI 模型时，Codex 支持两种人工登录方式：使用 ChatGPT 登录，用于订阅访问；以及使用 API key 登录，用于按用量访问。两者在桌面应用、CLI 和 IDE 扩展中都可用；Codex cloud 则要求使用 ChatGPT 登录。企业自动化还有第三条路径：Codex 访问令牌，详见下文。
这个选择并非无关紧要。根据官方认证文档，登录方式决定了适用哪些管理控制与数据处理策略：ChatGPT 登录遵循你的 ChatGPT 工作区权限、基于角色的访问控制，以及 Enterprise 的保留与驻留设置；而 API key 用量则改为遵循你的 API 组织的保留与数据共享设置。如果你的组织要审计数据流，这一句话就决定了你该和合规团队开哪一场会。
CLI 的默认方式是浏览器流程：运行codex login并完成浏览器中的步骤。当没有可用的有效会话时，这就是 Codex 首先提供的路径。
Codex CLI 的 API key 登录，以及它如何计费
API key 这条路径更多是为机器和流水线设计的，而不是为人工操作设计的。Codex 不把 key 作为命令行参数接收（那样它会落进 shell 历史和进程列表），而是从标准输入读取：
printenv OPENAI_API_KEY | codex login --with-api-key这一条命令就是 codex login 的 API key 流程，而它的计费含义值得读两遍。OpenAI 通过你的 OpenAI Platform 账户按标准 API 价格对 API key 用量计费，Codex 使用标准 API 定价，而不是 ChatGPT 套餐内含的额度。换句话说，这样登录会把你从订阅世界带进按量计费世界，具体价格见官方定价页，本文不展开。功能覆盖也会变化：文档指出，部分依赖 ChatGPT 工作区访问或云服务的功能在 API key 认证下会受限或不可用，某些插件也不可用，因为它们的连接流程需要 OAuth 能力，而这一模式不提供。
这一模式的优势在自动化。文档说得很直接：程序化的 Codex CLI 工作流（例如 CI/CD 任务）请使用 API key 认证，并且不要在不可信或公开环境中暴露 Codex 执行。
Codex CLI 凭证在磁盘上：四种存储模式
登录之后，凭证会被缓存。文档明确说明，Codex 会把登录信息缓存在本地的明文文件里，~/.codex/auth.json或者放在操作系统的凭证存储中；同时 CLI 与 IDE 扩展共享同一份缓存的登录信息。如果这篇文章你只记一句话，就记文档自己的那句：如果你使用基于文件的存储，请把~/.codex/auth.json它当作密码对待，因为它包含访问令牌。不要提交到仓库，不要粘进工单，也不要在聊天中分享。
缓存落在哪里，可以通过配置里的cli_auth_credentials_store来设置。文档给出四种模式：
file把凭证存进auth.json目录下，CODEX_HOME该路径默认为~/.codex。keyring把凭证存进操作系统的凭证存储，如果该存储不可用就直接失败，而不是静默回退。auto在有可用的操作系统凭证存储时使用它，否则回退到auth.json。ephemeral只在当前进程的内存中保留凭证，适合不应向磁盘持久化任何内容的一次性环境。
完整的 schema 见配置参考。对受管机群来说，有一个治理细节很重要：管理员可以通过本地认证要求强制cli_auth_credentials_store，而用户无法通过config.toml或 CLI 参数覆盖被强制的值。如果你的平台团队希望操作系统凭证存储成为 Codex auth.json 这类密钥唯一可接受的位置，那么这个开关是存在的，而且它不是建议性的。
检查当前生效的是哪种登录
两条命令就能回答状态问题：codex login status会报告当前生效的认证方式，而codex logout会清除已存储的凭证。在桌面应用和 IDE 扩展中，个人资料菜单会显示当前账号或 API key 状态。
共享缓存这一行为，解释了一整类团队困惑。由于 CLI 与扩展共享缓存的登录，其中任意一方登出，就意味着另一方下次启动需要重新登录。当同事说“我这儿能跑，他那儿不行”时，某个界面最近发生过登出，属于头号嫌疑，而不是边缘情况。
文档里有一条企业边界值得单独说明：当进程环境选择了 workload identity 时，Codex 会同时拒绝codex login和codex logout，因为认证由外围环境控制。在这种配置下，登录命令并不是你要找的接口，这是有意为之。
Codex 无头登录：设备码与备选方案
基于浏览器的登录，前提是有浏览器且本地回调可用。在远程或无头机器上，或者当本地网络阻断把 OAuth 令牌返回给 CLI 的 localhost 回调时，这个前提就不成立了。文档首选的答案是设备码认证，目前标记为 beta：
- 个人账号请在 ChatGPT 安全设置中启用设备码登录；如果工作区由管理员管理，则在工作区权限中启用。
- 在运行 Codex 的终端里，在交互式登录界面中选择使用设备码登录，或者直接运行专用命令：
codex login --device-auth。 - 在浏览器中打开打印出的链接，登录，然后输入一次性代码。
如果你的环境中没有设备码登录，文档给出了两种备选方案。第一种是在有浏览器的机器上完成认证，再把缓存的凭证复制到无头主机，可以借助scp，或直接复制进容器；文档再次强调了复制文件的密码级警告，并指出当你的操作系统把凭证存进凭证存储而不是文件时，这个方法可能不适用。第二种是通过 SSH 转发 CLI 的本地回调端口，让标准浏览器流程走隧道。两个流程都有精确步骤的文档，在把它们接进自动化配置之前，都值得在当前页面重读一遍，因为 beta 状态和界面措辞都可能变化。
CI/CD 与自动化
对流水线来说，文档给出的默认做法是 API key 认证，并附带警告：不要在不可信或公开环境中暴露 Codex 执行。这正好对应CI 指南里的护栏习惯：通过密钥存储注入凭证，只暴露给需要它的那一步，并让它们远离日志和构建产物。
对于需要在自动化中使用 ChatGPT 侧会话的团队，有一种进阶模式：一份专门指南介绍了如何在可信的 CI/CD runner 上维护账号认证，包括让 Codex 在正常运行中刷新 auth 缓存，并为下一个任务保留更新后的文件。文档也很坦率：API key 仍然是自动化场景推荐的默认选择；进阶路线是为更窄的场景存在的，不是省事的路径。如果你们组织的凭证按计划轮换，关于如何在不中断服务的情况下更换的机械式清单，在提供商切换指南中。
前面提到的 Codex 访问令牌是第三条路径：在 ChatGPT Enterprise 工作区中，管理员可以授予访问令牌权限，让成员为可信的非交互式工作流创建令牌。令牌面向可信脚本、调度器和私有 CI runner，文档的边界很清楚：一般的 OpenAI API 调用，继续使用 Platform API key。
团队级管理的限制
受管环境可以在配置层约束认证。文档中两个设置承担了主要工作：forced_login_method接受一个只允许 ChatGPT 登录或只允许 API key 登录的取值，而forced_chatgpt_workspace_id把 ChatGPT 登录固定到特定工作区。执行模型很严格：如果当前生效的凭证与配置的限制不匹配，Codex 会让用户登出并退出。这些也可以通过旧版受管配置提供，所以在管理良好的机群上，“为什么 CLI 启动时把我登出了”这个问题，答案可能是策略，而不是 bug。
还有一条来自 Work Cloud 一侧的边界：API key 和 Codex 访问令牌都无法启用 Work Cloud 的本地计算机访问。该能力依赖以 ChatGPT 登录到符合条件的工作区，再多令牌配置也替代不了。
登录诊断
当浏览器登录或设备码认证失败时，Codex 会在配置的日志目录下写一个专门的codex-login.log文件，这个文件正是文档为登录相关调试推荐的，也包括提交支持请求时的使用。升级之前先把它收集齐；这决定了你得到的是“登录不工作”，还是一份别人能据此行动的报告。
还有两个相邻的细节能省时间。第一，在带 TLS 代理或私有根 CA 的企业网络中，登录前先把CODEX_CA_CERTIFICATE设置为一个 PEM 包；当它未设置时，Codex 会回退到SSL_CERT_FILE。同一套自定义 CA 设置适用于登录、普通请求和安全 WebSocket 连接，所以这类网络上的登录失败，往往与后续的请求失败是同一个根因。第二，对于认证问题里的错误码层面，通用的错误码指南覆盖了 401 系列，以及什么时候不该重试。
如果用的是非默认提供商，先把提供商配置确认清楚，再归咎于认证；自定义提供商指南把配置失败与登录失败区分开来。
速查表与安全清单
| 场景 | 建议路径 | 凭证所在位置 |
| :- | :- | :- |
| 本地单机 | ChatGPT 登录（默认） | 操作系统凭证存储或~/.codex/auth.json |
| 本地 + API 计费 | 通过 stdin 的 API key 登录 | 同一存储，API key 凭证 |
| 共享多用户机器 | API key，配合每用户CODEX_HOME，或 keyring 模式 | 仅用户级存储 |
| 无头服务器 | 设备码登录（beta）或文档中的备选方案 | 文件缓存，密码级 |
| CI/CD | API key 认证 | CI 密钥存储，按步骤注入 |
| 受管团队 | 以forced_login_method允许的为准 | 由受管配置强制执行 |
五个值得刻在心里的安全动作：把~/.codex/auth.json无论它出现在哪里都当作密码对待；永不提交、永不粘进工单、永不在聊天中分享；在策略允许时优先使用操作系统凭证存储；把 CI 密钥限定到需要它的那一步，并彻底避免不可信环境；还要记住，CLI 或扩展任一方登出都会波及另一方。最后，由于界面措辞和设备码上的 beta 标记都可能变化，在把它们写进 runbook 之前，请对照官方认证页和平台自己的文档确认细节。
存储只是这个问题的一个面；泄漏面、过期、轮换以及“先吊销”的处理，都汇总在密钥卫生指南里。