Как исправить ошибки сертификатов 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 подменяется цепочка сертификатов проблемного узла:

  1. Установите и откройте SWG bar на macOS 14 или новее (Apple silicon).
  2. Запустите проблемную команду один раз, а затем проверьте SWG bar → Домены — или прозондируйте нужный хост напрямую из Терминала с помощью встроенного CLI:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. Изучите классификацию и корневой 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, а не полагайтесь на кешированные результаты.