Claude Code SSL 证书报错：5 个真正管用的修复方案（2026）

在家用得好好的 Claude Code，一到公司就被一堵 TLS 报错墙拦住：SELF_SIGNED_CERT_IN_CHAIN、unable to get local issuer certificate，或者干脆一句 Self-signed certificate detected。你的安装并没有问题。是公司的网络在打开每一条 HTTPS 连接、重新签名，而 Claude Code 认不出这个新签名。

修复方案几乎从来都不是关闭证书校验，而是教会 Claude Code 去信任公司额外添加的那一张证书。本文按你应当尝试的顺序，讲清楚做到这一点的五种方法，加上与之配套的代理设置，以及那个会悄悄把你的 API key 交给线路上任何人的「修复」。

30 秒快速诊断

先看错误字符串。它会告诉你哪一层出了问题，而每一种都对应下文的一个具体修复。

有一个测试能在十秒内锁定原因。在没有检查代理的网络上运行 Claude Code——手机热点就行——或者让 IT 对 api.anthropic.com 加一条绕行规则。如果它在那里能连、在公司网络下失败，那就是代理在重新签发你的流量，你需要的是 CA 修复，而不是重装。

修复它还是绕开它：各自适用的场景

在动配置文件之前，先弄清楚你到底遇到的是哪种问题。下面的证书修复假设你能拿到公司的 CA 并设置环境变量。这并不总能成立，硬来只会浪费一下午。

何时添加 CA（多数情况）

• 你能掌控这台机器，能设置环境变量或编辑 ~/.claude/settings.json。
• IT 能给你根 CA 文件，或者它已经装进了你的 OS 信任库。
• 代理使用的是普通透传或基本认证。

何时改为经网关路由

• 代理要求 NTLM 或 Kerberos 认证。Claude Code 两者都不支持，导入任何 CA 都改变不了这一点。
• 你拿不到公司 CA，而 IT 又不肯把 Anthropic 的域名加进白名单。
• 你需要为整个团队提供一个带自有 TLS 终止的统一出口点，于是逐个开发者去折腾 CA 已经不值当了。

停手判据

如果 Claude Code 在直连网络下能用，只在公司代理背后出问题，那这就是信任问题，没别的了。不要重装，不要盲目切换 Node 版本，也别为「二进制损坏」去开工单。直接跳到修复 1。如果它在干净网络下也失败，那原因是别的（DNS、区域封锁、订阅过期），本文的证书修复帮不上忙。

Claude Code 为什么拒绝这张证书

大多数公司网络都跑着 TLS 检查代理：Zscaler、Netskope、Cato、CrowdStrike Falcon，或者一个做同样事情的全隧道 VPN。这个盒子的存在是为了读取出站 HTTPS，用于数据防泄漏和恶意软件扫描。要读取加密流，它必须坐在中间：它终止你到 api.anthropic.com 的连接，解密，然后自己再向前建立连接，并用公司的私有证书颁发机构对响应重新签名。

你的浏览器信任这张重新签发的证书，是因为 IT 在配置笔记本时就把公司根 CA 推进了浏览器和 OS 的信任库。而 Claude Code 是一个独立的运行时，对「该信任什么」有自己的一套判断——错配就出在这里。

flowchart LR
    A[Claude Code] -->|HTTPS| B[TLS-inspection proxy]
    B -->|decrypts, re-signs<br/>with corporate CA| C[api.anthropic.com]
    C -->|real Anthropic cert| B
    B -->|re-signed cert| A
    A -->|corporate CA<br/>not in trust store| D[SELF_SIGNED_CERT_IN_CHAIN]

下面这点是多数攻略搞错的地方。现代版本的 Claude Code 其实已经会读取你的 OS 信任库了。默认情况下它同时信任内置的 Mozilla CA 集和操作系统的证书库。读取 OS 库需要一个暴露 tls.getCACertificates 的运行时：原生安装器始终具备，npm 安装则需要 Node 22.15 或更高。在更旧的 Node 上，只有内置集和 NODE_EXTRA_CA_CERTS 生效。所以当 IT 已经把公司根证书装进 OS 库、而你又用的是较新的构建时，像 Zscaler 和 CrowdStrike Falcon 这样的检查代理完全不用额外配置就能正常工作。错误只出现在那些缺口上：老旧的 npm 安装、从没进过 OS 库的 CA，或者以某种方式启动、跳过了它的运行时。

读懂 SSL 错误：字符串与影响范围

