Claude Code 提示“Unable to connect to API”，后面跟着 Self-signed certificate detected、unable to get local issuer certificate 或 SSL certificate has expired，反复重试通常无法解决。需要处理的是报错对应的证书信任、证书链、代理配置或客户端版本问题。

浏览器能够打开网页，并不意味着 Claude Code 使用的运行时已经信任同一条证书链。终端可用、桌面端不可用，也需要核对两个入口实际使用的版本和配置。

## 一、SSL 报错不同，解决方向也不同

| 报错关键词 | 含义与检查方向 |
| --- | --- |
| SELF_SIGNED_CERT_IN_CHAIN / Self-signed certificate detected | 证书链无法连接到受信任的 CA；检查企业 HTTPS 检查设备、私有网关以及额外 CA 是否加载 |
| UNABLE_TO_GET_ISSUER_CERT / unable to get local issuer certificate | 无法构建受信任的签发链；检查缺失的中间证书、CA 信任和版本缺陷 |
| CERT_HAS_EXPIRED / SSL certificate has expired | 检查系统时间、服务端证书及企业检查设备的证书有效期，也要核对证书链构建问题 |
| Hostname/IP does not match certificate's altnames | 请求的域名与证书 SAN 不匹配；检查实际访问地址、DNS、代理转发和网关证书 |
| EPROTO / TLS handshake failed / wrong version number | 属于握手或协议问题；检查代理协议与端口、网关兼容性和版本，不应直接判定为缺少 CA |

上述提示能够缩小范围，但不能单凭一行报错确定根因。例如 issuer 错误既可能是客户端没有企业根证书，也可能是服务端没有发送必要的中间证书。

## 二、核对版本和实际启动的 Claude Code

终端执行：

```bash
claude --version
claude doctor
```

Windows PowerShell 查看命令来源：

```powershell
Get-Command claude -All | Select-Object CommandType, Source
```

macOS、Linux 查看命令来源：

```bash
type -a claude
```

机器上同时存在原生版、npm 版和 IDE 扩展时，更新一个入口不代表其他入口也已更新。原生安装可使用 `claude update`；通过包管理器安装的版本按对应包管理器更新；桌面应用和 VS Code 扩展也需要分别检查更新。

截至 2026 年 11 月 12 日，官方更新日志已记录多项相关修复：

- **2.1.314**：修复系统证书库中续期根证书与旧根交叉签名时触发的 UNABLE_TO_GET_ISSUER_CERT。
- **2.1.317**：修复部分 HTTPS 检查代理在根证书续期后出现的 unable to get local issuer certificate。
- **2.1.318**：修复 NODE_EXTRA_CA_CERTS 文件为空、非 PEM 或以损坏证书开头时，导致所有连接失败的问题；可读证书会继续使用，并输出警告。
- **2.1.321**：修复回复过程中连接中断时，以 EPROTO: The TLS handshake failed 直接结束任务的问题，恢复保留部分回复或重试的处理。

遇到升级后突然出现的证书问题，应对照版本修复记录更新受影响入口。不能把“升级”理解为能够修复所有过期证书或服务端配置错误。

## 三、企业 CA 不受信任：配置 NODE_EXTRA_CA_CERTS

公司网络启用了 HTTPS 检查，或者访问的是私有证书签发的网关时，Claude Code 可能需要额外信任对应 CA。

### 1. 获取正确的 CA 文件

向网络或系统管理员获取用于该连接的 CA 公钥证书，使用 PEM 格式。不要把 API Key、客户端私钥或随意下载的证书填到这里。

PEM 证书的内容具有以下边界：

```text
-----BEGIN CERTIFICATE-----
证书的 Base64 内容
-----END CERTIFICATE-----
```

扩展名不是判断依据：把二进制 DER 文件改名为 .pem，不会完成格式转换。Windows 导出时可选择“Base-64 编码 X.509”。文件中也不应出现 BEGIN PRIVATE KEY。

### 2. 在启动终端中设置绝对路径

