Claude Code Verbindungsfehler: Proxy, TLS und Firewall beheben

Du willst Claude Code auf einem Firmenrechner oder über VPN nutzen, und die Verbindung scheitert mit Fehlern wie diesen?

Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
  Check your proxy or corporate SSL certificates
fetch failed

Das sind Netzwerkfehler und bedeuten "Claude Code erreicht den Server von Anthropic (api.anthropic.com) nicht." Es handelt sich nicht um Authentifizierung (401/403), nicht um Serverüberlastung (529/500) und nicht um ein Rate-Limit (429) – die Anfrage hat den Server überhaupt nie erreicht. Die üblichen Ursachen sind Firmen-Proxys, TLS-Inspektion (Zertifikate) und Firewalls, weshalb dieses Problem in Unternehmensnetzwerken besonders häufig auftritt. Dieser Artikel behandelt Proxy-Konfiguration, Firmen-CA-Zertifikate, die freizugebenden Domains und die Diagnoseschritte – auf Basis offizieller Informationen.

Die Kernpunkte vorab. (1) Hinter einem Proxy setzt du HTTPS_PROXY. (2) Bei einem Zertifikatsfehler durch TLS-Inspektion (Zscaler usw.) richtest du NODE_EXTRA_CA_CERTS auf die Firmen-CA – und deaktiviere niemals die Prüfung mit NODE_TLS_REJECT_UNAUTHORIZED=0 (das setzt den gesamten Datenverkehr dem Abfangen aus). (3) Führe zuerst curl -I https://api.anthropic.com aus, um zu prüfen "wird der Server überhaupt erreicht?" – das ist der Ausgangspunkt jeder Eingrenzung.

1. Was dieser Fehler bedeutet

Unable to connect to API, fetch failed, ECONNREFUSED / ETIMEDOUT bedeuten "die Anfrage hat den Server von Anthropic nicht erreicht" = sie ist irgendwo in TCP/TLS/DNS gescheitert. Das ist der entscheidende Unterschied zu anderen Fehlern: Authentifizierung (401/403), Server (529/500) und Rate (429) sind Antworten, nachdem der Server erreicht wurde, während Netzwerkfehler bedeuten, dass er nie erreicht wurde.

In Unternehmensnetzwerken teilen sich die typischen Blockaden in drei Schichten auf. (1) Proxy – du kommst nicht direkt nach außen und musst über einen Firmen-Proxy routen, der nicht konfiguriert ist. (2) TLS-Inspektion (Zertifikate) – ein Inspektions-Proxy wie Zscaler ersetzt Zertifikate, sodass du der Firmen-Root-CA vertrauen musst. (3) Firewall – die erforderlichen Domains sind nicht freigegeben. Das Erste, was du tun solltest, ist, mit curl -I https://api.anthropic.com zu bestätigen "ist der Server erreichbar?" – diese eine Prüfung trennt "ein Netzwerkproblem" von "allem anderen."

2. Proxy-Konfiguration (HTTPS_PROXY)

Wenn du über einen Firmen-Proxy routen musst, setze die standardmäßigen Proxy-Umgebungsvariablen. Claude Code berücksichtigt sie.

# Empfohlen: HTTPS-Proxy
export HTTPS_PROXY=http://proxy.example.com:8080
# Falls HTTPS nicht verfügbar ist, HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# Ziele, die den Proxy umgehen (durch Leerzeichen oder Komma getrennt)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# Proxy mit Authentifizierung (Passwörter nicht fest einbetten)
export HTTPS_PROXY=http://username:password@proxy.example.com:8080

Hinweise: SOCKS-Proxys werden nicht unterstützt. Für NTLM- / Kerberos-Proxys empfiehlt die offizielle Dokumentation, dazwischen ein LLM gateway aufzusetzen und ANTHROPIC_BASE_URL darauf zu richten. Wenn du außerdem MCP-Server verwendest, musst du HTTPS_PROXY und NODE_EXTRA_CA_CERTS im env jedes einzelnen Servers explizit setzen (sie werden nicht vom übergeordneten Prozess vererbt). Diese Variablen können auch im env-Block der settings.json stehen.

