So richten Sie HTTPS_PROXY für Cursor und Claude Code im Unternehmensnetzwerk ein

Wenn Ihr Unternehmen den ausgehenden Datenverkehr über einen Unternehmensproxy blockiert, hören KI-Assistenten wie Cursor und Claude Code einfach auf zu antworten: die Autovervollständigung hängt, die CLI gibt ETIMEDOUT oder SSL certificate problem aus. Lassen Sie uns untersuchen, wie man die Umgebungsvariablen HTTPS_PROXY korrekt festlegt, die Authentifizierung einrichtet und typische Fehler vermeidet, aufgrund derer Entwickler Stunden mit dem Debuggen von Netzwerkeinstellungen anstelle von Code verbringen.

Warum KI-Assistenten einen Proxy im Unternehmensnetzwerk benötigen

Cursor und Claude Code sind keine lokalen Modelle. Sie greifen ständig auf externe APIs zu: Cursor kontaktiert seine Code-Indexierungsserver und die API-Modelle (OpenAI, Anthropic, Google, je nach gewähltem Anbieter), während Claude Code — direkt über HTTPS auf die Anthropic API zugreift. Im Unternehmensnetzwerk ist der direkte Zugang zum Internet häufig durch eine Firewall blockiert, und der gesamte ausgehende Datenverkehr muss über einen Proxy-Server (Squid, Zscaler, Blue Coat, Fortinet FortiProxy oder interner Unternehmensgateway) geleitet werden. Ohne korrekt konfigurierte Umgebungsvariablen weiß die Anwendung einfach nicht, dass der Datenverkehr über den Proxy geleitet werden muss, und versucht, direkt auf das Internet zuzugreifen — was zu Zeitüberschreitungen führt.

Eine besondere Schwierigkeit besteht darin, dass Cursor auf Electron basiert (im Wesentlichen ist es Chromium + Node.js), während Claude Code — eine Node.js-CLI-Anwendung ist. Jede hat ihre eigene Logik zum Lesen der Proxy-Einstellungen: Electron erbt teilweise die Systemeinstellungen des Betriebssystems, während Node.js-Prozesse die Umgebungsvariablen HTTP_PROXY/HTTPS_PROXY direkt oder über Bibliotheken wie undici und node-fetch lesen. Dies führt zu Verwirrung: die Einstellungen sind gesetzt, aber das Tool „sieht“ sie nicht.

Die Variablen HTTP_PROXY, HTTPS_PROXY und NO_PROXY: wie es funktioniert

Der klassische Weg, einen Proxy für Konsolenanwendungen in Node.js, Python und Go anzugeben, ist über Umgebungsvariablen. Der Unterschied zwischen HTTP_PROXY und HTTPS_PROXY ist grundlegend: der erste wird für Anfragen über das HTTP-Protokoll verwendet, der zweite für HTTPS-Anfragen (und fast der gesamte Datenverkehr der KI-Assistenten erfolgt über HTTPS). Es ist ratsam, beide anzugeben, selbst wenn der tatsächliche Datenverkehr nur HTTPS ist — einige Bibliotheken führen zu Beginn Dienst-HTTP-Anfragen durch.

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

Beachten Sie: Selbst für HTTPS-Datenverkehr wird das Schema in der Proxy-Adresse als http:// angegeben, nicht https:// — dies ist die Adresse des Proxy-Servers selbst, nicht der Zielressource. Die Verbindung zum Proxy über HTTP ist normal, die Verschlüsselung zum Endserver funktioniert trotzdem über den CONNECT-Tunnelmechanismus.

Die Variable NO_PROXY ist notwendig, um interne Unternehmensadressen vom Proxy auszuschließen — andernfalls gehen Anfragen an interne Git-Repositories, Jira oder lokale Entwicklungsdienste ebenfalls über den externen Proxy und finden entweder nicht statt oder werden langsamer. Ein wichtiger Punkt: einige Bibliotheken sind empfindlich gegenüber der Groß- und Kleinschreibung der Variablen. Zur Sicherheit sollten Sie beide Varianten angeben — in Groß- und Kleinbuchstaben:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

