Claude Code 连接失败与认证错误排查

已经装好 Claude Code 却登不上、连不上、发不出请求时的完整排查路径：从服务状态、版本与认证方式，到环境变量、代理、DNS、出口 IP、企业防火墙与证书，最后是调试日志与官方支持。

先归类，再排查

绝大多数问题落在四类里，而且报错文本通常已经指明了类别：

报错方向	类别	换网络有用吗	重新登录有用吗
找不到命令	安装与 PATH	无关	无关
未登录、令牌过期、403、组织被停用	认证与账号	通常无关	有用
连接被拒、超时、无法解析、代理拒绝	网络与代理	有用	无关
证书校验失败、自签名证书	TLS 与企业拦截	部分有关	无关
529 过载、429 限流	服务端与额度	无关	无关

分错类别是最常见的时间浪费：网络问题反复重装，认证问题反复换节点，两边都不会有进展。

第一步：命令能不能跑起来

如果连 claude 都执行不了，那还谈不上连接问题。

claude --version

正常会输出版本号加 (Claude Code)。报「找不到命令」时：先关闭并重新打开终端（安装后没重开终端是第一大原因），仍然不行就检查安装目录是否在 PATH 中。Windows 上还要注意桌面版可能占用了同名命令，以及机器上是否存在多份安装或旧的 shell 别名。

这一类属于安装问题，处理方式见 Claude Code 安装与初始化。

第二步：服务状态与版本

服务状态。 打开 status.claude.com。反复出现 529 过载提示时基本可以确定是服务端容量问题——客户端本身会带退避地自动重试，多等一会儿即可，本地怎么调都没用。

版本。 版本落后时先更新：

claude update

原生安装平时会后台自动更新；Homebrew、WinGet 与 Linux 包管理器安装需要手动升级。更新前后各跑一次复现步骤，能省下大量猜测。

只读诊断。

claude doctor

它不启动会话，也不改配置，输出包括安装健康度、设置文件的语法错误、最近一次自动更新的结果，以及带建议的告警。遇到问题先跑它，而不是先重装。

第三步：认证

先看清楚现在用的是什么

在会话里运行：

/status

这一步经常直接给出答案：你以为在用订阅，实际生效的是某个 API Key；你以为代理配好了，实际那一行显示为无法解析。

重置登录

原因不明确时，一次干净的重新认证能解决大部分问题：

1. 运行 /logout 完全退出
2. 关闭 Claude Code
3. 重新运行 claude，走完整个认证流程

浏览器没有自动打开时，在登录提示处按 c 复制授权链接，手动粘贴到浏览器打开。这在 SSH 和窄终端下尤其有用——链接换行后没法直接点。

远程环境登录不了

WSL2、SSH、容器里，浏览器开在另一台机器上，回调回不到本地。登录后页面会给一串登录码，粘回终端提示处即可。如果粘贴进不去（终端的粘贴快捷键没送进输入框），改用：

claude auth login

它从标准输入读取登录码。WSL2 下浏览器完全打不开时，可以把 BROWSER 变量指向 Windows 侧的浏览器可执行文件路径。

登录成功但立刻 403

订阅用户先确认订阅仍在有效期内；Console 用户需要管理员在成员设置里授予 Claude Code 或 Developer 角色。两者都正常却依然 403，那要怀疑公司代理干扰了 API 请求，跳到代理那一节。

频繁被要求重新登录

先运行 /login 重新认证。如果反复发生，检查系统时钟——令牌校验依赖正确的时间戳，时间偏差过大会导致令牌被判定为无效。

macOS 上还有一种情况：钥匙串不可写时（SSH 会话中被锁定，或钥匙串密码与账户密码不同步），凭据会退回到明文文件保存。claude doctor 会给出对应告警和修复建议，可以用系统自带的钥匙串解锁命令处理，之后再 /logout 并重新登录，把凭据移回加密存储。

