【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. 原因分析

原因分类表

原因分类	具体表现	占比
OAuth 过期	时限	约 40%
API Key 撤销	被删除	约 25%
长时间未用	令牌过期	约 15%
密码更改	令牌失效	约 10%
刷新失败	网络	约 5%
多设备冲突	踢出	约 5%

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. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：重新登录	OAuth 过期	⭐⭐⭐⭐⭐	低
方案二：API Key	长期	⭐⭐⭐⭐⭐	低
方案三：刷新令牌	轻微	⭐⭐⭐⭐	低
方案四：检查凭证	损坏	⭐⭐⭐⭐⭐	低
方案五：测试 Key	Key 无效	⭐⭐⭐⭐⭐	低
方案六：清除缓存	严重	⭐⭐⭐⭐⭐	低

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[✅ 长期方案]