Unable to connect to API: Self-signed certificate detected (DEPTH_ZERO_SELF_SIGN...

原文：API Error: Unable to connect to API: Self-signed certificate detected (DEPTH_ZERO_SELF_SIGNED_CERT). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store
译文：API 错误：无法连接到 API：检测到自签名证书 (DEPTH_ZERO_SELF_SIGNED_CERT)。该证书来自 Claude Code 不信任的机构，通常是 TLS 检查型企业代理或由私有 CA 签署的网关：设置 NODE_EXTRA_CA_CERTS 指向该 CA 证书包，或将其添加到系统证书存储中

错误原因

Claude Code 在建立 API 连接时，遇到了服务器端使用自签名证书或私有 CA 签发证书的情况。系统默认的安全策略不信任此类证书，因此抛出 DEPTH_ZERO_SELF_SIGNED_CERT 异常，导致连接被拒绝。常见于企业内网代理或私有网关环境。

解决方案

方案一：设置环境变量指向 CA 证书包

将私有 CA 的证书文件路径通过 NODE_EXTRA_CA_CERTS 传递给 Node.js 进程：

# Linux / macOS
export NODE_EXTRA_CA_CERTS=/path/to/your/private-ca-bundle.crt

# Windows (PowerShell)
$env:NODE_EXTRA_CA_CERTS="C:\path\to\your\private-ca-bundle.crt"

方案二：将 CA 证书安装到系统证书存储

Linux (Ubuntu/Debian):

sudo cp private-ca-bundle.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

macOS:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain private-ca-bundle.crt

Windows:
将 .crt 文件导入「受信任的根证书颁发机构」存储区。

预防措施

• 🔐 统一证书管理：企业环境建议统一部署内部 PKI，避免在多个节点重复处理证书信任问题


• 🔍 定期审计：使用 openssl s_client -connect <host>:<port> -showcerts 验证证书链完整性，提前发现不合规证书