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:
- Installiere und öffne SWG bar unter macOS 14 oder neuer (Apple Chip).
- 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
- 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.comschließtapi.example.comoderauth.example.comnicht 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.