Как исправить ошибки сертификатов TLS и SSL из-за SWG в CLI и ИИ на Mac
Устранение ошибок CERTIFICATE_VERIFY_FAILED и local issuer certificate в git, npm, Python, Claude Code и Cursor за корпоративным SWG-шлюзом в macOS.
SWG bar · Обновлено
Когда корпоративный Mac работает за защищённым веб-шлюзом (SWG), выполняющим HTTPS/SSL-инспекцию (break-and-inspect), Safari и Chrome обычно открывают сайты без предупреждений, тогда как утилиты в Терминале и ИИ-агенты для разработки завершаются ошибками рукопожатия TLS — например, SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY или SSL certificate problem: unable to get local issuer certificate.
Это расхождение возникает потому, что браузеры обращаются к системной Связке ключей macOS (Keychain), куда MDM может установить корневой сертификат проверки вашей организации, а многие среды командной строки (git, curl, Node.js/npm, Python/pip) и ИИ-инструменты (Claude Code, Cursor, серверы MCP) проверяют сертификаты по собственным встроенным хранилищам публичных центров сертификации (CA).
1. Убедитесь, какое именно имя хоста проходит HTTPS-инспекцию
Прежде чем менять переменные окружения или сетевые настройки, проверьте, действительно ли на вашем Mac подменяется цепочка сертификатов проблемного узла:
- Установите и откройте SWG bar на macOS 14 или новее (Apple silicon).
- Запустите проблемную команду один раз, а затем проверьте SWG bar → Домены — или прозондируйте нужный хост напрямую из Терминала с помощью встроенного CLI:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
- Изучите классификацию и корневой CA. Учитывайте, что веб-интерфейсы, серверы авторизации, реестры пакетов и конечные точки API языковых моделей часто используют разные имена хостов: один поддомен может проходить без изменений, а другой — расшифровываться.
Если вы пользуетесь совместимым с MCP ИИ-помощником, можно также подключить встроенный MCP-сервер SWG bar, чтобы ИИ-клиент напрямую запрашивал наблюдаемые домены и цепочки сертификатов.
2. Выберите подходящее решение для вашей среды
Убедившись, что сертификат целевого имени хоста подписан корневым CA инспекции, выберите один из трёх подходов в зависимости от сетевой политики и ваших полномочий:
| Подход | Как это работает | Когда подходит лучше всего |
|---|---|---|
| Настроить доверие CA для инструмента | Укажите среде выполнения (например, через NODE_EXTRA_CA_CERTS, SSL_CERT_FILE или REQUESTS_CA_BUNDLE) путь к экспортированному PEM-файлу с корпоративным корневым CA. |
Политика компании требует проверяемой маршрутизации через SWG, и вы доверяете этому CA для конкретного инструмента. |
| Запросить административное исключение TLS-инспекции | ИТ-служба исключает имя хоста API или реестра пакетов из расшифровки HTTPS на шлюзе, сохраняя маршрутизацию через шлюз. | Инструменты с привязкой сертификатов (certificate pinning) или общие для команды сервисы разработки ломаются из-за break-and-inspect. |
| Включить подоменный обход SWG в SWG bar | Направляет выбранное имя хоста в macOS без расшифровки HTTPS на шлюзе через строку меню, CLI или MCP. | Вы администрируете сеть или уполномочены тестировать маршрут без инспекции для отдельных доменов на своём Mac. |
Подробное архитектурное сравнение исключений на шлюзе и изменения маршрута приведено в статье Обход SWG и исключение TLS-инспекции.
3. Включите обход проверяемого домена в macOS при наличии полномочий
Если подоменный обход допустим в вашей сети, включите его для точного имени хоста API или реестра из строки меню (SWG bar → Домены → Обойти SWG → Включить обход для этого домена) либо из Терминала:
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status
Когда статус сменится на Обход активен, перезапустите команду CLI, фоновый демон или процесс расширений IDE, чтобы закрыть старые соединения и переподключиться по новому правилу. Инструкции по первичному разрешению сетевого расширения macOS, поведению при перезапуске и отключению обхода см. в руководстве Как обойти SWG на Mac.
Учитывайте ограничения платформы и сети
- Действие на уровне конкретного имени хоста: обход для
example.comне включает автоматическиapi.example.comилиauth.example.com. Проверьте каждое имя хоста, к которому обращается инструмент. - Требования к сети: SWG bar 2.4.12 требует macOS 14+ на Apple silicon и доступного пути IPv4 через физический сетевой интерфейс. Если межсетевой экран блокирует прямые исходящие соединения или инструмент принудительно использует собственный прокси, отключите правило обхода и воспользуйтесь исключением TLS на шлюзе либо настройкой пакета сертификатов CA.
- Проверка на свежих данных: после любого изменения выполняйте новую проверку по руководству по проверке HTTPS и SSL, а не полагайтесь на кешированные результаты.