修复 Mac 终端 CLI 与 AI 工具中的 SWG TLS/SSL 证书错误
排查并修复 macOS 在企业 SWG 环境下 git、npm、Python、Claude Code 和 Cursor 出现的 CERTIFICATE_VERIFY_FAILED 与本地签发者证书错误。
SWG bar · 更新日期
当公司 Mac 处于执行 **HTTPS/SSL 解密检查(Break-and-Inspect)**的安全 Web 网关(SWG)之后时,Safari 和 Chrome 往往能毫无警告地打开网页,但终端工具和 AI 编程助手却会因 TLS 握手失败而报错,常见错误包括 SSL: CERTIFICATE_VERIFY_FAILED、UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 SSL certificate problem: unable to get local issuer certificate。
出现这种差异的原因在于:浏览器会读取 macOS 钥匙串(Keychain)——企业 MDM 可以在其中安装检查根证书(Root CA);而许多命令行运行时(git、curl、Node.js/npm、Python/pip)以及 AI 工具(Claude Code、Cursor、MCP 服务器)则默认使用各自内置的公共 CA 证书库来校验服务器证书。
1. 确认是哪个主机名正在接受 HTTPS 检查
在修改环境变量或网络设置之前,请先确认报错端点的证书链在你的 Mac 上是否确实被替换:
- 在运行 macOS 14 或更高版本(Apple 芯片)的 Mac 上安装并打开 SWG bar。
- 运行一次报错的命令,然后查看 SWG bar → 域名,或者直接使用内置 CLI 在终端中探测目标端点:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
- 检查该域名的分类和根证书(Root CA)。请注意,Web 前端、身份认证服务器、包管理器仓库和大模型 API 端点通常使用不同的主机名——某个子域名可能直通放行,而另一个子域名仍在被解密。
如果你使用兼容 MCP 的 AI 助手,还可以连接 SWG bar 内置的 MCP 服务器,让 AI 客户端直接查询已观测域名和证书链详情。
2. 选择适合当前环境的修复方案
确认目标主机名的证书由检查根证书签发后,请根据所在网络的安全策略与授权范围,从以下三种方案中选择其一:
| 方案 | 工作机制 | 适用场景 |
|---|---|---|
| 为工具配置自定义 CA 信任 | 将运行时的证书环境变量(如 NODE_EXTRA_CA_CERTS、SSL_CERT_FILE 或 REQUESTS_CA_BUNDLE)指向包含企业根证书的导出 PEM 证书包。 |
企业策略要求流量必须经过 SWG 检查,且你信任该 CA 用于对应工具。 |
| 申请管理员配置 TLS 解密例外 | 由 IT 在网关上将该 API 或软件源主机名排除在 HTTPS 解密之外,同时保留网关路由。 | 启用证书固定的工具或团队共用的研发端点在 Break-and-Inspect 下无法工作。 |
| 在 SWG bar 中开启单域名 SWG 绕过 | 通过菜单栏、CLI 或 MCP 在 macOS 上为所选主机名建立不经网关 HTTPS 解密的路由。 | 你管理该网络,或已获授权在 Mac 上针对特定域名测试未受检查的连接路径。 |
如需详细对比网关解密例外与本地路由变更的架构差异,请阅读SWG 绕过与 TLS 解密例外对比。
3. 在获授权时于 macOS 上绕过受检域名
如果单域名绕过符合你的网络使用规范,可以从菜单栏(SWG bar → 域名 → 绕过 SWG → 开启)或在终端中为具体的 API 或包仓库主机名启用绕过:
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status
等待状态显示为 绕过中(CLI 输出 bypassing)后,重启对应的 CLI 命令、后台守护进程或 IDE 扩展宿主进程,使已有连接关闭并按新规则重新建立连接。首次使用时的 macOS 网络扩展授权、重启恢复行为以及使用完毕后关闭绕过的方法,请参阅如何在 Mac 上绕过 SWG。
注意平台与网络边界
- 按主机名精确生效:绕过
example.com不会自动包含api.example.com或auth.example.com,请逐一核对工具实际访问的每个主机名。 - 平台与网络要求:SWG bar 2.4.12 需要运行 macOS 14+ 的 Apple 芯片 Mac,以及通过物理网络接口建立的可用 IPv4 路径。如果防火墙阻断直接出站连接,或工具自身强制配置了显式代理,请关闭绕过规则,改用管理员 TLS 例外或配置 CA 证书包。
- 使用最新证据验证:每次调整后,请按照 HTTPS 与 SSL 检查检测指南重新发起检测,不要依赖缓存的旧结果。