准确的字符串能缩小原因范围。这和 Node 与 OpenSSL 用的是同一套分类，所以无论 Claude Code 跑在原生二进制还是 npm 安装上都适用。

这个区分很重要。每次 API 调用都出现的校验错误是信任库问题，用一个 CA 修一次就好。安装时出现的吊销错误是防火墙挡了查询，你只需针对那一条安装命令绕开它，而不必改动你的信任配置。

修复方案（按顺序）

自上而下地做。靠前的修复比靠后的更干净、风险更低。

修复 1：让 Claude Code 使用 OS 信任库

如果 IT 已经把公司 CA 放进了你的系统库（他们几乎总会这么做，因为浏览器需要它），最干净的修复就是确保 Claude Code 去读那个库，而不是跟它对着干。

在原生安装器上这是自动的。在 npm 安装上，确认你的 Node 是 22.15 或更新：

node --version

如果更旧，就升级 Node，或者切换到原生安装器——后者的信任从不依赖 Node 版本。CLAUDE_CODE_CERT_STORE 的默认值已经是 bundled,system，所以 Claude Code 开箱即读 OS 库。只有在有人把它强制改成了 bundled（这会去掉 OS 库）时你才需要碰这个变量；那种情况下把 system 加回去：

export CLAUDE_CODE_CERT_STORE=bundled,system

预期结果：Claude Code 会信任你的 OS 所信任的一切，包括公司根证书。单独强制 system 并不会添加默认值本就没有的任何信任，所以它救不了一个太旧、读不了 OS 库的运行时。如果 OS 库本身就缺这张 CA，那就该用修复 2。

修复 2：让 NODE_EXTRA_CA_CERTS 指向公司 CA

这是主力修复，也是 Anthropic 文档为 TLS 检查环境点名的那个。它在内置证书集之上追加你的公司根证书，而不替换任何东西。

先拿到 PEM 格式的 CA 文件。问 IT，或者自己导出：macOS 上打开钥匙串访问，把公司根证书导出为 .pem；Windows 上运行 certmgr.msc，打开「受信任的根证书颁发机构」，导出为 Base-64 编码的 X.509；Linux 上该文件通常已经位于 /usr/local/share/ca-certificates 或 /etc/pki/ca-trust 下。

然后让 Claude Code 指向它：

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

预期结果：API 调用成功，因为 Claude Code 现在信任代理重新签发的证书。把这条导出加进 ~/.zshrc 或 ~/.bashrc 使其永久生效。如果你的 CA bundle 里有多张证书（一张根加若干中间证书），把它们拼进一个 PEM 文件即可；NODE_EXTRA_CA_CERTS 会全部读取。

修复 3：单独修复安装步骤

安装和运行时是两条不同的网络调用，可以各自独立失败。如果 curl 在 Claude Code 还没装上就卡住了，那就去改安装命令，而不是你的 shell 配置。

让安装器的 curl 指向同一个 CA bundle：

curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash

在 Windows 上，如果你看到 schannel 安全通道错误，先强制使用 TLS 1.2：

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

如果 Windows 报告 CRYPT_E_NO_REVOCATION_CHECK 或 CRYPT_E_REVOCATION_OFFLINE，说明网络阻断了证书吊销查询，这在公司防火墙后很常见。只针对本次安装加上尽力而为的吊销检查：

curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

预期结果：二进制装上了。运行时的 API 调用仍受修复 1 或修复 2 管辖，所以那些也要一并设置。

修复 4：配置代理本身

有时证书没问题，只是代理没被用上。Claude Code 会读取标准的代理变量。对 API 流量而言起作用的是 HTTPS_PROXY：

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

NO_PROXY 接受以空格或逗号分隔的列表，* 会让所有连接都绕过代理。如果代理需要基本认证，把凭据放进 URL：

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

在你为之耗时之前，有两个限制值得先知道。Claude Code 不支持 SOCKS 代理。它也不处理 NTLM 或 Kerberos 代理认证——而这正是下一节要讲的场景。

修复 5：mTLS 与客户端证书环境

有些企业不仅要求可信的服务器证书，还要求客户端证书。Claude Code 通过三个变量支持双向 TLS：

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

预期结果：Claude Code 会在握手期间出示客户端证书，满足那些按证书（而非按请求头）来认证调用方的代理或网关。

反面修复：绝不要关闭校验

你会在论坛上看到有人推荐 NODE_TLS_REJECT_UNAUTHORIZED=0。它让错误消失，是因为它告诉 Node 接受任何人给的任何证书。这也包括坐在同一间咖啡馆网络里的攻击者——他现在能读取你每次请求以明文发送的 API key。这是你绝不该提交的一行。添加 CA 会保持校验开启，且只信任你选定的证书；关闭校验则是信任一切。两者不可同日而语。