第四步：账号与 API 凭据

这是最容易踩、也最难自己想到的一个坑。

如果环境里存在 ANTHROPIC_API_KEY，它会覆盖订阅的登录凭据。 典型症状是：明明有有效订阅，却报组织已被停用之类的账号错误。来源通常是上一家公司、上一个项目留在 shell 配置里的旧 Key。

处理方式是在当前终端取消这个变量后重新运行 claude，并把它从 shell 配置文件（.zshrc、.bashrc、.profile，Windows 上是 PowerShell 配置文件与用户环境变量）里删掉，否则下次开终端又会回来。改完用 /status 确认生效的认证方式变了。

反过来，如果你本来就想用 API Key，那要确认这个 Key 有效、账户里还有可用额度，并且用的是 Console 账号而不是订阅登录。区分 429 的两种含义也在这里：限流是临时的，等一会儿就好；额度或消费限额触顶不会自己恢复，需要去账号里处理。

第五步：环境变量

有一条规则先说清楚：这些变量在启动时读取一次，正在运行的会话不会感知到后来的改动。 改完必须退出重开。

需要重点确认的几个：

变量	作用	常见错误
ANTHROPIC_API_KEY	API 认证	历史遗留值覆盖了订阅登录
HTTPS_PROXY / HTTP_PROXY	代理地址	缺少 http:// 前缀；写成了 SOCKS 地址
NO_PROXY	绕过代理的主机	分隔符写错，或该绕过的没写进去
NODE_EXTRA_CA_CERTS	额外信任的 CA 证书	路径不存在或权限不足

代理变量的大小写形式都能识别，生效顺序是 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY，用第一个已设置的值。所以同时设了大小写两份且内容不一致时，实际生效的可能不是你以为的那个。

NO_PROXY 支持空格分隔与逗号分隔两种写法，* 表示全部绕过。本地回环地址不需要特意写进去。

第六步：终端与运行环境

几个和终端本身有关的排查点：

• 变量是在哪个终端里设置的。 只在当前窗口 export 的变量，换一个窗口就没了；写进配置文件才会持久。
• IDE 插件不继承 shell 环境。 终端里能用、VS Code 或 JetBrains 里不行，多半是 IDE 进程没有继承你的 shell 变量。要么在 IDE 自己的设置里配，要么从已经导出变量的终端里启动 IDE。
• 后台任务不共享你的 shell。 需要让所有会话都拿到同一份网络配置时，把变量写进设置文件的 env 块，而不是只在某个 shell 里导出。

第七步：代理

企业环境里最常见的一类问题。要点：

地址必须带协议前缀。 缺少 http:// 这类前缀时，Claude Code 在启动阶段就会报错并指出是哪个变量——这是少数会在启动时校验的配置。

不支持 SOCKS 代理。 只支持标准的 HTTP 与 HTTPS 代理变量。需要 NTLM、Kerberos 这类认证时，官方建议改用支持对应认证方式的网关服务。

代理需要允许 CONNECT 隧道。 报「代理拒绝连接」时，除了认证信息，还要确认代理策略允许 CONNECT。

代理接受了连接却不转发请求，表现是「没有任何响应」——请求发出去后迟迟等不到响应头。这类问题在代理日志里比在客户端更容易看清楚。

安装阶段也可能卡在代理上。先确认能不能连上下载服务器：

curl -sI https://downloads.claude.ai/claude-code-releases/latest

第一行是 200 说明连通。403 通常是代理或网络过滤拦截，也可能是所在地区不在支持范围内；5xx 一般是临时问题。完全没有输出、报无法解析主机或超时，说明连接被网络阻断。

Windows PowerShell 里要写 curl.exe，因为 PowerShell 把 curl 映射成了自己的命令，不认这些参数。

第八步：DNS 与网络质量

判断方法和其他服务一样：同一台机器上其他网站是否正常？ 只有这几个域名解析不了，是域名层面的问题；全都不正常，那是本地网络问题。

