Source: https://swgbar.com/zh-CN/guides/swg-tls-certificate-errors-macos/
Language: zh-CN

# 修复 Mac 终端 CLI 与 AI 工具中的 SWG TLS/SSL 证书错误

排查并修复 macOS 在企业 SWG 环境下 git、npm、Python、Claude Code 和 Cursor 出现的 CERTIFICATE\_VERIFY\_FAILED 与本地签发者证书错误。

SWG bar · 更新日期 2026年11月18日

当公司 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 上是否确实被替换：

1.  在运行 macOS 14 或更高版本（Apple 芯片）的 Mac 上[安装并打开 SWG bar](<https://swgbar.com/zh-CN/install/>)。
2.  运行一次报错的命令，然后查看 **SWG bar → 域名**，或者直接使用内置 [CLI](<https://swgbar.com/zh-CN/cli/>) 在终端中探测目标端点：

```
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
```

3.  检查该域名的分类和根证书（Root CA）。请注意，Web 前端、身份认证服务器、包管理器仓库和大模型 API 端点通常使用不同的主机名——某个子域名可能直通放行，而另一个子域名仍在被解密。

如果你使用兼容 MCP 的 AI 助手，还可以连接 [SWG bar 内置的 MCP 服务器](<https://swgbar.com/zh-CN/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 解密例外对比](<https://swgbar.com/zh-CN/guides/swg-bypass-vs-tls-exception/>)。

## 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](<https://swgbar.com/zh-CN/guides/how-to-bypass-swg/>)。

## 注意平台与网络边界

*   **按主机名精确生效**：绕过 `example.com` 不会自动包含 `api.example.com` 或 `auth.example.com`，请逐一核对工具实际访问的每个主机名。
*   **平台与网络要求**：SWG bar 2.4.12 需要运行 macOS 14+ 的 Apple 芯片 Mac，以及通过物理网络接口建立的可用 IPv4 路径。如果防火墙阻断直接出站连接，或工具自身强制配置了显式代理，请关闭绕过规则，改用管理员 TLS 例外或配置 CA 证书包。
*   **使用最新证据验证**：每次调整后，请按照 [HTTPS 与 SSL 检查检测指南](<https://swgbar.com/zh-CN/guides/detect-https-inspection/>)重新发起检测，不要依赖缓存的旧结果。

## 继续阅读

*   [如何在 Mac 上绕过 SWG（单域名一键绕过与 CLI 命令）](<https://swgbar.com/zh-CN/guides/how-to-bypass-swg/>)
*   [如何在 Mac 上绕过 SSL 检查（企业 SWG 单域名绕过指南）](<https://swgbar.com/zh-CN/guides/bypass-ssl-inspection-mac/>)
*   [如何在 macOS 上绕过 HTTPS 与 TLS 检查（Break-and-Inspect 指南）](<https://swgbar.com/zh-CN/guides/bypass-https-tls-inspection-mac/>)
*   [如何在 Mac 上绕过企业代理与 SWG SSL 检查](<https://swgbar.com/zh-CN/guides/bypass-corporate-proxy-ssl-inspection-mac/>)
*   [如何判断我的电脑是否被 SWG 劫持（Mac 上检测 HTTPS/SSL 检查）](<https://swgbar.com/zh-CN/guides/detect-https-inspection/>)
*   [如何检查公司或办公 Mac 是否正在拦截 HTTPS（SSL 检查排查）](<https://swgbar.com/zh-CN/guides/check-if-work-mac-intercepting-https/>)
*   [Mac SSL 检查检测工具：菜单栏实时侦测 HTTPS 拦截](<https://swgbar.com/zh-CN/guides/ssl-inspection-checker-mac/>)
*   [Mac 上的 Zscaler SSL 检查：如何检测并按域名绕过](<https://swgbar.com/zh-CN/guides/zscaler-ssl-inspection-bypass-mac/>)
*   [Mac 上的 Netskope SSL 检查：检测解密与单域名绕过指南](<https://swgbar.com/zh-CN/guides/netskope-ssl-inspection-bypass-mac/>)
*   [Mac 上的 Cloudflare WARP 与 Zero Trust TLS 检查：检测与绕过](<https://swgbar.com/zh-CN/guides/cloudflare-warp-tls-inspection-mac/>)
*   [SWG bar 中的“已确认”与“疑似”HTTPS 检查状态解析](<https://swgbar.com/zh-CN/guides/confirmed-vs-suspected-https-inspection/>)
*   [在 SWG bar 中检查中间人根证书与签发机构](<https://swgbar.com/zh-CN/guides/inspect-mitm-root-certificates-macos/>)
*   [Mac 上的企业 SWG 与 MDM HTTPS 解密检查解析](<https://swgbar.com/zh-CN/guides/enterprise-swg-https-inspection-macos/>)
*   [SWG 绕过与 TLS 解密例外（Break-and-Inspect）对比](<https://swgbar.com/zh-CN/guides/swg-bypass-vs-tls-exception/>)
*   [在 Mac 上为多域名 Web 应用、SSO、CDN 与 API 配置 SWG 绕过](<https://swgbar.com/zh-CN/guides/multi-domain-sso-api-cdn-swg-bypass/>)
*   [排查 Mac 上 SWG 绕过的“恢复中”“已暂停”与连接错误](<https://swgbar.com/zh-CN/guides/troubleshoot-swg-bypass-recovering-paused-macos/>)
*   [macOS VPN 虚拟网卡与 SWG HTTPS 检查对比](<https://swgbar.com/zh-CN/guides/macos-vpn-virtual-interface-vs-swg-inspection/>)
*   [为什么证书固定（Pinning）应用与 mTLS 在 SWG 检查下会失效](<https://swgbar.com/zh-CN/guides/certificate-pinning-mtls-swg-inspection-macos/>)
*   [Mac 在 SWG 下的 Homebrew、Docker、Python 与 Node.js CA 信任配置](<https://swgbar.com/zh-CN/guides/homebrew-docker-python-node-ca-trust-swg-macos/>)
*   [修复 Mac 上 Claude Code 与 Cursor 的 'unable to get local issuer certificate' 报错（SWG 与 MCP）](<https://swgbar.com/zh-CN/guides/ai-coding-agents-claude-code-cursor-swg-macos/>)
*   [在 Mac 上使用 openssl 与 security verify-cert 验证 TLS 证书](<https://swgbar.com/zh-CN/guides/verify-tls-certificates-openssl-security-verify-cert-macos/>)
*   [SWG bar 权限、本地隐私与 TLS 探测限额说明](<https://swgbar.com/zh-CN/guides/macos-network-extension-privacy-probe-limits/>)
*   [SWG bar 如何检查 HTTPS 解密](<https://swgbar.com/zh-CN/how-it-works/>)
*   [下载并安装 Mac 版 SWG bar（macOS 14+）](<https://swgbar.com/zh-CN/install/>)
*   [检测 SSL 与 HTTPS 检查的 Chrome 扩展（SWG bar 配套插件）](<https://swgbar.com/zh-CN/chrome-extension/>)
*   [SWG bar CLI 使用指南](<https://swgbar.com/zh-CN/cli/>)
*   [SWG bar MCP 使用指南](<https://swgbar.com/zh-CN/mcp/>)
*   [SWG bar 版本信息](<https://swgbar.com/zh-CN/releases/>)
*   [关于 SWG bar](<https://swgbar.com/zh-CN/about/>)