完整演练：macOS 上的 Zscaler

抽象的步骤容易做错，所以这里针对最常见的配置——Zscaler 背后的一台 Mac——把整个流程从头走一遍。大约五分钟。

首先，确认真的是代理问题。连上你的手机热点，运行 claude。如果它在那里能连，说明公司网络在做拦截，你继续往下走。

从钥匙串导出 Zscaler 根证书。打开钥匙串访问，搜索公司根证书（通常名为 Zscaler Root CA），选中它，用「文件」→「导出项目」将其保存为 home 目录下的 zscaler-root.pem。如果它导出成 .cer，就转换一下：

openssl x509 -inform der -in zscaler-root.cer -out zscaler-root.pem

让 Claude Code 指向它，并让设置持久生效：

echo 'export NODE_EXTRA_CA_CERTS="$HOME/zscaler-root.pem"' >> ~/.zshrc
source ~/.zshrc

开一个新的终端，让这条导出加载进来，然后启动 claude。SSL 错误消失了。

验证修复确实生效

不要相信「看起来好使」。确认 Claude Code 和你的 shell 对证书达成一致。下面这条单行命令用同一个 CA 走一次请求，应当打印出证书链和 SSL certificate verify ok：

curl --cacert "$NODE_EXTRA_CA_CERTS" -svo /dev/null https://api.anthropic.com 2>&1 | grep -E "issuer|verify"

如果 curl 用那个 bundle 校验通过，但 claude 仍然失败，说明变量没有传到 Claude Code 的进程。那是下面要讲的 shell 与 settings.json 的落差，而不是证书问题。

Docker、CI Runner 与远程开发

容器是这个错误在你以为已经解决之后又冒出来的地方，因为一个全新的容器不会继承你笔记本的 OS 信任库。你的宿主机信任公司 CA；Docker 里的 Ubuntu 基础镜像不信任。

把 CA 烤进镜像，并同时在 OS 库和 Node 变量里注册它：

COPY corporate-ca.pem /usr/local/share/ca-certificates/corporate-ca.crt
RUN update-ca-certificates
ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corporate-ca.crt

同样的逻辑适用于 CI runner 和远程开发机：一个位于同一代理背后的 GitHub Actions 或 GitLab runner，需要 CA 出现在作业环境中，通常是作为一个 secret 文件在作业开始时写入，并在任何 claude 步骤之前导出 NODE_EXTRA_CA_CERTS。Devcontainer 需要在其 Dockerfile 中加上面那行 ENV。如果你只改了自己的 shell 配置，容器从来没见过它。

settings.json 与 shell

上文的每个变量都可以放进 ~/.claude/settings.json 的 env 块——对于一台只配置一次的机器，这是更整洁的选择：

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/path/to/corporate-ca.pem",
    "HTTPS_PROXY": "https://proxy.example.com:8080"
  }
}

有一点值得直说。某些较早的版本在 NODE_EXTRA_CA_CERTS 只设于 settings.json 时会忽略它，而桌面应用也不总会把它传给它派生的 CLI 子进程。这两点都作为已跟踪的 GitHub issue 出现过。如果 settings.json 里的值不起作用，可靠的退路是在你的配置里做 shell 导出——每个构建都认它，因为 Node 在 Claude Code 启动之前就会读取它。

常见相关错误（及修复）

这些错误常和证书错误相邻出现，容易被误认成一回事。

最后一行是那个不显眼的。如果 claude 在你的终端里能用，而 VS Code 或 JetBrains 面板抛出 SSL 错误，那是编辑器从程序坞启动的，从没见过你的 .zshrc。要么在 IDE 自己的环境里设置这些变量，要么从一个已经导出了它们的 shell 里启动编辑器。

当代理不肯让步：经网关路由

如果代理要求 NTLM 或 Kerberos，或者你干脆拿不到 CA，那么添加证书是条死路。Anthropic 自家的网络指南也是这么说的：对于需要高级认证的代理，在前面放一个会说那套认证方案的 LLM 网关。网关终止它自己的 TLS，一次性搞定那套麻烦的代理协商，于是每个开发者都指向同一个端点，而不必各自跟自己的信任库较劲。

ofox 就是这样一个东西：一个兼容 OpenAI 和 Anthropic 的网关，地址是 https://api.ofox.ai。把 Claude Code 指向一个自定义端点只是一行改动，跟我们的 Claude Code 端点切换教程 里讲的是同一个替换。设置两个变量：

