公司网里 Claude Code 报 SSL 证书错误怎么解决？以及为什么别关证书校验

2026-08-08

在公司电脑上装好 Claude Code，第一次跑就连不上，报的是证书相关的错：

SSL certificate verification failed

搜一圈，最容易搜到的「解法」是设一个环境变量把证书校验关掉。那条千万别用——官方文档在这条报错的处理里专门写了一句不要这么做。

这篇讲正确的做法，以及企业网环境下一整套连接类问题的排查顺序。

一、成因：中间有个设备在拆你的 TLS

官方说明的成因是：代理或安全设备用它自己的证书拦截了 TLS 流量。

这在企业网里很常见。为了做内容审计、数据防泄漏、恶意流量检测，网络设备会把 HTTPS 连接拆开看一眼再重新加密。代价是证书链变了——你的客户端拿到的不是目标网站的证书，而是那台设备签发的。

操作系统层面通常已经装好了企业的根证书（所以浏览器不报错），但 Node.js 默认不读操作系统的证书库，于是跑在 Node 上的工具就会报证书校验失败。

二、官方给的做法

官方对 SSL certificate verification failed / SSL certificate error 给的处理是：

导出组织的 CA 包，设到 NODE_EXTRA_CA_CERTS：

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

然后官方紧跟着写了一句：

不要设 NODE_TLS_REJECT_UNAUTHORIZED=0

以及：运行 claude doctor 获取详情。

那个证书文件从哪来

NODE_EXTRA_CA_CERTS 要的是企业根证书文件的绝对路径。拿到它的途径通常是：

问 IT——这是最快也最靠谱的一条。企业根证书通常有标准的分发方式
从系统证书库里导出（不同系统的操作不同，本文不逐一展开，因为各家环境差异很大）

建议直接走第一条。 IT 那边一般有现成的文件和说明，比自己摸索快得多，也不容易导出个不完整的。

为什么不能关证书校验

NODE_TLS_REJECT_UNAUTHORIZED=0 的作用是让 Node 完全不校验证书。设了它确实「能连上了」，但代价是：

你从此接受任何证书。 校验存在的意义就是确认对面是不是它声称的那个。关掉之后，你没法区分「公司的合规审计设备」和「其他任何拦在中间的东西」。

而且这个变量往往被设在 shell 配置里长期生效，影响的不止 Claude Code，是这台机器上所有跑在 Node 上的东西。

一句话：它不是修，是把门拆了。

顺带一提，Gemini CLI 官方文档对同类问题给的第一条建议是先试 NODE_USE_SYSTEM_CA=1（让 Node 直接用操作系统的证书库）。两边的工具都跑在 Node 上，遇到证书问题时，这个思路是通用的——优先让 Node 去信任系统已经信任的东西，而不是关掉校验。

三、企业网里还有几条会撞

证书只是企业网环境下的一条。官方错误参考里跟企业网络相关的还有几条，一起看能少走弯路：

`Unable to connect to API`

成因：TCP 连接失败。官方处理：

先确认连通性：
```
curl -I https://api.anthropic.com
```
Windows PowerShell 要用 curl.exe（PowerShell 里 curl 是别名，行为不一样）
在企业代理后面：设 HTTPS_PROXY
用 LLM 网关：设 ANTHROPIC_BASE_URL
确认防火墙放行了官方网络访问要求里列的主机
Linux / WSL：检查 /etc/resolv.conf 里的 nameserver
macOS：检查 ifconfig 输出里的 VPN 网络扩展

第一步是分界线：curl 通了说明网络层没问题，往下查代理和配置；curl 也不通，就先解决网络本身，别在 Claude Code 的配置里折腾。

`Unable to connect to Anthropic services`

这条发生在首次运行设置期间的连接检查。官方处理：

报错提到代理的话，确认代理值，并请网络团队放行
参考上面那条的排查
如果网络确实是通的但一直失败，官方给了一个可能性：Claude Code 可能在你的国家/地区不可用

最后一条值得单独说：这是一个需要单独确认的方向，而不是配置问题。 本文不对可用性范围做任何判断——需要确认请以官方说明为准。

`Extra inputs are not permitted`

成因：代理或 LLM 网关把 anthropic-beta 请求头剥掉了。

处理：让网关转发这个头；或者设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

