# Codex / Claude Code 国内常见报错排错指南：401、403、429、登录卡住全解

> Codex 登录卡在 localhost 回调？Claude Code 一启动就 403？429 限流怎么办？国内环境下 Codex 与 Claude Code 的常见报错分类排查手册。
> 更新于 2026-08-04 · 难度 初级 · 来源 https://aicdks.com/guides/codex-claude-code-troubleshooting

装好了 [Codex](/guides/install-codex-cli-china) 或 [Claude Code](/guides/install-claude-code-china) 却跑不起来？国内环境下 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 写入会话」整条链路，国内网络下回调经常失败。处理顺序：

```bash
# 1. 清掉脏的认证缓存再重试一次
rm -f ~/.codex/auth.json
codex login
```

反复失败就别死磕 OAuth，直接切 **API key 模式**（不需要回调）：在 `~/.codex/config.toml` 配一个供应商（中转站给的 Base URL + key）：

```toml
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 额度](/category/api-中转与额度-codex-额度)时确认商品明确支持 Responses/Codex。

### Claude Code：登录后仍然报错

```bash
claude logout && claude login
```

如果浏览器授权完成后命令行仍不可用，检查凭证是否写入了 `~/.claude/` 下的凭证文件。走中转的用户不需要官方登录，直接设环境变量：

```bash
export ANTHROPIC_BASE_URL="中转地址"
export ANTHROPIC_AUTH_TOKEN="中转key"
```

## 二、403 Forbidden（最复杂的一类）

403 表示请求**到达了服务端但被拒绝**，原因分层排查：

1. **先用浏览器测**：能正常登录 claude.ai / chatgpt.com 并对话 → 问题在终端网络层（最常见：终端不继承浏览器的系统代理）；浏览器也打不开或提示地区不可用 → 出口 IP 被地区限制，需要换出口或走[中转](/guides/what-is-api-relay)；
2. **给终端配代理**（解决大多数「浏览器能用、终端不能用」）：

```bash
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
```

端口按你本地代理工具实际填。注意 Claude Code 读的是标准代理环境变量，且官方文档说明不支持 SOCKS 代理；还要检查 `NO_PROXY` 是否把目标域名排除掉了。

3. **换 key 交叉验证**：新 key 能用 → 旧 key 失效/被封；新 key 也 403 → 问题在账号或 IP 层；
4. 都不行 → 出口 IP 不干净（数据中心段、共享 VPN）被风控。最省事的方案是改走国内可直连的[中转额度](/category/api-中转与额度)，绕开整条海外链路。

## 三、429 限流

先弄清是哪种限流：

- **订阅窗口限流**（Plus/Pro/Max 登录态）：额度按时间窗口重置，只能等。Codex 里进入会话后输入 `/status` 查看用量与重置时间；Claude Code 用 `/status` 类命令查看（以各自官方文档为准）。经常撞墙说明档位不够，考虑升级 [Pro 5X/20X](/category/ai-账号与服务-chatgpt-pro-5x)、[Claude Max](/category/ai-账号与服务-claude-max-5x-代充)，或把批量任务分流到按量中转；
- **API 并发/速率限流**：立刻可以换 key 或换供应商继续跑——这正是 [CC Switch](/guides/cc-switch-tutorial) 和 [CCR](/guides/api-switching-tools-compared) 的用武之地。

## 四、超时与断流

- `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](https://code.claude.com/docs)、[developers.openai.com/codex](https://developers.openai.com/codex/)）；
- 去官方仓库搜报错原文：[anthropics/claude-code](https://github.com/anthropics/claude-code/issues)、[openai/codex](https://github.com/openai/codex/issues)——大部分报错都有现成 issue。

## 相关教程

- [Codex 安装教程](/guides/install-codex-cli-china) / [Claude Code 安装教程](/guides/install-claude-code-china)
- [API 中转是什么](/guides/what-is-api-relay)
- [CC Switch 使用教程](/guides/cc-switch-tutorial)