Przejdź do głównej zawartości

Konfiguracja proxy i VPN

Claude Code działa za firmowym proxy, gdy HTTPS_PROXY, a dla wyjątków NO_PROXY, znajduje się w bloku env pliku ustawień. Proxy z inspekcją TLS wymaga dodatkowo certyfikatu głównego w systemowym magazynie zaufania albo w NODE_EXTRA_CA_CERTS, a mTLS — certyfikatu i klucza klienta. Zapora musi przepuszczać api.anthropic.com, hosty logowania i hosty poszczególnych funkcji.

Ta strona jest dla developera, któremu pierwsza sesja claude nie działa w sieci firmowej, i dla inżyniera platformy, który musi to uruchomić dla całego zespołu. Typowy obraz: w domu Claude Code działa, w biurze zgłasza Unable to connect to API albo SSL certificate verification failed. Dział IT mówi, że „wszystko idzie przez Zscalera”, a poprawka, która zadziałała na jednym laptopie, nie dociera ani do agentów w tle, ani do następnej osoby w zespole.

  • Tabelę decyzyjną, która mówi, których ustawień proxy, certyfikatów i mTLS potrzebuje twoja sieć
  • Blok env w settings.json, który dociera do każdej sesji, także do agentów w tle
  • Aktualną listę hostów Claude Code z podziałem na wymagane i opcjonalne
  • Plik managed settings, który dostarcza tę samą konfigurację na każdą maszynę
  • Procedurę weryfikacji (claude --debug, /status, claude doctor), która dowodzi, że konfiguracja się wczytała
  • Tabelę awarii, która łączy każdy komunikat błędu z przyczyną i poprawką

Każdą zmienną, host i komunikat błędu na tej stronie sprawdzono 2026-09-26 w dokumentacji Claude Code (konfiguracja sieci, zmienne środowiskowe, błędy) i w zainstalowanym CLI w wersji 2.1.283.

Zanim dotkniesz pliku konfiguracyjnego, zadaj działowi IT trzy pytania: czy jest proxy, czy proxy rozszyfrowuje TLS i czy brama wymaga certyfikatu klienta. Odpowiedzi przekładają się na ustawienia tak:

Twoja siećCo ustawićSekcja
Bezpośredni dostęp do internetu albo VPN split-tunnel, który nie kieruje hostów Anthropic przez tunelNic—
Wymagane proxy HTTP lub HTTPSHTTPS_PROXY, NO_PROXYProxy
Proxy rozszyfrowuje TLS (Zscaler, Netskope, Palo Alto, Blue Coat i podobne)Nic, jeśli główny CA jest w systemowym magazynie zaufania; w przeciwnym razie NODE_EXTRA_CA_CERTSCertyfikat proxy
Brama wymaga certyfikatu klientaCLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEYmTLS
Proxy przyjmuje tylko NTLM lub KerberosBramka LLM albo lokalne proxy uwierzytelniająceUwierzytelnianie
Dostępne jest tylko proxy SOCKSClaude Code go nie obsługuje (sprawdzone na v2.1.283); poproś o proxy HTTP albo bramkę LLM—
Zapora z listą dozwolonych adresów wyjściowychHosty z tabeli hostów—

Claude Code czyta zmienne sieciowe raz, przy starcie. Umieść je w pliku ustawień, a nie w profilu powłoki. Eksport w powłoce dociera do terminala, z którego uruchamiasz claude, ale agenci w tle działają pod osobnym procesem nadzorcy, który może nigdy tej powłoki nie zobaczyć. Blok env w ~/.claude/settings.json dociera do każdej sesji.

  1. Weź od IT adres proxy razem ze schematem. Claude Code odmawia startu, gdy nie potrafi sparsować adresu proxy, na przykład proxy.company.com:8080 bez http://, i podaje nazwę zmiennej do poprawienia.

  2. Dodaj proxy do ~/.claude/settings.json:

    {
    "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.company.internal"
    }
    }

    Zalecaną zmienną jest HTTPS_PROXY. HTTP_PROXY ustaw tylko wtedy, gdy IT nie daje proxy HTTPS. Działają też nazwy pisane małymi literami, a Claude Code bierze pierwszą znalezioną w kolejności https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. Nieaktualne https_proxy w powłoce wygrywa więc z poprawnym HTTPS_PROXY.

  3. Ustaw NO_PROXY dla hostów wewnętrznych, które nie mogą iść przez proxy, na przykład wewnętrznego serwera MCP albo mirrora pakietów. Zmienna przyjmuje listę rozdzielaną przecinkami lub spacjami, kropkę na początku dla subdomen (.company.internal) i *, żeby ominąć proxy dla wszystkiego. Wpis dla loopbacku nie jest potrzebny dla połączeń WebSocket samego Claude Code: one nigdy nie idą przez proxy.

  4. Uruchom nową sesję poleceniem claude. Działające sesje nie widzą zmiany.