Proxy für Cursor konfigurieren

Cursor verwendet teilweise die systemeigenen Proxy-Einstellungen des Betriebssystems (insbesondere unter macOS und Windows), aber für einen stabilen Betrieb im Unternehmensnetzwerk ist es besser, dies explizit über Umgebungsvariablen und, falls erforderlich, über die Konfigurationsdatei der Anwendung einzurichten.

Unter macOS und Linux ist es am einfachsten, den Export der Variablen in die Profil-Datei der Shell hinzuzufügen, damit sie bei jedem Start des Terminals, von dem aus Cursor gestartet wird, übernommen werden:

# ~/.zshrc oder ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

Nach der Änderung der Profil-Datei führen Sie source ~/.zshrc aus und starten Cursor vollständig neu (nicht einfach das Fenster minimieren — beenden Sie den Prozess über den Activity Monitor oder den Task-Manager, da Electron-Anwendungen die Umgebung beim Start cachen).

Unter Windows ist es bequemer, die Variablen über die Systemeinstellungen (Systemsteuerung → System → Erweiterte Systemeinstellungen → Umgebungsvariablen) oder über PowerShell für eine dauerhafte Speicherung festzulegen:

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

Wenn Cursor danach immer noch keine Verbindung zur API der Modelle herstellen kann, überprüfen Sie die Proxy-Einstellungen innerhalb der Anwendung selbst: Einstellungen → Netzwerk (oder Allgemein) — dort kann es ein separates Feld für die Proxy-URL geben, das die systemeigenen Variablen überschreibt. In einigen Versionen von Cursor muss auch die Option „Systemproxy-Einstellungen verwenden“ explizit aktiviert werden.

Proxy für Claude Code konfigurieren

Claude Code ist ein CLI-Tool auf Node.js, das über npm/npx ausgeführt wird, daher liest es direkt die Umgebungsvariablen aus der Terminal-Sitzung, in der es aufgerufen wurde. Dies vereinfacht die Konfiguration: es reicht aus, die Variablen vor dem Start zu exportieren.

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

Wenn Sie Claude Code als Teil eines CI-Pipelines oder aus einem Skript ausführen, übergeben Sie die Variablen explizit im Startbefehl, um eine Abhängigkeit von der globalen Umgebung der Shell zu vermeiden:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "Überprüfen Sie die Tests im Projekt"

Für eine dauerhafte Konfiguration ist es bequemer, die Variablen in einer .env-Datei im Stammverzeichnis des Projekts zu fixieren und sie über direnv oder die eingebaute Unterstützung für dotenv, falls Ihre Shell dies unterstützt, zu übernehmen. Dies ist besonders praktisch, wenn verschiedene Projekte unterschiedliche Proxy-Einstellungen benötigen (zum Beispiel, wenn ein Projekt mit einer internen API arbeitet und ein anderes mit externen Diensten).

Authentifizierung am Unternehmensproxy

Die meisten Unternehmensproxies erfordern eine Authentifizierung — Basic Auth, Digest oder NTLM. Für Basic Auth können Benutzername und Passwort direkt in die Proxy-URL eingebettet werden, wie oben gezeigt: http://user:[email protected]:8080. Ein wichtiger Punkt — wenn das Passwort spezielle Zeichen enthält (@, #, %), müssen sie URL-kodiert werden, sonst bricht der Parser der Proxy-Zeichenfolge an der Grenze zwischen Benutzername und Host.

# Wenn das Passwort P@ssw0rd#2024 ist, kodieren wir die Sonderzeichen:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