需要能正常访问的主要域名：

• api.anthropic.com —— 模型请求
• claude.ai、claude.com、platform.claude.com —— 登录与令牌交换
• downloads.claude.ai —— 安装与自动更新
• registry.npmjs.org —— 仅 npm 安装方式需要

网络质量方面要区分两种表现：持续失败多半是被拦或配置错误；间歇中断（跑着跑着断开、偶尔超时）才是链路质量或中间设备切断长连接的典型症状。后者只能靠记录时间与频率、在另一网络下对照来定位。

超时相关的行为也可以调：客户端对流式响应有多个空闲看门狗，网络较慢时可以适当放宽超时阈值，但这只是缓解症状，不解决根因。

第九步：出口 IP 与企业防火墙

出口 IP。 如果换到另一个出口环境后立刻正常，说明原出口被限制或被判定为异常来源。注意它只解释连接层面的问题——账号被停用、角色权限不足、订阅过期这些换多少个出口都一样。

企业防火墙与安全网关。 需要网络管理员确认三件事：上面列出的域名已放行；代理允许 CONNECT 隧道；TLS 拦截没有破坏握手或提前关闭长连接。

如果公司启用了 IP 允许列表一类的策略，还要确认代理出口地址本身在允许范围内——否则表现会很怪：一部分功能正常，另一部分连不上。

第十步：TLS 与证书

报证书校验失败、自签名证书在链上、拿不到本地颁发者证书，基本都指向同一件事：企业网络在做 TLS 拦截，而它的根证书不在可信范围内。

默认情况下 Claude Code 同时信任内置的 CA 集合和操作系统的证书存储，所以企业根证书装进系统信任库通常就够了。仍然不行时，向 IT 索取证书文件并显式指定：

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

Windows PowerShell：

$env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'

设置后重启会话，然后确认它真的加载了（见下一节）。要验证服务器证书链本身是否正常，可以用：

openssl s_client -connect api.anthropic.com:443

这里有一条不能越过的线：不要关闭证书校验。 网上常见的「设个环境变量跳过 TLS 验证就好了」是错误建议——它把加密连接降级成了任何中间人都能读写的通道，公司里这么做通常也直接违反安全规范。正确做法只有一个：配置可信 CA。同理，也不要为了让它跑起来而永久关闭防火墙或绕过企业安全策略。

第十一步：读调试日志

前面都排除不掉时，让它把过程写下来：

claude --debug

调试输出写入用户目录下 .claude/debug/ 里以会话 ID 命名的文件，而不是打在终端上；也可以用 --debug-file 指定路径。

日志里值得找的几行：额外 CA 证书是否从 NODE_EXTRA_CA_CERTS 成功追加、客户端证书与私钥是否加载成功。如果某个文件读不到，日志会写明读取失败及原因——这比在客户端界面上猜要直接得多。

会话内的 /status 也会显示代理地址（无法解析的值会标为已忽略）与证书加载情况，两者配合看。

什么时候该联系官方支持

本地排查全部通过、问题依然复现，或者问题本身就在服务端（账号状态、计费、角色权限），就不要继续在本地折腾了。提交时带上：

• 报错原文与发生时间
• claude --version 与 claude doctor 的输出
• 复现步骤
• 是否在另一台设备、另一个网络下同样复现

相关内容

• 装不上、命令找不到：Claude Code 安装与初始化
• 装好了想学怎么用：Claude Code 完整使用教程
• 是 Claude 网页端或客户端打不开，而不是命令行：Claude 连接失败与网络问题排查
• 用 Anthropic API 直接调模型时的问题：Anthropic API 快速上手

参考资料

• Claude 服务状态页
• 安装与登录问题排查（官方文档）
• 企业网络配置：代理、CA 与 mTLS（官方文档）
• 错误信息参考（官方文档）