Żeby wypróbować proxy bez edycji pliku, wyeksportuj te same zmienne w powłoce i uruchom claude. Gdy działają, przenieś je do ustawień.

Uwierzytelnianie Basic działa przez adres: http://USERNAME:PASSWORD@proxy.company.com:8080. Trzymaj tę wartość w ~/.claude/settings.json albo w managed settings, nigdy w .claude/settings.json repozytorium, które trafia do gita.

Claude Code nie ma wbudowanej obsługi NTLM ani Kerberosa. Dokumentacja Claude Code zaleca bramkę LLM, która obsługuje twoją metodę uwierzytelniania. Druga popularna opcja to lokalne proxy uwierzytelniające, takie jak Px albo Cntlm: uwierzytelnia się dalej twoimi poświadczeniami Windows lub Active Directory i wystawia zwykłe proxy na localhost, które wpisujesz do HTTPS_PROXY. Dla zespołu lepsza jest bramka: jedna usługa do utrzymania zamiast nakładki na każdym laptopie.

Proxy z inspekcją TLS podpisuje każde połączenie HTTPS na nowo własnym, firmowym certyfikatem głównym. Claude Code odrzuca taki certyfikat, dopóki nie ufa temu CA.

Domyślnie Claude Code ufa zarówno dołączonemu zestawowi CA Mozilli, jak i systemowemu magazynowi certyfikatów (CLAUDE_CODE_CERT_STORE ma domyślnie wartość bundled,system). Jeśli IT już wgrało firmowy certyfikat główny do systemowego magazynu, co na zarządzanych laptopach jest normą, Claude Code działa bez żadnych ustawień certyfikatów. Jest jeden warunek: odczyt magazynu systemowego wymaga środowiska z tls.getCACertificates. Natywny instalator zawsze je ma; instalacje z npm potrzebują Node 22.15 lub nowszego. Na starszym Node działa tylko dołączony zestaw i NODE_EXTRA_CA_CERTS — to częsty powód, dla którego u jednej osoby nie działa, a u sąsiada tak.

Gdy certyfikatu nie ma w magazynie systemowym albo pracujesz na starszym Node, wskaż Claude Code plik PEM:

{
"env": {
"NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
}
}

Plik PEM dostaniesz od IT (certyfikat główny i ewentualne pośrednie) albo wyeksportujesz sam:

Okno terminala
# macOS: eksport firmowego certyfikatu głównego po nazwie z Pęku kluczy
security find-certificate -a -c "Corp Root CA" -p /Library/Keychains/System.keychain > ~/corp-root-ca.pem
# Każdy system: sprawdź, jakiego wystawcę proxy pokazuje dla hosta API
openssl s_client -connect api.anthropic.com:443 -proxy proxy.company.com:8080 -showcerts </dev/null 2>/dev/null | grep -E "s:|i:"

Zamień Corp Root CA na nazwę certyfikatu głównego twojej firmy. Jeśli openssl pokazuje jako wystawcę twoją firmę zamiast publicznego CA, proxy prowadzi inspekcję TLS i potrzebujesz tej sekcji.

NODE_EXTRA_CA_CERTS dodaje certyfikaty, nie zastępuje dołączonego zestawu. CLAUDE_CODE_CERT_STORE=system ustaw tylko wtedy, gdy polityka wymaga, żeby Claude Code nie ufał niczemu poza magazynem systemowym.

NODE_EXTRA_CA_CERTS załatwia zaufanie do serwera. Gdy brama wymaga też, żeby Claude Code potwierdził swoją tożsamość, dodaj certyfikat i klucz klienta:

{
"env": {
"CLAUDE_CODE_CLIENT_CERT": "/etc/pki/claude/client-cert.pem",
"CLAUDE_CODE_CLIENT_KEY": "/etc/pki/claude/client-key.pem"
}
}

Jeśli klucz jest zaszyfrowany, ustaw też CLAUDE_CODE_CLIENT_KEY_PASSPHRASE i dostarczaj go z magazynu sekretów, a nie z pliku w repozytorium.

