登录失败是新手使用 Codex 时最常见的障碍之一。大多数登录问题可以通过区分登录路径和排查网络层级来解决，而非简单地重装工具。

常见登录路径

  1. ChatGPT 浏览器登录：依赖本地回调完成验证。

    2. 2. 设备码登录 (--device-auth)：适合浏览器回调受阻的环境。

    3. API Key 登录：直接使用 Token 进行认证。

    问题分类与排查

    1. 浏览器回调失败

    表现为浏览器已提示登录成功，但终端（CLI）没有任何反应。

    • 根因：本地 localhost 回调被防火墙、代理或安全软件拦截。
    • 解决：尝试运行 codex logout 清理状态，或改用设备码登录方式。

    2. 设备码验证异常

    • 根因：验证码过期、网络无法访问登录页面或工作区权限限制。
    • 解决：确认网络连通性，并在有效期内完成验证。

    3. API Key 认证无效

    表现为 401 Unauthorized 或 Invalid API key。

    • 根因：Key 包含多余空格、已失效、或误用了非平台级 Token。
    • 解决：重新核对 Key 的完整性，确认其在服务商控制台的状态。

    4. 本地缓存冲突

    • 根因：~/.codex/auth.json 损坏或 CLI 与 IDE 间的登录状态同步异常。
    • 解决：优先执行 codex logout 彻底退出，再重新尝试登录，避免直接删除配置目录。

    进阶环境问题

    在企业网络环境下，TLS 代理或私有 CA 证书可能会拦截 HTTPS 请求，导致 CLI 登录失败。若浏览器可上网但 CLI 报错，应优先排查企业级网络代理配置。

    排障核心原则

    • 一次只试一种方式：不要同时尝试多种登录路径。
    • 不要泄露敏感信息：排障时严禁将真实的 API Key 或 Token 贴入聊天或日志中。
    • 优先清理状态：遇到卡顿时，先尝试 logout 恢复干净状态。

    做到分清类型、按序排查，绝大多数登录问题都能在几分钟内解决。