Mac 上的“Unable to connect to API: SSL certificate verification failed”

证书来自 Claude Code 不信任的机构时,它会打印这条消息。文档提到的情形有:检查 TLS 的企业代理,或使用私有 CA 的网关。

让你的智能体来解决拷贝一条提示词,适用于 Claude Code、Codex 或任何能使用终端的智能体。

我的 Mac 出现了这个问题:Mac 上的“Unable to connect to API: SSL certificate verification failed”。请阅读 https://kilobat.app/zh-hans/guides/claude-code-ssl-certificate-verification-failed.md,并和我一起逐步处理。如果缺少 Kilobat CLI,请安装:brew install seifip/kilobat/kilobat。请你自己运行指南中的终端和 kilobat 检查,并告诉我发现了什么。列出只有我才能完成的步骤。更改任何设置之前先问我。

适用于:所有当前 macOS 版本上终端里的 Claude Code。核查日期:2026年10月29日

症状

  • Claude Code 打印 Unable to connect to API: SSL certificate verification failed。
  • 代码是 UNABLE_TO_GET_ISSUER_CERT_LOCALLY,或者文字中提到 self-signed certificate。
  • 从连上工作网络时开始出现。

可能的原因

  • 检查 TLS 的代理。代理或安全设备用自己的证书拦截 TLS 流量。
  • 使用私有 CA 的网关。LLM 网关可能使用私有机构签发的证书。
  • 无法加载的 CA 文件。Claude Code 读不到 NODE_EXTRA_CA_CERTS 指定的文件时会给出警告。
  • 时钟不对。日期偏差很大会导致证书检查失败。

如何检查

  1. 查看签发者。

    curl -v -o /dev/null https://api.anthropic.com 2>&1 | grep -i issuer
  2. 显示这个变量。

    echo $NODE_EXTRA_CA_CERTS
  3. 用调试日志启动 Claude Code,然后查看日志中的 CA 行。

    claude --debug
  4. 检查日期。

    date

如何修复

  1. 向管理员索取 PEM 格式的 CA 证书包。

  2. 启动前让 Claude Code 指向它。

    export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
  3. 或者按文档所述,把这个 CA 添加到 macOS 系统证书存储中。

  4. 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0。它会关闭验证。

使用 Kilobat

  1. Kilobat 的连接诊断会逐层测试 API 主机。TLS 层会显示证书是由谁签发的。

    kilobat why https://api.anthropic.com
  2. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 diagnose_connection 和 diagnose_network 运行它们。请参阅找出某个网站或 API 连不上的原因。

常见问题

Claude Code 会使用 macOS 的证书存储吗?

默认情况下,它信任自带的 Mozilla CA 和操作系统的证书存储。原生安装版始终会读取系统证书存储。

可以关闭验证吗?

文档说明不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0。

参考资料

核查日期:2026 年 10 月 29 日。