报错现象
Claude Code 的报错集中在三条线上：登录认证、网络链路、额度消耗。三条线的报错形态不同，排查动作也完全不同，混在一起猜只会浪费时间。下面是三个最高频的现场（报错原文以实际粘贴为准，先对号入座）：
场景 A：昨天还好好的，今天一启动就要求重新登录，或对话直接返回认证错误：
【待补：登录类报错完整原文，例如认证失效/Invalid API key 一类的实际输出】场景 B：能启动、能打字，但一发消息就转圈后超时或连接失败，多见于公司网络或挂了代理的机器：
【待补：网络类报错完整原文，例如 fetch failed / 超时 / 连接被重置一类的实际输出】场景 C：对话到一半返回限流或额度类错误，隔一段时间又能用，或换 Key 才能用：
【待补：额度/限流类报错完整原文，例如 rate limit / credit balance 一类的实际输出】环境
| 项目 | 说明 |
|---|---|
| Claude Code | npm 全局安装【待补：实测版本号】 |
| Node.js | 18 及以上，LTS 为主力（当前 Node.js 22.0 系列）【待补：实测版本号】 |
| 操作系统 | Windows 11（原生）/ WSL2 Ubuntu【待补：实测具体版本】 |
| 网络环境 | 分两类：可直连官方端点的网络；需代理或中转的网络 |
| 认证方式 | 订阅 OAuth 登录 / API Key / 中转 Token，三种都可能是报错源头 |
排查过程
先跑官方自检，把环境问题摘出去：
claude --version
claude doctorclaude doctor 会检查安装完整度和基础连通性，它标出来的问题先修，再往下走。然后按三条线分开排查。
登录线。 第一步确认当前认证状态：REPL 里输 /status，看认证方式是 OAuth、API Key 还是中转 Token。第二步验证 Key 本身有没有效——API Key 泄露后被平台作废是常见事，去发放方后台（Anthropic Console 或中转后台）看 Key 状态是否还在启用。第三步排查环境变量污染：echo $ANTHROPIC_API_KEY（PowerShell 用 echo $env:ANTHROPIC_API_KEY），确认没有指向一个早已作废的旧 Key——settings.json 的 env 段和 shell 里的 export 都可能藏着旧值。
网络线。 用最小请求测端点连通性，绕开 Claude Code 本身：
curl -sv -o /dev/null https://api.anthropic.com 2>&1 | grep -E "Connected|HTTP|SSL"【待补：curl 实际输出】能建立 TLS 连接说明链路通，报错在认证或额度；连不上就是代理或防火墙问题。挂代理的机器检查 HTTPS_PROXY / HTTP_PROXY 环境变量有没有设、端口对不对；走中转的检查 ANTHROPIC_BASE_URL 拼写（协议、域名、路径逐段比对）。
额度线。 订阅用户的额度按官方说明以约 5 小时为周期滚动重置，“过了几小时又能用”本身就是额度线的证据。API 计费用户去 Console 看余额和用量明细；中转用户去中转后台看这一侧的余额——两边是独立账户，充错边是最常见的乌龙。
根因
三条线的典型根因各一个：
- 登录类：认证凭证失效。可能是 OAuth 令牌过期、Key 被作废，也可能是 shell 环境变量/
env配置里残留了旧 Key，优先级压过了登录态，请求带着死凭证出门。 - 网络类：链路没打通。机器到官方端点之间被墙或被防火墙拦截；或代理变量没设导致直连；或中转地址写错、中转服务本身宕了。这一类的报错发生在”请求发出去之前或半路”，和 Key 对不对无关。
- 额度类：凭证有效、链路通，但配额到顶。订阅是滚动窗口限流，等窗口重置就恢复；API 是余额耗尽，充值才恢复；中转是中转侧余额或限流规则触发。
一句话判断：认证错误看凭证、连接错误看链路、限流错误看窗口和余额。
修复方案
登录类修复——清掉旧认证重来：
# REPL 内执行
/login按引导走完浏览器授权即可；API Key 用户则把有效 Key 重新写入环境变量或 ~/.claude/settings.json 的 env 段，并确认作废的旧 Key 已从所有配置位置删除。
网络类修复——把链路配通再启动：
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890端口按你自己的代理客户端改【待补：实测可用的端口】。走中转的直接配端点变量：
export ANTHROPIC_BASE_URL="https://你的中转域名"
export ANTHROPIC_AUTH_TOKEN="中转Key"额度类修复——订阅用户等窗口重置或升级套餐（具体额度数值【待补：官方当前公开的额度说明】）；API 用户充值；中转用户在中转后台充值或调整限流规则。想省额度，把后台小模型也指到便宜通道（ANTHROPIC_SMALL_FAST_MODEL，详见 API Key 配置篇的坑 3）。
验证
修复后统一用同一个动作闭环：/status 确认认证方式与端点符合预期，然后跑最小调用：
claude -p "回答一个字：好"有回复即整条链路（认证→网络→模型）全通。三类报错各自再补一个针对性确认：登录类看 /status 不再要求登录；网络类看 curl 握手成功且 Claude Code 不再超时；额度类看连续多轮对话不再触发限流【待补：修复前后对比记录】。
【待补：/login 重新授权成功或正常运行状态截图】
如何预防
- 固定配置进文件，临时配置进终端：代理和中转变量写进
~/.claude/settings.json的env段，避免每次开终端手动 export、也避免旧变量残留——环境变量优先级问题大多出在”忘了自己设过什么”。 - 换 Key 必做三件事：后台作废旧 Key、全局搜索配置目录里的旧值（
grep -r "sk-ant" ~/.claude一类）、重跑/status。 - 网络环境变化先跑自检：换了办公网、换了代理端口，先
claude doctor再干活。 - 额度看趋势不看单点：API 用户定期看 Console 用量曲线，中转用户开着后台余额提醒，别等报错才发现账户空了。
- 升级别拖：Node.js 与 Claude Code 保持在新 LTS 与近期版本，一部分”玄学超时”是旧版本网络栈问题，升级后自然消失（升级方法见版本管理篇）。