官方原文索引： Codex CLI Sign-in / Authentication / Login Methods
1. 核心架构与原理解析
Codex CLI 支持两种认证方式，其安全模型和适用场景截然不同：
| 认证方式 | 凭证存储位置 | 适用场景 | 成本模式 |
|---|---|---|---|
| ChatGPT 账号 | ~/.codex/token（OAuth Token） | 日常开发 | 包含在订阅中 |
| API Key | ~/.codex/auth.json 或环境变量 | CI/CD、自动化 | 按 Token 计费 |
认证流程拓扑：
🛠️ 专家视角 / 架构思考： ChatGPT 认证使用 OAuth 2.0 设备码流程，Token 有效期有限且支持刷新。企业环境中建议强制
forced_login_method = "chatgpt"并绑定特定工作空间（forced_chatgpt_workspace_id），这样：
- 离职员工自动失去访问（通过 Workspace 成员管理）
- 所有操作记录进入企业合规日志平台
- API Key 泄露风险被 OAuth 机制替代
2. 工程落地与代码示例
交互式首次登录
# 启动 Codex
codex
# 终端显示登录选项：
# 1. Sign in with ChatGPT（推荐）
# 2. Enter API Key手动触发登录/登出
# 重新登录（切换账号或 Token 过期时）
codex login
# 设备码登录（SSH 远程无浏览器环境）
codex login --device-code
# API Key 管道登录
printenv OPENAI_API_KEY | codex login --with-api-key
# 清除本地凭证
codex logout自动认证配置（CI/CD）
# 方式 1：环境变量（推荐）
export OPENAI_API_KEY="***"
codex exec "run tests"
# 方式 2：配置文件（~/.codex/config.toml）
preferred_auth_method = "apikey"
# 方式 3：GitHub Actions Secret
# 在 CI 中设置 SECRET: ***
# 工作流中引用：${{ secrets.OPENAI_API_KEY }}GitHub Actions 完整示例：
# .github/workflows/codex-ci.yml
name: Codex CI Integration
on: [push, pull_request]
jobs:
codex-task:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Codex
run: npm install -g @openai/codex
- name: Run Codex Task
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex exec --approval-mode never \
--sandbox workspace-write \
"分析当前代码变更并运行相关测试"修复常见登录错误
# 错误：Error: account/read failed during TUI bootstrap
# 解决：重新登录
codex logout && codex login
# 错误：Token 过期导致 401
# 解决：刷新登录状态
codex login
# 错误：API Key 无 Codex 权限
# 解决：确认 Key 所属账号有 Plus/Pro 订阅，或 Enterprise 计划已开通 Codex凭证安全存储配置
# ~/.codex/config.toml
# 使用操作系统密钥环存储凭证（最安全）
cli_auth_credentials_store = "keyring"
# 备选：明文文件（仅开发环境）
# cli_auth_credentials_store = "file"3. 场景深入：不同环境下的认证实践
场景：SSH 远程服务器无浏览器
# 远程服务器
$ codex login --device-code
Please visit https://github.com/login/device and enter code: ABCD-1234
# 本地浏览器打开上述链接，输入 ABCD-1234
# 授权完成后远程自动继续场景：多账号切换（个人 + 公司）
# 使用环境变量隔离不同账号
# 个人项目
export OPENAI_API_KEY="sk-personal-xxx"
codex
# 公司项目
export OPENAI_API_KEY="sk-company-xxx"
export OPENAI_BASE_URL="https://api.company.com/v1"
codex
# 或者使用 config.toml 的 profile 功能
# ~/.codex/config.toml
[profile.personal]
model = "gpt-5.3-codex"
[profile.company]
model = "gpt-5-codex"
base_url = "https://api.company.com/v1"4. 💡 核心避坑与最佳实践 (Takeaways)
- SSH 远程登录用
--device-code：无图形界面时，设备码登录是唯一可靠方式 - API Key 不要写入代码仓库：使用环境变量或密钥管理系统（Vault、AWS Secrets Manager、GitHub Secrets）
- 企业强制 Workspace 绑定：通过
forced_chatgpt_workspace_id防止个人账号混用，离职即失效 - Token 存储在 OS Keyring 更安全：配置
cli_auth_credentials_store = "keyring"防止明文落盘 - 定期轮换 API Key：企业环境建议每月轮换，配合审计日志追踪使用情况