Schwieriger wird es bei der NTLM-Authentifizierung (die häufig in Verbindung mit Microsoft ISA Server, Forefront TMG oder Fortinet verwendet wird) — Node.js und die meisten HTTP-Clients unterstützen NTLM „out of the box“ nicht. In diesem Fall ist die Standardlösung — einen lokalen Proxy-Mittelsmann einzurichten, der das NTLM-Handschlag übernimmt und dann einen „sauberen“ HTTP-Proxy für die Anwendung bereitstellt. Dazu werden häufig cntlm oder px (lokaler NTLM-Proxy auf Python) verwendet. Das Schema ist einfach: Cursor/Claude Code → localhost:3128 (cntlm) → Unternehmens-NTLM-Proxy → Internet.

# Beispielkonfiguration für cntlm (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    Ihr_Passwort_oder_Hash
Proxy       proxy.company.local:8080
Listen      3128

# Nach dem Start von cntlm geben wir die lokale Adresse an:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

Zertifikate und MITM: SSL-Probleme im Unternehmensnetzwerk

Wenn im Unternehmen ein Produkt wie Zscaler, Netskope oder ein anderer Webfilter mit SSL-Inspektion bereitgestellt wird, wird der Datenverkehr am Proxy entschlüsselt und mit dem Unternehmens-Root-CA-Zertifikat signiert. Node.js (und damit auch Claude Code und der größte Teil der internen Module von Cursor) vertraut standardmäßig nur seinem eingebauten Satz von Root-Zertifikaten und wird den Fehler UNABLE_TO_VERIFY_LEAF_SIGNATURE oder self signed certificate in certificate chain auswerfen.

Die Lösung besteht darin, das Unternehmens-CA-Zertifikat zu exportieren (normalerweise kann es von der IT-Abteilung bezogen oder aus dem Zertifikatsspeicher des Browsers exportiert werden) und Node.js den Pfad dazu über die Variable NODE_EXTRA_CA_CERTS anzugeben:

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

Es wird dringend davon abgeraten, die Zertifikatsüberprüfung global über NODE_TLS_REJECT_UNAUTHORIZED=0 zu deaktivieren — dies entfernt den Schutz vor MITM-Angriffen für den gesamten Prozess, einschließlich legitimer Verbindungen. Verwenden Sie dieses Flag nur für einmalige Diagnosen und stellen Sie den Schutz unbedingt wieder her.

Typische Fehler und deren Lösungen

Fehler	Ursache	Lösung
ETIMEDOUT / ECONNREFUSED	Proxy-Variablen sind in der Sitzung, in der die Anwendung ausgeführt wird, nicht exportiert	Überprüfen Sie echo $HTTPS_PROXY im selben Terminal, starten Sie die Anwendung vollständig neu
407 Proxy Authentication Required	Benutzername/Passwort sind nicht angegeben oder veraltet	Aktualisieren Sie die Anmeldeinformationen in der Proxy-Zeile, URL-kodieren Sie die Sonderzeichen im Passwort
self signed certificate in certificate chain	Der Unternehmens-MITM-Proxy ersetzt das Zertifikat	Geben Sie NODE_EXTRA_CA_CERTS mit dem Unternehmens-Root-CA an
Der Proxy funktioniert im Terminal, aber nicht in Cursor	Cursor wurde nicht aus dem richtigen Terminal oder über eine Verknüpfung ohne Umgebung gestartet	Starten Sie Cursor mit einem Befehl aus dem Terminal mit exportierten Variablen oder definieren Sie die Variablen global im System
NTLM authentication failed	Der Client unterstützt das NTLM-Handschlag nicht	Richten Sie einen Zwischenproxy cntlm oder px zwischen der Anwendung und dem Unternehmensproxy ein

Überprüfung der Verbindung mit curl

Bevor Sie herausfinden, warum Cursor oder Claude Code nicht funktioniert, stellen Sie sicher, dass der Proxy überhaupt erreichbar ist und den HTTPS-Datenverkehr korrekt weiterleitet. Verwenden Sie dazu curl — es liest dieselben Umgebungsvariablen und ermöglicht es Ihnen, das Problem schnell zu lokalisieren, ohne schwere Anwendungen zu starten.

