SWG-TLS- & SSL-Zertifikatsfehler in CLI- und KI-Tools auf dem Mac beheben

Behebe CERTIFICATE_VERIFY_FAILED und Fehler mit lokalen Ausstellerzertifikaten in git, npm, Python, Claude Code und Cursor hinter einem SWG unter macOS.

SWG bar · Aktualisiert

Befindet sich ein Firmen-Mac hinter einem Secure Web Gateway (SWG) mit aktiver HTTPS-/SSL-Inspektion (Break-and-Inspect), laden Safari und Chrome Websites oft ohne Warnung, während Terminal-Werkzeuge und KI-Coding-Agenten mit TLS-Handshake-Fehlern wie SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY oder SSL certificate problem: unable to get local issuer certificate abbrechen.

Diese Abweichung entsteht, weil Browser den macOS-Schlüsselbund abfragen – in dem die Unternehmens-Root-CA per MDM installiert werden kann –, während viele Kommandozeilen-Laufzeitumgebungen (git, curl, Node.js/npm, Python/pip) und KI-Tools (Claude Code, Cursor, MCP-Server) Zertifikate gegen ihre eigenen mitgelieferten öffentlichen CA-Speicher prüfen.

1. Prüfen, welcher Hostname einer HTTPS-Inspektion unterliegt

Bevor du Umgebungsvariablen oder Netzwerkeinstellungen änderst, solltest du verifizieren, ob die Zertifikatskette des betroffenen Endpunkts auf deinem Mac tatsächlich ersetzt wird:

  1. Installiere und öffne SWG bar unter macOS 14 oder neuer (Apple Chip).
  2. Führe den fehlschlagenden Befehl einmal aus und prüfe anschließend SWG bar → Domains – oder untersuche den genauen Endpunkt direkt im Terminal mit der integrierten CLI:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. Kontrolliere die Einstufung und die Root-CA. Beachte, dass Web-Frontends, Authentifizierungsserver, Paket-Registries und LLM-API-Endpunkte häufig getrennte Hostnamen nutzen – eine Subdomain kann unverändert durchgeleitet werden, während eine andere entschlüsselt wird.

Wenn du einen MCP-kompatiblen Assistenten einsetzt, kannst du zudem den integrierten MCP-Server von SWG bar verbinden, damit dein KI-Client beobachtete Domains und Zertifikatsketten direkt abfragen kann.

2. Den passenden Lösungsweg für deine Umgebung wählen

Sobald bestätigt ist, dass eine Inspektions-Root-CA das Zertifikat des Ziel-Hostnamens signiert, wähle je nach Netzwerkrichtlinie und Berechtigung einen dieser drei Ansätze:

Ansatz Funktionsweise Ideal, wenn
CA-Vertrauen für das Tool konfigurieren Verweise die Laufzeitumgebung (z. B. über NODE_EXTRA_CA_CERTS, SSL_CERT_FILE oder REQUESTS_CA_BUNDLE) auf ein exportiertes PEM-Bundle, das die Unternehmens-Root-CA enthält. Die Unternehmensrichtlinie inspiziertes SWG-Routing vorschreibt und du dieser CA für das jeweilige Tool vertraust.
Administrative TLS-Inspektionsausnahme anfordern Die IT nimmt den API- oder Registry-Hostnamen am Gateway von der HTTPS-Entschlüsselung aus, behält das Gateway-Routing aber bei. Tools mit Certificate Pinning oder teamweite Entwickler-Endpunkte durch Break-and-Inspect fehlschlagen.
Domänenbasierte SWG-Umgehung in SWG bar aktivieren Routet den gewählten Hostnamen unter macOS ohne HTTPS-Entschlüsselung des Gateways über Menüleiste, CLI oder MCP. Du das Netzwerk verwaltest oder berechtigt bist, für bestimmte Domains auf deinem Mac eine uninspizierte Route zu nutzen.

Einen detaillierten Architekturvergleich zwischen Gateway-Ausnahmen und Routenänderungen findest du unter SWG-Umgehung vs. TLS-Inspektionsausnahme.

3. Inspizierte Domain unter macOS bei Berechtigung umgehen

Wenn eine domänenbasierte Umgehung für dein Netzwerk zulässig ist, kannst du sie für den genauen API- oder Registry-Hostnamen über die Menüleiste (SWG bar → Domains → SWG umgehen → Umgehung für diese Domain aktivieren) oder im Terminal einschalten:

/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status

Sobald der Status Umgehung aktiv anzeigt, starte den CLI-Befehl, Hintergrund-Daemon oder IDE-Extension-Host neu, damit bestehende Verbindungen geschlossen und über die neue Regel neu aufgebaut werden. Hinweise zur erstmaligen Freigabe der macOS-Netzwerkerweiterung, zum Neustartverhalten und zum späteren Ausschalten findest du unter SWG auf dem Mac umgehen.

Plattform- und Netzwerkgrenzen beachten

  • Geltungsbereich pro Hostname: Eine Umgehung für example.com schließt api.example.com oder auth.example.com nicht automatisch ein. Prüfe jeden einzelnen Hostnamen, den dein Tool kontaktiert.
  • Netzwerkvoraussetzungen: SWG bar 2.4.12 erfordert macOS 14+ auf Apple-Chip-Macs sowie einen verfügbaren IPv4-Pfad über eine physische Netzwerkschnittstelle. Blockiert eine Firewall direkte ausgehende Verbindungen oder erzwingt das Tool einen eigenen expliziten Proxy, deaktiviere die Umgehungsregel und nutze stattdessen eine administrative TLS-Ausnahme oder eine CA-Bundle-Konfiguration.
  • Mit frischen Nachweisen verifizieren: Führe nach jeder Änderung anhand der Anleitung zur HTTPS- & SSL-Inspektion eine neue Prüfung durch, statt dich auf zwischengespeicherte Ergebnisse zu verlassen.