3. TLS und Firmen-CA-Zertifikate (am wichtigsten, sicher)

Die häufigste Blockade in Unternehmen ist ein Zertifikatsfehler, der dadurch entsteht, dass ein TLS-Inspektions-Proxy (Zscaler, Netskope, Palo Alto usw.) Zertifikate ersetzt. Typische Meldungen sind unable to get local issuer certificate und SELF_SIGNED_CERT_IN_CHAIN.

Zum Hintergrund: Neuere Versionen von Claude Code vertrauen SOWOHL dem mitgelieferten CA-Satz ALS AUCH dem Trust Store des Betriebssystems. Das heißt: Wenn die Firmen-Root-CA im Zertifikatsspeicher des Betriebssystems liegt, funktioniert es oft ohne zusätzliche Konfiguration (das Verhalten variiert je nach Version, prüfe daher den aktuellen Stand). Liegt sie nicht im OS-Speicher, richte NODE_EXTRA_CA_CERTS auf das CA-Bundle (PEM), das du von der IT erhalten hast:

# Der korrekte, sichere Weg: der Firmen-CA vertrauen
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# Falls der Proxy ein Client-Zertifikat erfordert (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

Wenn du bereits zum Installationszeitpunkt (bevor die Binärdatei existiert) auf einen Zertifikatsfehler stößt, gib die CA an curl weiter: curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash.

4. Firewall-Allowlist-Domains

Wenn deine Firewall die Ziele einschränkt, gib diese Domains über HTTPS (443) frei (gemäß den offiziellen Netzwerkanforderungen).

Telemetrie (statsig.anthropic.com) und Fehlerberichte (*.sentry.io) sind optional und können deaktiviert werden (sie müssen nicht in der erforderlichen Allowlist enthalten sein). Wenn du Installationen selbst über npm verwaltest, brauchst du downloads.claude.ai möglicherweise nicht. Die genauen Domains und IP-Bereiche können überarbeitet werden, daher prüfe den aktuellen Stand auf der offiziellen Netzwerkkonfigurationsseite.

5. Der Diagnose-Workflow

Wenn keine Verbindung zustande kommt, gehe von oben nach unten vor. Das erste curl gibt die Richtung vor.

6. Abgrenzung zu ähnlichen Fehlern

"Es bleibt hängen" kann auch nicht-netzwerkbedingt sein. Die große Trennlinie ist "hat es den Server erreicht?"

Eine Eselsbrücke: Netzwerkfehler bedeuten "der Server wurde nie erreicht" (TCP/TLS/DNS), und HTTPS_PROXY oder NODE_EXTRA_CA_CERTS helfen nur auf dieser Schicht. Im Gegensatz dazu sind 401/403, 529/500 und 429 "Antworten nach dem Erreichen", sodass das Anpassen von Proxy oder CA sie nicht behebt. Ob curl erfolgreich ist, ist das beste einzelne Indiz, das die beiden voneinander trennt. Zu weiteren häufigen Fehlern siehe die Fehlerübersicht.

Zusammenfassung

Die Netzwerk-/Proxy-Fehler von Claude Code (Unable to connect / fetch failed / SSL certificate verification failed usw.) bedeuten, dass die Anfrage den Server nie erreicht hat = ein TCP/TLS/DNS-Fehler. Sie sind etwas anderes als Authentifizierung (401/403), Server (529/500) und Rate (429), und die üblichen Verursacher sind der Firmen-Proxy, die TLS-Inspektion und die Firewall im Unternehmen.

