【Bug已解决】codex: 会话过期 — CodeX CLI 认证令牌失效解决方案

【Bug已解决】codex: "session expired" / Authentication token invalid — CodeX 会话过期解决方案

1. 问题描述

CodeX CLI 的会话过期或认证令牌失效，无法继续使用：

# 会话过期 $ codex "分析代码" Error: Session expired Your session has expired. Please log in again. # 或令牌无效 $ codex --print "task" --max-turns 5 Error: 401 Unauthorized Invalid authentication token. # 或令牌过期 $ codex "task" Error: token_expired Your API token has expired. Please refresh. # 或 OAuth 令牌失效 $ codex Error: OAuth token invalid Please re-authenticate with /login.

这个问题在以下场景中特别常见：

• OAuth 令牌过期
• API Key 失效或被撤销
• 长时间未使用后令牌过期
• 账户密码更改
• 令牌刷新失败
• 多设备登录冲突

2. 原因分析

原因分类表

3. 解决方案

方案一：重新登录（最推荐）

# 步骤 1：重新登录 codex /login # 步骤 2：或使用命令行 codex login # 步骤 3：按提示完成 OAuth 认证 # 浏览器会打开 OpenAI 登录页面 # 步骤 4：验证 codex --print "hello" --max-turns 1

方案二：使用 API Key

# 步骤 1：获取 API Key # 登录 https://platform.openai.com/ # API Keys → Create new secret key # 步骤 2：设置环境变量 export OPENAI_API_KEY=sk-xxxxx # 步骤 3：永久设置 echo 'export OPENAI_API_KEY=sk-xxxxx' >> ~/.bashrc source ~/.bashrc # 步骤 4：验证 codex --print "hello" --max-turns 1

方案三：刷新令牌

# 步骤 1：尝试刷新 codex /refresh # 步骤 2：如果刷新失败，重新登录 codex /login # 步骤 3：清除旧凭证 rm -rf ~/.codex/credentials.json codex /login # 步骤 4：验证 codex --print "hello" --max-turns 1

方案四：检查凭证文件

# 步骤 1：检查凭证 ls -la ~/.codex/credentials.json cat ~/.codex/credentials.json # 查看内容 # 步骤 2：如果文件损坏 rm ~/.codex/credentials.json codex /login # 步骤 3：检查权限 chmod 600 ~/.codex/credentials.json # 步骤 4：验证 codex --print "hello" --max-turns 1

方案五：检查 API Key 有效性

# 步骤 1：测试 API Key curl -s https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' # 步骤 2：如果 401，Key 无效 # 登录 platform.openai.com 重新创建 # 步骤 3：如果 403，Key 被限制 # 检查账户状态 # 步骤 4：验证 codex --print "hello" --max-turns 1

方案六：清除缓存重新登录

# 步骤 1：清除所有凭证 rm -rf ~/.codex/credentials.json rm -rf ~/.codex/auth* rm -rf ~/.codex/session* # 步骤 2：重新登录 codex /login # 步骤 3：验证 codex --print "hello" --max-turns 1 # 步骤 4：如果仍失败，使用 API Key export OPENAI_API_KEY=sk-xxxxx codex --print "hello" --max-turns 1

4. 各方案对比总结

5. 常见问题 FAQ

5.1 OAuth 令牌多久过期

通常 1-2 小时。过期后需要刷新或重新登录。

5.2 如何重新登录

codex /login # 或 codex login

5.3 API Key 会过期吗

API Key 不会自动过期，但可以被手动撤销。

5.4 如何获取 API Key

登录 https://platform.openai.com/ → API Keys → Create。

5.5 令牌刷新失败

清除凭证重新登录：

rm ~/.codex/credentials.json codex /login

5.6 如何检查 Key 是否有效

curl -s https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{"model":"gpt-4o","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

5.7 多设备登录冲突

在一台设备登录可能导致另一台设备令牌失效。重新登录即可。

5.8 credentials.json 在哪里

通常在~/.codex/credentials.json。

5.9 API Key 和 OAuth 的区别

• API Key: 永久有效，适合 CI/CD
• OAuth: 自动刷新，适合交互使用

5.10 排查清单速查表

□ 1. codex /login 重新登录 □ 2. OPENAI_API_KEY=sk-xxx 使用 Key □ 3. codex /refresh 刷新令牌 □ 4. rm ~/.codex/credentials.json 清除 □ 5. codex /login 重新认证 □ 6. curl 测试 Key 有效性 □ 7. platform.openai.com 创建 Key □ 8. chmod 600 credentials.json 修复权限 □ 9. API Key 不会过期 □ 10. CI/CD 使用 API Key

6. 总结

1. 根本原因：会话过期最常见原因是 OAuth 令牌过期（40%）和 API Key 撤销（25%）
2. 最佳实践：使用codex /login重新登录，或使用OPENAI_API_KEY环境变量
3. API Key：在 platform.openai.com 创建，设置export OPENAI_API_KEY=sk-xxx
4. 凭证损坏：rm ~/.codex/credentials.json清除后重新登录
5. 最佳实践建议：CI/CD 中使用 API Key（永久有效），交互使用使用 OAuth（自动刷新）

故障排查流程图

flowchart TD A[会话过期] --> B[codex /login 重新登录] B --> C{成功?} C -->|是| D[✅ 问题解决] C -->|否| E[使用 API Key] E --> F[export OPENAI_API_KEY] F --> G[codex --print hello 验证] G --> H{成功?} H -->|是| D H -->|否| I[检查凭证文件] i --> j[ls ~/.codex/credentials.json] j --> K{文件存在?} K -->|否| L[codex /login 重新登录] K -->|是| M[rm 清除损坏凭证] M --> L L --> N{成功?} N -->|是| D N -->|否| O[测试 API Key] O --> P[curl api.openai.com] P --> Q{Key 有效?} Q -->|否| R[platform.openai.com 创建新 Key] Q -->|是| S[清除缓存] R --> F S --> T[rm -rf ~/.codex/credentials*] T --> B D --> U[CI/CD: 使用 API Key] U --> V[✅ 长期方案]