# Überprüfung der Erreichbarkeit des Proxys und der Authentifizierung
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# Überprüfung unter Berücksichtigung des Unternehmenszertifikats
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

Wenn curl erfolgreich eine Antwort erhält (selbst 401 oder 403 — das ist normal, das TLS-Handschlag hat funktioniert), und Claude Code dennoch keine Verbindung herstellen kann — liegt das Problem nicht im Netzwerk, sondern daran, dass der Prozess die Umgebungsvariablen nicht sieht. Wenn curl ebenfalls mit einem Zertifikatfehler oder einer Zeitüberschreitung fehlschlägt — liegt das Problem auf Netzwerk- oder Proxy-Ebene, und die Tools sind hier nicht relevant.

Wann ein externer Proxy anstelle des Unternehmensproxies benötigt wird

Manchmal beschränkt sich die Aufgabe nicht nur auf den Zugang aus dem Unternehmensnetzwerk nach außen. Entwickler, die Integrationen mit geoabhängigen APIs testen, das Verhalten des Dienstes aus verschiedenen Ländern überprüfen oder die Rate-Limit-Politiken der Anbieter debuggen, stellen fest, dass der Unternehmensproxy für alle Anfragen dieselbe Unternehmens-IP ausgibt. In solchen Szenarien ist es praktisch, den Testdatenverkehr parallel zum Hauptarbeitsumfeld über einen externen Proxy zu leiten.

Für stabile, langfristige Testsitzungen mit minimalem Risiko einer IP-Sperrung eignen sich residential proxies — sie verwenden echte IP-Adressen von Heim-Anbietern und sehen aus wie normaler Benutzerverkehr, was wichtig ist, um geo-spezifische Antworten der API zu überprüfen. Wenn das Verhalten eines mobilen Clients reproduziert oder netzwerktypensensitive Szenarien getestet werden müssen, sollten mobile Proxies in Betracht gezogen werden. Und für massives paralleles Testen von Anfragen an öffentliche APIs, wo Geschwindigkeit und Kosten des Datenverkehrs wichtiger sind als die Maskierung als normaler Benutzer, sind in der Regel Datacenter-Proxies ausreichend.

Wichtig: Ein solcher externer Proxy wird genau wie die Variablen HTTPS_PROXY/HTTP_PROXY konfiguriert, jedoch für die Testumgebung oder ein separates Terminalprofil, um ihn nicht mit dem Hauptarbeitsdatenverkehr über das Unternehmensgateway zu vermischen. Wenn die Unternehmenspolitik vorschreibt, dass der gesamte Datenverkehr des Unternehmens nur über den internen Proxy geleitet wird, muss die Verwendung eines externen Proxys mit der IT/Security abgestimmt werden — viele Unternehmen verbieten ausdrücklich das Umgehen des Unternehmensgateways ohne Genehmigung.

Checkliste zur Konfiguration

Fazit

Die meisten Probleme mit Cursor und Claude Code hinter einem Unternehmensproxy lassen sich auf drei Dinge zurückführen: die Umgebungsvariablen erreichen den Prozess nicht, die Authentifizierung ist falsch konfiguriert oder das Unternehmens-MITM-Zertifikat wurde nicht in die vertrauenswürdigen Zertifikate aufgenommen. Wenn Sie diese drei Punkte der Reihe nach überprüfen — über curl, und nicht sofort über die Anwendung selbst — sparen Sie Stunden beim Debuggen und lokalisieren schnell die Ursache.

Wenn die Aufgabe jedoch über das Unternehmensnetzwerk hinausgeht und Sie das Verhalten der API aus verschiedenen Regionen oder von verschiedenen IP-Typen testen müssen, empfehlen wir, residential proxies auszuprobieren — sie bieten stabileren und weniger verdächtigen Datenverkehr für externe Dienste im Vergleich zu normalen Datacenter-Adressen.