Die Lösungen: (1) Hinter einem Proxy setzt du HTTPS_PROXY (SOCKS nicht unterstützt; NTLM/Kerberos über ein Gateway), (2) bei Zertifikatsfehlern legst du die Firmen-CA in NODE_EXTRA_CA_CERTS – niemals NODE_TLS_REJECT_UNAUTHORIZED=0, (3) setze api.anthropic.com usw. in der Firewall auf die Allowlist. Diagnostiziere, indem du zuerst die Erreichbarkeit mit curl -I https://api.anthropic.com testest -> /doctor und Proxy-Prüfung -> Zertifikats-/Proxy-Einstellungen -> eine direkte Verbindung zur Bestätigung -> DNS/VPN/Docker. Der Schlüssel ist, Netzwerk von Authentifizierung/Server/Rate über die Frage "hat es den Server erreicht?" zu trennen. Verwandt: Authentifizierungs-/Login-Fehler, 529/500-Fehler, Claude-Code-Fehlerübersicht.

FAQ

Q. Auf meinem Firmen-PC erscheint "Unable to connect to API" und ich komme nicht durch.
A. Meistens musst du über einen Firmen-Proxy routen, der nicht konfiguriert ist. Prüfe zuerst die Erreichbarkeit mit curl -I https://api.anthropic.com; wenn das scheitert, setze einen Proxy wie export HTTPS_PROXY=http://proxy.example.com:8080 (für einen Proxy mit Authentifizierung ergänze user:password@). Beachte, dass SOCKS nicht unterstützt wird, und für NTLM/Kerberos-Proxys lautet die offizielle Empfehlung, über ein LLM gateway zu gehen.

Q. Ich bekomme "SSL certificate verification failed."
A. Das ist typischerweise ein Firmen-TLS-Inspektions-Proxy (z. B. Zscaler), der Zertifikate ersetzt. Hole dir die Firmen-Root-CA (PEM) von der IT und setze export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem. Wenn die Firmen-CA bereits im Zertifikatsspeicher des Betriebssystems liegt, funktioniert es eventuell ohne Konfiguration. Deaktiviere niemals die Prüfung mit NODE_TLS_REJECT_UNAUTHORIZED=0 – das setzt den gesamten Datenverkehr dem Abfangen aus.

Q. NODE_TLS_REJECT_UNAUTHORIZED=0 zu setzen hat es behoben. Ist das in Ordnung?
A. Nein – mach das sofort rückgängig. Es deaktiviert die TLS-Zertifikatsprüfung für den gesamten Prozess und lässt den gesamten Datenverkehr – einschließlich des Verkehrs zu api.anthropic.com – schutzlos gegenüber Man-in-the-Middle-Angriffen (Abhören/Manipulation). Das ist ein gravierendes Sicherheitsrisiko, das Zugangsdaten und Quellcode preisgeben kann. Die einzig richtige Lösung ist, der Firmen-CA über NODE_EXTRA_CA_CERTS korrekt zu vertrauen.

Q. Welche Domains sollte ich in der Firewall freigeben?
A. Über HTTPS (443) gibst du mindestens api.anthropic.com (API), claude.ai und platform.claude.com (Authentifizierung), downloads.claude.ai (Installer/Updates) und raw.githubusercontent.com frei. Telemetrie (statsig) und Fehlerberichte (sentry) sind optional. Die genauen Domains/IPs können überarbeitet werden, daher prüfe den aktuellen Stand auf der offiziellen Netzwerkkonfigurationsseite.

Q. curl funktioniert, aber nur Claude Code stellt keine Verbindung her.
A. Die Ursache liegt oft zwischen Claude Code und dem Betriebssystem. Häufige Fälle: eine WSL-/etc/resolv.conf, die auf einen toten DNS zeigt, Überreste eines veralteten VPN (z. B. alte macOS-utun-Schnittstellen), oder ein residentes Tool wie Docker, das den Verkehr abfängt. Probiere eine direkte Verbindung ohne VPN, stoppe residente Tools und überprüfe das DNS, in dieser Reihenfolge. Beachte, dass vorübergehende 5xx-Fehler bis zu 10 Mal automatisch wiederholt werden; wenn du also einen Fehler siehst, während curl erfolgreich ist, sind die Wiederholungsversuche bereits aufgebraucht.