Rotacja certyfikatu nie wymaga restartu. Podmień pliki pod tymi samymi ścieżkami. Od v2.1.232 Claude Code ponownie czyta oba pliki, gdy żądanie kończy się zerwaniem połączenia albo błędem uzgadniania TLS, i ponawia je z nową parą. Nie czyta ich ponownie, gdy brama kończy uzgadnianie i odpowiada błędem HTTP, a eksportery OpenTelemetry trzymają pierwszy certyfikat do restartu. Żeby potwierdzić rotację, uruchom sesję z claude --debug i poszukaj w logu debugowania wiersza Stale connection — reloaded rotated mTLS client material. Tego wiersza nie ma, gdy para została wczytana ponownie przy stosowaniu ustawień, więc sam jego brak nie oznacza błędu. Podmień parę, zanim stara wygaśnie.

Przepuść te hosty przez proxy i zaporę. Tabela to lista z dokumentacji Claude Code z 2026-09-26, pogrupowana według tego, co przestaje działać bez danego hosta.

HostDo czegoGdy zablokowany
api.anthropic.comŻądania do modelu, kontrola bezpieczeństwa domen WebFetch, flagi funkcji, zdarzenia telemetriiNic nie działa
platform.claude.comLogowanie i odświeżanie tokenów OAuth, dla kont Console i claude.aiNie da się zalogować
claude.ai, claude.comLogowanie kontem claude.aiNie da się zalogować kontem claude.ai
downloads.claude.aiNatywny instalator, automatyczne aktualizacje, pliki wykonywalne wtyczekBrak instalacji i aktualizacji
registry.npmjs.orgInstalacje z npm, serwery MCP uruchamiane przez npx, zależności wtyczekSerwery MCP i wtyczki nie startują
github.comMarketplace’y wtyczek, także oficjalnyInstalacje przez /plugin się nie udają
mcp-proxy.anthropic.comKonektory MCP z claude.aiBrak konektorów
storage.googleapis.comLiczniki instalacji wtyczek w /pluginKosmetyka
raw.githubusercontent.comLista zmian w /release-notesKosmetyka
code.claude.comWbudowane wyszukiwanie w dokumentacjiClaude nie przeczyta własnej dokumentacji
bridge.claudeusercontent.comRozszerzenie Claude in ChromeRozszerzenie nie może się połączyć
*.frame.claudeusercontent.comOdczyt treści artefaktów, tylko gdy narzędzie Artifact jest dostępne dla twojego kontaClaude nie otworzy artefaktu; CLAUDE_CODE_DISABLE_ARTIFACT=1 wyłącza narzędzie i ten host
http-intake.logs.us5.datadoghq.com, browser-intake-us5-datadoghq.comOpcjonalna telemetria operacyjna i raporty błędów (tylko bezpośrednie API Anthropic)Nic się nie psuje
formulae.brew.shSprawdzanie aktualizacji w instalacjach z HomebrewBrak powiadomienia o aktualizacji
*-review.googlesource.comWyszukiwanie zmian w Gerricie, tylko w sesjach zakładki Code w Claude Desktop na repozytoriach z googlesource.comNic się nie psuje (opcjonalny)

Starsze poradniki, w tym poprzednia wersja tej strony, wymieniają statsig.anthropic.com i sentry.io. Żadnego z nich nie ma na liście dla v2.1.283: flagi funkcji i zdarzenia telemetrii idą teraz do api.anthropic.com, a opcjonalna telemetria do dwóch hostów Datadog. Żeby całkiem pozbyć się hostów opcjonalnych, ustaw CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1. To wyłącza też automatyczne aktualizacje, /feedback, informacje o wydaniach, sprawdzanie dostępności trybu fast i pobieranie flag funkcji (przez co Remote Control przestaje być dostępne) — więc zdecyduj świadomie. Ta zmienna zachowuje się nietypowo: wartość 0 albo false nadal wyłącza ruch, więc żeby go przywrócić, usuń zmienną.

Jeśli używasz Amazon Bedrock, Google Cloud Agent Platform (dawniej Vertex AI), Microsoft Foundry albo bramki LLM, ruch do modelu idzie do tego dostawcy. WebFetch nadal wywołuje api.anthropic.com dla kontroli bezpieczeństwa domen, chyba że ustawisz w ustawieniach skipWebFetchPreflight: true, a sprawdzenie dostępności trybu fast też woła api.anthropic.com przez twoje proxy, a nie przez bramkę. Stronę dostawcy opisuje konfiguracja bramki LLM.

Agenci w tle uruchamiani przez claude --bg, claude agents albo /background działają pod jednym procesem nadzorcy na użytkownika. Nadzorca dziedziczy środowisko tej powłoki, która uruchomiła go jako pierwsza. Jeśli proxy siedzi tylko w ~/.zshrc, agenci w tle działają wtedy, gdy nadzorcę przypadkiem uruchomiła ta powłoka, i po cichu nie działają, gdy zrobił to terminal w IDE.