这条很典型——报错文本一点都看不出跟网关有关，但真因是中间设备改了请求。企业网里遇到看不懂的参数类报错，值得往这个方向想一下。

`Bedrock streaming response has an unexpected content-type`

成因：网关或代理改动了流式响应体或它的 Content-Type 头。

处理：配置网关原样透传 InvokeModelWithResponseStream 的响应体和 Content-Type 头；如果网关只是重写了头、二进制体是原样过的，可以设 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1。

`403 with x-deny-reason: host_not_allowed`

这条是云会话里的出站请求被网络策略拦了。官方给的是一套界面操作：打开例程编辑或启动云会话 → 点显示环境名的云图标 → 在「更新云环境」对话框里把网络访问从信任改成自定义 → 把被拦的域名加进允许的域（每行一个）→ 勾上也包括默认的通用包管理器列表以保留默认允许项 → 保存。

四、企业网排查顺序

把上面这些串成一条：

claude doctor —— 官方在证书那条里直接推荐了它，它会给出详情
curl -I https://api.anthropic.com —— 划清是网络层还是应用层（Windows 用 curl.exe）
报错提到证书 → 配 NODE_EXTRA_CA_CERTS 指向企业 CA 包（不要关校验）
报错提到连不上 → 设 HTTPS_PROXY；Linux/WSL 查 /etc/resolv.conf，macOS 查 VPN 网络扩展
走网关 → 设 ANTHROPIC_BASE_URL；确认网关透传 anthropic-beta 头
参数类报错看不懂 → 想想是不是中间设备改了请求
仍不行 → 把官方网络访问要求的主机清单给网络团队，让他们放行

第 2 步的分界作用最大。很多时间是花在「明明是网络不通，却在改工具配置」上的。

五、走 LLM 网关的话，有三件事要一起配

企业里常见的做法是不让客户端直连，统一走一个 LLM 网关。这种架构下，除了证书，还有几件事必须一起配好，否则会撞上一串看起来毫不相干的报错。

第一，ANTHROPIC_BASE_URL 指向网关。 这是官方在 Unable to connect to API 里给的做法。

第二，网关必须透传 anthropic-beta 请求头。 剥掉的话会报 Extra inputs are not permitted——这个报错文本完全看不出跟网关有关，很容易被当成参数写错。实在改不了网关，可以设 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

第三，凭证由网关那边定。 官方在 API Error: 401 的处理里写了：如果用的是 LLM 网关，那就去修网关期望的那套凭证。你本地的 key 对不对，跟网关认不认是两回事。

还有一个副作用要知道：配了 ANTHROPIC_BASE_URL 之后，远程控制功能用不了。 官方对 Remote Control requires the Anthropic API 给的处理就是 unset ANTHROPIC_BASE_URL 再重启会话——因为那个功能要求会话直接跟 Anthropic API 通信。这不是故障，是链路要求，别为了它去反复调网关。

如果走的是 Amazon Bedrock 且中间有网关，还要注意流式响应：网关如果改动了响应体或 Content-Type 头，会报 Bedrock streaming response has an unexpected content-type。官方处理是让网关原样透传 InvokeModelWithResponseStream 的响应体和头；如果网关只改了头、二进制体是完整的，可以设 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1。

把这几条放在一起看会发现一个共同点：企业网里的报错，文本往往指向应用层，真因在中间设备。 记住这个规律，比记住每一条报错都有用。

六、总结

证书报错的成因是企业设备拦截 TLS，操作系统信任了那张证书，但 Node 默认不读系统证书库。
官方做法是 NODE_EXTRA_CA_CERTS 指向企业 CA 包；证书文件直接问 IT 最快。
官方明确写了不要设 NODE_TLS_REJECT_UNAUTHORIZED=0——那不是修，是把校验关了，而且影响这台机器上所有 Node 程序。
企业网里还有一族相关报错：连不上、网关剥请求头、Bedrock 响应头被改、云会话出站被拦，它们的报错文本都看不出跟网络设备有关。
排查先跑 claude doctor 和 curl -I，划清网络层和应用层再动手。

本文所引官方内容来自 Claude Code 官方错误参考文档，另引用了 Gemini CLI 官方 troubleshooting 中对同类证书问题的处理思路，核对日 2026-08-08。企业网络环境差异很大，具体配置请与所在组织的网络团队确认。