Codex / Claude Code 国内常见报错排错指南：401、403、429、登录卡住全解
更新于 2026-08-04 · 本站教程免费，长期更新
装好了 Codex 或 Claude Code 却跑不起来？国内环境下 90% 的报错集中在认证、网络、限流三类。这篇按报错现象给排查步骤，先对号入座再动手，不要一上来同时改 key、代理、Base URL——那样只会制造新问题。
排查总原则
| 现象 | 大概率卡在哪 | 第一步 |
|---|---|---|
| 401 Unauthorized | key 失效 / 认证缓存脏了 | 清认证缓存重登，或换 key 验证 |
| 403 Forbidden | 请求到了服务端但被拒：地区限制、账号策略、IP 不干净 | 分层定位（见下） |
| 429 rate_limit | 限流：订阅窗口额度用尽或 API 并发超限 | 确认是哪种限流 |
| timeout / fetch failed / ETIMEDOUT | 网络根本没通：代理没配、直连被断 | 检查网络出口 |
| 登录页卡住 / localhost 拒绝连接 | OAuth 回调链路断了 | 换 API key 模式或中转 |
一、登录问题
Codex：浏览器登录卡住、localhost 拒绝了我们的连接请求
codex login 依赖「浏览器授权 → 本地回调 → CLI 写入会话」整条链路，国内网络下回调经常失败。处理顺序：
# 1. 清掉脏的认证缓存再重试一次
rm -f ~/.codex/auth.json
codex login
反复失败就别死磕 OAuth，直接切 API key 模式（不需要回调）：在 ~/.codex/config.toml 配一个供应商（中转站给的 Base URL + key）：
model_provider = "relay"
[model_providers.relay]
name = "Relay"
base_url = "中转站给的 Base URL"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
注意 Codex 走的是 OpenAI Responses API 协议，买 Codex 额度时确认商品明确支持 Responses/Codex。
Claude Code：登录后仍然报错
claude logout && claude login
如果浏览器授权完成后命令行仍不可用，检查凭证是否写入了 ~/.claude/ 下的凭证文件。走中转的用户不需要官方登录，直接设环境变量：
export ANTHROPIC_BASE_URL="中转地址"
export ANTHROPIC_AUTH_TOKEN="中转key"
二、403 Forbidden（最复杂的一类）
403 表示请求到达了服务端但被拒绝，原因分层排查：
- 先用浏览器测：能正常登录 claude.ai / chatgpt.com 并对话 → 问题在终端网络层（最常见：终端不继承浏览器的系统代理）；浏览器也打不开或提示地区不可用 → 出口 IP 被地区限制，需要换出口或走中转；
- 给终端配代理（解决大多数「浏览器能用、终端不能用」）：
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
端口按你本地代理工具实际填。注意 Claude Code 读的是标准代理环境变量，且官方文档说明不支持 SOCKS 代理；还要检查 NO_PROXY 是否把目标域名排除掉了。
- 换 key 交叉验证：新 key 能用 → 旧 key 失效/被封；新 key 也 403 → 问题在账号或 IP 层；
- 都不行 → 出口 IP 不干净（数据中心段、共享 VPN）被风控。最省事的方案是改走国内可直连的中转额度，绕开整条海外链路。
三、429 限流
先弄清是哪种限流：
- 订阅窗口限流（Plus/Pro/Max 登录态）：额度按时间窗口重置，只能等。Codex 里进入会话后输入
/status查看用量与重置时间；Claude Code 用/status类命令查看（以各自官方文档为准）。经常撞墙说明档位不够，考虑升级 Pro 5X/20X、Claude Max，或把批量任务分流到按量中转； - API 并发/速率限流：立刻可以换 key 或换供应商继续跑——这正是 CC Switch 和 CCR 的用武之地。
四、超时与断流
ETIMEDOUT/fetch failed：网络没通，回到第二节配代理，或改用中转 Base URL；- 长任务中途断流：优先怀疑代理链路稳定性；走中转的换一家节点更近的试试；
- 公司网络报
407：企业代理要求认证，在代理 URL 里带上账号密码或找 IT；证书报错通常是企业中间人证书，需要把企业 CA 加进系统信任。
五、还是不行？
- 升级到最新版再试：
npm update -g @openai/codex @anthropic-ai/claude-code； - 用
claude /doctor（Claude Code 内置诊断）检查安装与网络（命令以官方文档为准：code.claude.com/docs、developers.openai.com/codex）； - 去官方仓库搜报错原文：anthropics/claude-code、openai/codex——大部分报错都有现成 issue。