Poprawka jest ta sama co w pierwszej sekcji: każdą zmienną sieciową trzymaj w bloku env w ~/.claude/settings.json albo w managed settings. Po zmianie zatrzymaj działającego nadzorcę, żeby następna sesja w tle wczytała nowe wartości:

Okno terminala
claude daemon stop --any

claude daemon stop kończy też sesje w tle, które nadzorca obsługuje, więc najpierw pozwól działającym agentom skończyć albo uprzedź zespół, jeśli maszyna jest współdzielona.

VPN split-tunnel kieruje przez tunel tylko firmowe zakresy adresów. Hosty Claude Code idą przez publiczny internet, więc zwykle nie trzeba żadnych ustawień.

VPN full-tunnel wysyła wszystko przez infrastrukturę firmy. Spodziewaj się wszystkich trzech elementów: proxy, inspekcji TLS i firmowego DNS. Skonfiguruj je według sekcji powyżej. W dokumentacji błędów pojawiają się dwa problemy typowe dla VPN: WSL potrafi odziedziczyć nieosiągalny serwer nazw w /etc/resolv.conf, a na macOS odłączony lub odinstalowany klient VPN może zostawić nieaktualny interfejs utun albo regułę trasowania.

Jeden developer, który naprawił własnego laptopa, to nie wdrożenie. Dostarcz blok sieciowy jako managed settings — wtedy obowiązuje w każdej sesji na każdej maszynie i ma pierwszeństwo przed ustawieniami użytkownika i projektu:

{
"env": {
"HTTPS_PROXY": "http://proxy.company.com:8080",
"NO_PROXY": "localhost,127.0.0.1,.company.internal",
"NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
}
}

Zapisz go jako osobny plik managed-settings.d/20-network.json obok managed-settings.json w katalogu systemowym. Zespół platformy jest wtedy właścicielem bloku sieciowego i nie edytuje pliku, za który odpowiada dział bezpieczeństwa. Claude Code scala najpierw managed-settings.json, a potem każdy plik *.json z managed-settings.d/ w kolejności alfabetycznej; bloki env scala klucz po kluczu. Katalogi systemowe:

  • macOS: /Library/Application Support/ClaudeCode/
  • Linux i WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\

Dwie pułapki sprawiają, że poprawny plik nic nie robi albo robi szkodę:

  • Wygrywa inne źródło zarządzane. Domyślnie (managedSourcesBehavior: "first-wins") Claude Code bierze źródło zarządzane o najwyższej randze i ignoruje resztę: najpierw ustawienia zarządzane z serwera claude.ai, potem polityka MDM lub rejestru, dopiero potem te pliki. Jeśli firma już wysyła politykę przez konsolę claude.ai albo MDM, umieść blok sieciowy tam. /status pokazuje, którego źródła zarządzanego użyto, a które pominięto.
  • Błędny JSON zatrzymuje każdą sesję. Plik zarządzany, który nie parsuje się jako obiekt JSON, sprawia, że Claude Code odmawia startu i podaje nazwę pliku. Sprawdzaj plik poleceniem jq . 20-network.json w potoku, który go dostarcza.

Plik certyfikatu dostarcz pod tę samą ścieżkę na każdą maszynę narzędziami, którymi już rozsyłasz pliki po flocie — inaczej ustawienie wskazuje na nic. Profile MDM, ustawienia zarządzane z serwera i resztę bazowej polityki opisuje integracja z firmą. W kontenerach wpisz te same wartości do obrazu; przewodnik po dev containerach opisuje to razem z zaporą typu default-deny.

Przy starcie Claude Code sprawdza tylko adres proxy. Zła ścieżka certyfikatu wychodzi później, jako nieudane żądanie. Zamiast czekać na awarię, udowodnij, że każdy element się wczytał.

  1. Uruchom sesję z logiem debugowania zapisywanym do znanego pliku:

    Okno terminala
    claude --debug-file /tmp/claude-net.log

    Bez --debug-file polecenie claude --debug pisze do ~/.claude/debug/<session-id>.txt, a nie do terminala.

  2. Wyszukaj w logu wiersze potwierdzające wczytanie plików:

    Okno terminala
    grep -E "CA certs:|mTLS:|Failed to (read|load)" /tmp/claude-net.log

    Działająca konfiguracja wypisuje CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (...), a przy mTLS także mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT i analogiczny wiersz dla klucza. Wiersz Failed to read lub Failed to load podaje przyczynę.

  3. W sesji uruchom /status. Sprawdź, czy wskazuje wysłane przez ciebie źródło zarządzane. Wiersz Proxy pokazuje aktywny adres proxy i oznacza wartość, której nie da się sparsować. Wiersze mTLS client cert i mTLS client key pojawiają się tylko wtedy, gdy pliki się wczytały. Wiersz Additional CA cert(s) pokazuje ścieżkę bez sprawdzania pliku, więc w tej sprawie ufaj logowi.

  4. Uruchom w terminalu claude doctor, żeby sprawdzić stan instalacji i ustawień.

  5. Wyślij jeden prawdziwy prompt, na przykład Reply with OK. Odpowiedź dowodzi, że działa cała ścieżka: proxy, zaufanie i lista hostów.