Windows PowerShell：

```powershell
$env:NODE_EXTRA_CA_CERTS = 'C:\certs\company-ca.pem'
Test-Path -LiteralPath $env:NODE_EXTRA_CA_CERTS
claude
```

macOS、Linux：

```bash
export NODE_EXTRA_CA_CERTS="/absolute/path/company-ca.pem"
test -r "$NODE_EXTRA_CA_CERTS" && echo "CA file is readable"
claude
```

路径必须替换为真实文件位置。上面的命令设置当前终端环境，需要从这个终端启动新的 Claude Code 进程；已经运行的会话不会因为另一个终端修改了环境变量而自动更新。

### 3. 需要持续生效时，合并到用户设置

可在 `~/.claude/settings.json` 的 `env` 对象中配置。Windows 中的对应位置通常为 `%USERPROFILE%\.claude\settings.json`。

```json
{
  "env": {
    "NODE_EXTRA_CA_CERTS": "C:/certs/company-ca.pem"
  }
}
```

macOS、Linux 将值换成对应绝对路径。原文件已有配置时，合并 env 字段并保留其他设置，不要用示例覆盖整个文件。启动进程环境中已有的同名变量可能覆盖 settings.json 的值，因此还要核对启动环境中的旧路径。

### 4. 核实证书确实加载

执行：

```bash
claude --debug
```

调试日志位于 `~/.claude/debug/`。检查是否出现类似下面的信息：

```text
CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (...)
```

如果日志显示无法读取、无法加载，或者没有可解析证书，应检查路径、文件读取权限和 PEM 格式。

`/status` 中显示 Additional CA cert(s) 路径，仅代表配置了这个路径，不能证明文件已成功加载。还需要实际发送请求验证。

## 四、系统证书已安装，Claude Code 为什么仍然报错？

当前官方文档说明，Claude Code 默认结合内置 Mozilla CA 和系统 CA，默认值为：

```text
CLAUDE_CODE_CERT_STORE=bundled,system
```

但读取系统 CA 依赖运行时能力。原生安装包含相应支持；npm 方式需要支持 `tls.getCACertificates` 的 Node.js，官方文档要求 Node.js 22.15 或更新版本。较旧运行时不能据此假定会读取系统证书库。

因此，“Claude Code 永远不读取系统证书”已经是不准确的概括。处理方法是核对安装方式、版本和运行时，并使用受支持的 CA 配置。

还有一种容易忽略的情况：系统证书库中的新旧根证书、交叉签名证书造成了证书链选择冲突。官方已提供相关版本修复，不宜继续复制旧文章中的全局删除证书操作。

若更新后仍需定位系统证书库冲突，可在管理员确认 CA 正确后，对单次启动使用以下组合进行验证：

```powershell
$env:CLAUDE_CODE_CERT_STORE = 'bundled'
$env:NODE_EXTRA_CA_CERTS = 'C:\certs\company-root-ca.pem'
claude
```

这里的 bundled 会排除系统 CA，保留内置 CA，再通过 NODE_EXTRA_CA_CERTS 添加明确需要的企业 CA。它不是所有 SSL 报错都需要添加的固定配置，也不意味着证书文件越大越好。

## 五、代理协议或端口填错：检查 HTTPS_PROXY

`HTTPS_PROXY` 表示 HTTPS 目标请求使用哪个代理，不代表变量里的代理地址必须写成 `https://`。

如果本机代理提供的是 HTTP 或 mixed 入口，可采用以下形式，端口替换为代理软件中实际显示的 HTTP/mixed 端口：

```powershell
$env:HTTPS_PROXY = 'http://127.0.0.1:实际端口'
$env:HTTP_PROXY = 'http://127.0.0.1:实际端口'
```

macOS、Linux：

```bash
export HTTPS_PROXY="http://127.0.0.1:实际端口"
export HTTP_PROXY="http://127.0.0.1:实际端口"
```

