连接失败：DNS、代理与 TLS 排障

01先确认故障发生在哪一层

安装下载失败、登录失败、模型请求失败和外部工具失败不一定来自同一域名。记录发生时间、Claude Code 版本、操作系统和错误原文，再定位请求目标。

检查顺序建议为域名解析、连接、TLS、HTTP 状态和应用层响应。一次只改变一个变量，避免同时更换代理、证书和网关后失去判断依据。

02核对代理配置

官方支持 HTTP/HTTPS 代理相关环境变量，当前文档说明不支持 SOCKS 代理。代理地址应包含正确协议、端口和实际可达的服务。

下方是本地 HTTP 代理的格式示例，127.0.0.1:7890 不是本站提供的服务；请替换成自己的网络配置。

export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
claude doctor

03证书问题单独处理

企业 TLS 检查代理可能使用组织 CA。优先由管理员正确安装组织证书；需要附加 CA 时，按官方说明使用 NODE_EXTRA_CA_CERTS，并确认文件路径与证书格式。

• 不要通过关闭证书校验掩盖证书链问题。
• 代理认证失败和上游 API 认证失败属于不同环节。
• HTTP 401、403、429、5xx 应结合响应主体与提供方说明判断。

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

04一份有效的故障报告

记录“哪条命令、哪个目标、什么错误、何时发生、如何复现”。分享时删去 Authorization、Cookie、API Key 和源码片段，仅保留诊断必需信息。

05按错误类型缩小检查范围

名称解析错误：先查域名是否拼错、DNS 是否返回结果。连接拒绝或超时：检查代理是否运行、地址与端口是否正确，以及网络策略是否允许出站。

证书链错误：检查企业 CA 和系统时间。HTTP 401：检查目标主机与鉴权方式。HTTP 429：查看服务方返回的限流说明。HTTP 5xx：记录响应标识并区分网关返回还是上游返回。

• 同一错误在多个项目复现，优先检查用户环境与网络。
• 仅某个模型失败，优先检查模型权限或网关映射。
• 短请求成功但长请求断开，重点观察流式超时与代理缓冲。
• 浏览器能打开官网，不代表 CLI 的 API 请求链路相同。