export ANTHROPIC_BASE_URL=https://api.ofox.ai/anthropic
export ANTHROPIC_API_KEY=sk-ofox-...

对它能解决什么、不能解决什么要诚实。公司代理仍然会重新签发到 api.ofox.ai 的流量，所以为了这个网关主机，你可能仍需要把公司 CA 放进信任库。网关为你换来的是：整个团队一个出口端点、横跨 Claude、GPT 和 Gemini 的统一账单视图，以及当某个上游不可达时的内建降级。关于完整的 base-URL 替换和模型路由，见我们的指南 为 Cursor、Claude Code 和 Cline 设置自定义 API；接上之后的成本控制，见 Claude Code 混合路由模式。如果你还在权衡是否彻底离开 Claude Code，同样的信任规则也适用于我们的 Claude Code 迁移到 Codex 指南。

网关是逃生舱口，不是默认选项。当你能拿到 CA 时，修复 1 或修复 2 更简单，也让你留在直连路径上。

常见问题

怎么修复 Claude Code 里的 SELF_SIGNED_CERT_IN_CHAIN？ 一个 TLS 检查代理用你不信任的 CA 重新签发了连接。把那张 CA 装进 OS 信任库（原生安装器和 Node 22.15+ 会自动读取），或者让 NODE_EXTRA_CA_CERTS 指向 CA bundle。不要关闭校验。

NODE_EXTRA_CA_CERTS 是什么，该指向哪里？ 一个 Node 变量，在内置证书集之上追加可信证书。把它指向 PEM 格式的公司根证书：export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem。在 shell 里或在 settings.json 里设置。

Claude Code 会读取 Windows 或 macOS 的证书库吗？ 会，默认情况下它信任内置的 Mozilla 集加上 OS 库。读取 OS 库需要原生安装器或 Node 22.15+；更旧的 Node 只用内置集和 NODE_EXTRA_CA_CERTS。

NODE_TLS_REJECT_UNAUTHORIZED=0 安全吗？ 不安全。它会对每个请求关闭证书校验，把你的 API key 暴露给路径上的任何人。应改为添加 CA。

为什么 curl 正常，Claude Code 却报 SSL 错误？ 它们读的是不同的信任库。系统 curl 通常已经信任公司 CA；Claude Code 的运行时可能不信任，或者 npm 安装用的 Node 比 22.15 更旧。让 NODE_EXTRA_CA_CERTS 指向同一个 CA，或改用原生安装器或 Node 22.15+ 让它读取 OS 库。（CLAUDE_CODE_CERT_STORE 默认就是 bundled,system，所以强制 system 毫无作用。）

我能在 settings.json 里设置 NODE_EXTRA_CA_CERTS 吗？ 可以，在 env 块里。有些旧版本只认 shell 导出，所以如果 settings.json 不起作用，就在你的 shell 配置里导出它。

Claude Code 支持 SOCKS 或 NTLM 代理吗？ 不支持 SOCKS，也不直接支持 NTLM 或 Kerberos 认证。它读取 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY，基本认证以 URL 中的 user:password 形式提供。对于 NTLM 或 Kerberos，在它前面放一个网关。

怎么拿到公司的 CA 证书文件？ 向 IT 索要 PEM 格式的根 CA，或者自己导出：从钥匙串访问（macOS）、certmgr.msc（Windows，Base-64 X.509），或 /usr/local/share/ca-certificates（Linux）。

本次更新核对的来源

• Claude Code: Troubleshoot installation and login，核对于 2026-07-03。TLS/SSL 错误字符串、--cacert 安装修复、Windows TLS 1.2 与 --ssl-revoke-best-effort，以及 HTTPS_PROXY 安装期设置的来源。
• Claude Code: Enterprise network configuration，核对于 2026-07-03。NODE_EXTRA_CA_CERTS、CLAUDE_CODE_CERT_STORE、内置加 OS 的信任模型与 Node 22.15 门槛、HTTP_PROXY/HTTPS_PROXY/NO_PROXY、基本认证代理 URL、不支持 SOCKS 的限制，以及 mTLS 变量的来源。
• anthropics/claude-code issue #22512，核对于 2026-07-03。证实了在 settings.json 中设置的 NODE_EXTRA_CA_CERTS 不被遵守的情形，正是它促成了 shell 导出这一退路。
• Node.js 关于 NODE_EXTRA_CA_CERTS 行为与 PEM bundle 处理的 TLS 文档，核对于 2026-07-03。