代理 URL 的 scheme 描述客户端连接代理服务器时使用的协议。HTTP 代理可以通过 CONNECT 转发 HTTPS 请求，目标连接仍可使用 TLS；但远程 HTTP 代理入口自身不具有 HTTPS 代理入口的传输保护，不能把两者随意互换。

检查以下项目：

- HTTP 入口是否误写为 https://，或使用了 SOCKS 专用端口。
- 同时设置大小写变量时是否存在冲突。官方文档说明小写变量优先，需要检查 https_proxy、http_proxy。
- NO_PROXY 是否让目标绕过了本应使用的代理。
- 代理程序是否运行，填写的地址是否属于 Claude Code 所在环境。

Claude Code 官方网络配置目前不支持直接使用 SOCKS 代理。代理软件只提供 SOCKS 入口时，需要采用客户端支持的 HTTP 接入方式。

WSL、容器、SSH 远端中的 127.0.0.1 指向各自环境，不能直接套用 Windows 宿主机的回环地址。应核对实际网络模式和可达地址，而不是反复替换证书。

开启 TUN 可能改变流量路径，但不能自动修复证书过期、域名不匹配或缺失的 CA，也不应作为所有 SSL 错误的统一答案。

## 六、证书过期、域名不匹配和证书链缺失怎么处理？

### 1. SSL certificate has expired

核对电脑日期、时间和时区。时间异常会影响证书有效期判断。

时间正确时，需要检查连接链路上实际返回的证书：目标服务证书、私有网关证书，以及企业 HTTPS 检查设备签发的证书都可能过期。

证书实际过期，应由对应服务或设备管理员更新证书；把过期证书加入信任文件不会延长有效期。如果证书本身有效、仅特定 Claude Code 版本失败，再检查证书链选择与版本缺陷。

### 2. Hostname mismatch

核对 API 或网关地址是否拼写正确、是否误用 IP 地址代替证书覆盖的域名，以及代理或 DNS 是否把请求送到了错误服务。

证书 SAN 应包含实际访问的域名。添加根证书无法修复域名不匹配，必须修正目标地址、路由或服务端证书。

### 3. 服务端缺少中间证书

服务端只发送站点证书，没有提供所需中间证书时，浏览器与不同运行时可能表现不同。应由服务端配置正确的证书链，通常发送站点证书和必要的中间证书；根证书通常不需要由服务端发送。

客户端额外信任 CA 与服务端补齐证书链是不同操作，不能用“导出当前网页证书就行”概括。

## 七、终端正常，桌面端或 VS Code 仍失败怎么办？

### 1. 检查配置加载范围

从桌面快捷方式启动的应用，不一定继承刚刚在终端设置的环境变量。修改终端环境后，需要退出并重新启动相应进程。

桌面应用管理的连接还有配置范围区别：官方文档明确，这类连接读取托管设置和用户级 `~/.claude/settings.json` 中的相关网络变量，不能依赖仓库内的项目配置。桌面 Code 标签页的本地、SSH、WSL 会话与应用管理的第三方提供商连接也不能混为一谈。

### 2. 更新对应应用和扩展

CLI 的更新不等于桌面应用内置组件或扩展已经更新。应核对真正报错的入口，并在调试日志中检查被忽略的设置项。

### 3. 区分模型请求、WebFetch 和 MCP

模型能够回复，不代表 WebFetch、远程 MCP 或 MCP OAuth 都使用了同一条连接路径。WebFetch 的安全预检还可能访问 Claude 的服务，不能只放行第三方模型网关。

只有某个 MCP 服务器失败时，应检查该服务器及其登录域名的证书，而不是直接重置整个 Claude Code 配置。只有 Bash 中的 Python、Git 等子程序报证书错误时，需要检查对应工具自己的信任配置；Claude Code 能联网不代表所有子程序都已正确配置。

## 八、安装阶段报 SSL 错误，处理方式有什么不同？

安装器下载、npm 下载和 Claude Code 启动后的 API 请求属于不同阶段。尚未安装完成时，修改 Claude Code 的 settings.json 通常不能修复下载工具本身的 TLS 信任。