We flocie zespół platformy wykonuje te kroki na maszynie kanarkowej po każdej zmianie sieciowego bloku managed settings i zatwierdza zmianę, zanim trafi do wszystkich. Developerzy robią to tylko wtedy, gdy przychodzi zgłoszenie.

Te prompty wymagają działającej sesji, więc uruchamiaj je na maszynie, która już się łączy: w sieci domowej, na skonfigurowanym laptopie kolegi albo w sesji, która dociera do modelu przez twoją bramkę.

Co widziszPrawdopodobna przyczynaCo zrobić
Unable to connect to Anthropic services przy pierwszym uruchomieniu, z A proxy is configured via HTTPS_PROXYProxy blokuje api.anthropic.com lub platform.claude.comPoproś IT o odblokowanie obu hostów; sprawdź curl -I https://api.anthropic.com z tej samej powłoki
Connection refused — a firewall or proxy may be blocking itBrak proxy w sieci, która go wymaga, albo zły port proxyUstaw HTTPS_PROXY; potwierdź host i port przez curl -x http://proxy.company.com:8080 -I https://api.anthropic.com
Couldn't connect through your proxy (ERR_PROXY_TUNNEL)Proxy odrzuciło tunel: złe poświadczenia albo host niedozwolonyPopraw poświadczenia w adresie albo poproś IT o dopuszczenie hosta
SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY) lub Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN)Inspekcja TLS z certyfikatem głównym, któremu Claude Code nie ufaDodaj certyfikat do magazynu systemowego albo ustaw NODE_EXTRA_CA_CERTS; przy instalacji z npm sprawdź, czy Node ma co najmniej 22.15
Claude Code nie startuje i wskazuje zmienną proxyAdresu proxy nie da się sparsować, najczęściej brakuje http://Dodaj schemat
curl działa, a Claude Code niePozostałość ANTHROPIC_BASE_URL wskazująca na niedziałającą bramkę albo https_proxy małymi literami przysłaniające poprawną wartośćUruchom echo $ANTHROPIC_BASE_URL, sprawdź bloki env w ustawieniach i usuń stare zmienne pisane małymi literami
Sesje interaktywne działają, agenci w tle nieZmienne sieciowe są tylko w profilu powłokiPrzenieś je do ~/.claude/settings.json, potem uruchom claude daemon stop --any
Streaming response ended before any complete data was received. Retrying without streaming.Proxy przechwytuje lub przepisuje strumieniowaną treść odpowiedzi, więc każde żądanie idzie dwa razyPoproś IT, żeby dla hosta API przepuszczało strumieniowane odpowiedzi i ich nagłówki bez zmian
Claude Code nie startuje i podaje nazwę pliku managed settingsPlik zarządzany nie jest poprawnym JSON-emPopraw plik na maszynie, a potem dodaj sprawdzenie jq do potoku, który go dostarcza
Blok sieciowy leży na dysku, ale /status nie pokazuje proxyPrzy first-wins wygrywa źródło o wyższej randze (konsola claude.ai albo MDM)Przenieś blok env do tego źródła albo omów managedSourcesBehavior z właścicielem polityki
Dostępne jest tylko proxy SOCKSClaude Code nie obsługuje SOCKS (v2.1.283)Poproś o regułę w proxy HTTP albo kieruj ruch przez bramkę LLM

Przy awariach niezwiązanych z siecią zacznij od rozwiązywania problemów z Claude Code.

Ta strona dotyczy tylko Claude Code. Codex od wydania 0.143.0 czyta systemową konfigurację proxy, w tym PAC i WPAD (według notatek wydania na GitHubie); zobacz konfigurację Codeksa. Ustawień sieciowych Cursora nie dało się 2026-09-26 zweryfikować na cursor.com, więc zanim wpiszesz je do planu wdrożenia, sprawdź jego własną dokumentację. Powyższa lista hostów dotyczy wyłącznie Claude Code: każde narzędzie potrzebuje hostów swojego dostawcy.