Codex认证机制：ChatGPT账户与API密钥的集成

认证体系概述

Codex作为聊天驱动开发工具，提供两种核心认证方式：ChatGPT账户登录和OpenAI API密钥认证。前者适合已订阅ChatGPT Plus/Teams计划的用户，后者适用于需要按使用量计费的场景。认证配置存储于~/.codex/auth.json，支持跨设备迁移与远程服务器部署。

API密钥认证流程

基础配置方法

通过API密钥认证需执行以下命令：

codex login --api-key "your-api-key-here"

该密钥需至少拥有Responses API的写入权限。密钥验证逻辑在codex-rs/login/src/lib.rs中实现，核心函数login_with_api_key负责权限校验与凭证存储。

密钥权限要求

API密钥必须包含以下权限集（定义于codex-rs/core/src/auth.rs）：

• responses:write - 写入交互响应数据
• models:read - 获取模型元信息
• codex:execute - 执行代码操作

ChatGPT账户登录实现

设备码认证流程

无浏览器环境下采用设备码认证（Device Code Flow），实现位于codex-rs/login/src/device_code_auth.rs：

1. 客户端请求设备码：POST https://auth.openai.com/device/code
2. 用户在浏览器中输入验证码
3. 客户端轮询令牌端点获取访问凭证

本地服务器辅助登录

带图形界面环境使用本地服务器模式（codex-rs/login/src/server.rs）：

• 启动临时服务器监听localhost:1455
• 自动打开浏览器完成OAuth授权
• 接收重定向回调并存储令牌

认证凭证管理

文件存储结构

认证信息以JSON格式存储于~/.codex/auth.json，结构定义见codex-rs/core/src/auth.rs的AuthDotJson结构体：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": 1719267834,
  "refresh_token": "def50200c6a8e..."
}

跨设备迁移方法

通过SCP传输认证文件至远程服务器：

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

Docker环境迁移命令：

CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker cp auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

远程服务器认证方案

SSH端口转发

通过端口转发实现远程登录：

# 本地终端执行
ssh -L 1455:localhost:1455 user@remote-host
# 远程终端执行
codex login

无头环境凭证迁移

1. 在本地完成登录：codex login
2. 传输凭证至无头环境：

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

认证机制切换指南

API密钥迁移至ChatGPT账户

1. 更新CLI至0.20.0+版本：codex self-update
2. 删除旧凭证：rm ~/.codex/auth.json
3. 重新登录：codex login

多账户切换

通过配置文件切换不同认证上下文：

# 创建工作账户配置文件
codex config set auth.path ~/.codex/work_auth.json
# 切换至个人账户
codex config set auth.path ~/.codex/personal_auth.json

常见问题排查

令牌过期处理

当遇到401 Unauthorized错误时，执行：

codex login --refresh

系统会自动使用codex-rs/login/src/pkce.rs中的PKCE流程刷新令牌。

权限不足解决

API密钥权限不足时，检查：

1. 密钥是否包含responses:write权限
2. 访问OpenAI权限控制台调整权限集
3. 重新执行codex login --api-key

安全最佳实践

凭证保护措施

• 使用环境变量注入密钥：export OPENAI_API_KEY=sk-xxx
• 启用文件系统权限控制：chmod 600 ~/.codex/auth.json
• 使用密钥环集成（codex-rs/core/src/auth.rs的KeyringStorage）

审计日志

认证事件日志位于~/.codex/logs/auth.log，包含：

• 登录时间戳
• 认证方式（API_KEY/ChatGPT）
• IP地址与设备信息

官方认证文档：docs/authentication.md
核心认证模块：codex-rs/login/src/lib.rs
配置指南：docs/config.md