例如 curl 下载失败，需要检查 curl 使用的证书库及代理；npm 报证书错误，需要检查 npm/Node 的 CA 配置和 registry 连接。组织提供的 CA 可以通过相应下载工具支持的 CA 选项接入，但不应关闭证书校验来完成安装。

排查放行规则时也要对应实际域名：原生下载与更新涉及 downloads.claude.ai，npm 及插件依赖涉及 registry.npmjs.org，插件克隆可能涉及 github.com。API、认证和下载不是同一个地址。

## 九、怎样确认问题已经解决？

`claude --version` 只显示本地版本，不会证明 API 请求成功；端口连通也不能证明 TLS 校验和认证通过。

在配置对应的启动环境中执行一个最小请求：

```bash
claude -p "只回复 OK，不调用工具"
```

账号或 API 凭据已正常配置的前提下，收到正常回复才能验证这条模型请求路径。该请求会使用账号或 API 用量。

如果原问题发生在桌面端、VS Code、WebFetch 或 MCP，需要回到相同入口执行相同类型的操作。若 SSL 错误消失后变成 401、403 或 429，则继续处理认证、访问权限或限流，不能把新错误仍算成证书问题。

不建议把 NODE_TLS_REJECT_UNAUTHORIZED=0、strict-ssl=false、curl -k 或关闭安全软件作为修复步骤。它们绕过检查或改变安全边界，没有修复错误的证书链、域名或代理协议。

## 十、总结

Claude Code 的 SSL 问题，核心是让实际发起请求的进程，使用正确的网络入口，并验证正确的证书链。缺少企业 CA 就补充可信 CA；代理协议或端口错误就修正入口；证书过期、域名不匹配或服务端链不完整，就处理对应服务；遇到已确认的版本缺陷，则更新受影响的应用或运行时。

保留证书校验，通过调试日志确认配置加载，再用实际请求验证结果，才能避免“报错暂时消失，配置却仍然不正确”的情况。

Claude Code 提示“Unable to connect to API”，后面跟着 Self-signed certificate detected、unable to get local issuer certificate 或 SSL certificate has expired，反复重试通常无法解决。需要处理的是报错对应的证书信任、证书链、代理配置或客户端版本问题。

Claude Code 提示 SSL 证书错误怎么办？证书、代理与版本问题逐项解决

Claude Code 出现 SSL 证书错误，可能涉及企业 CA、证书链、代理协议、客户端版本和配置加载范围。本文按报错类型给出 Windows、macOS、Linux 的检查步骤，说明 NODE_EXTRA_CA_CERTS 的配置方法，以及 CLI、桌面端和 VS Code 的验证方式。

开发工具

网络与通信

ClaudeCode API连接失败报SSL证书错误，需区分证书信任、代理配置或版本问题。企业CA不受信任时配置NODE_EXTRA_CA_CERTS指向PEM格式证书；代理需核对协议、端口及大小写变量；证书过期或域名不匹配应修正服务端配置。注意CLI、桌面端、扩展使用不同入口，更新需分别处理。通过claude --debug验证加载，执行最小请求确认解决。

热销域名限时优惠，新客首年免费！


domain

腾讯云双十一大促

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

ClaudeCode API连接失败报SSL证书错误，需区分证书信任、代理配置或版本问题。企业CA不受信任时配置NODE_EXTRA_CA_CERTS指向PEM格式证书；代理需核对协议、端口及大小写变量；证书过期或域名不匹配应修正服务端配置。注意CLI、桌面端、扩展使用不同入口，更新需分别处理。通过claude --d...

Claude Code 提示 SSL 证书错误怎么办？证书、代理与版本问题逐项解决-腾讯云开发者社区-腾讯云

Claude Code 提示 SSL 证书错误怎么办？证书、代理与版本问题逐项解决

Claude Code 提示 SSL 证书错误怎么办？证书、代理与版本问题逐项解决

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