Konfiguracja Proxy i VPN

Zainstalowałeś Claude Code, uwierzytelniłeś się i uruchomiłeś pierwszy prompt. Wisi przez trzydzieści sekund, potem wyrzuca ECONNREFUSED. Twoja sieć korporacyjna wymaga, aby cały ruch HTTPS przechodził przez proxy, a Claude Code o tym nie wie. Połowa developerów w Twoim zespole rezygnuje w tym momencie.

Ten przewodnik obejmuje każdy scenariusz sieciowy, z jakim możesz się spotkać w środowisku korporacyjnym, od prostych proxy HTTP po mTLS z niestandardowymi urzędami certyfikacji.

Co wynosisz z tego przewodnika

Działający Claude Code za proxy HTTP/HTTPS
Konfigurację niestandardowych certyfikatów CA dla korporacyjnej inspekcji TLS
Rozwiązywanie problemów z VPN dla konfiguracji split-tunnel i full-tunnel
Wzorce zmiennych środowiskowych działające we wszystkich narzędziach opartych na Node.js

Konfiguracja Proxy HTTP

Claude Code to aplikacja Node.js i respektuje standardowe zmienne środowiskowe proxy.

Podstawowa konfiguracja proxy

# Ustaw dla bieżącej sesji powłoki
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# Uruchom Claude Code
claude

Dla trwałej konfiguracji dodaj te zmienne do profilu powłoki (~/.bashrc, ~/.zshrc lub ~/.profile):

# W ~/.zshrc lub ~/.bashrc
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com,.internal"

Konfiguracja proxy do skopiowania dla ustawień Claude Code:

Dodaj do ustawień użytkownika w ~/.claude/settings.json:

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

Stosuje to proxy do każdej sesji Claude Code bez modyfikowania środowiska powłoki.

Proxy z uwierzytelnianiem

Jeśli Twoje proxy wymaga uwierzytelniania:

export HTTPS_PROXY="http://username:password@proxy.company.com:8080"

Dla proxy używających uwierzytelniania NTLM lub Kerberos zazwyczaj potrzebujesz lokalnego narzędzia proxy jak cntlm lub px:

# Zainstaluj i skonfiguruj cntlm
brew install cntlm  # macOS

# Skonfiguruj cntlm z danymi AD
# Następnie skieruj Claude Code na lokalne proxy cntlm
export HTTPS_PROXY="http://localhost:3128"

Niestandardowe certyfikaty CA

Wiele sieci korporacyjnych używa proxy z inspekcją TLS z niestandardowymi urzędami certyfikacji. Node.js domyślnie nie używa systemowego magazynu certyfikatów.

Dodawanie niestandardowych certyfikatów CA

# Wskaż Node.js na korporacyjny pakiet CA
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"

Konfiguracja certyfikatu do skopiowania:

# Znajdź swój korporacyjny certyfikat CA (typowe lokalizacje)
# macOS: Eksportuj z Keychain Access
# Linux: /etc/ssl/certs/ lub /usr/local/share/ca-certificates/

# Ustaw w profilu powłoki
export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/corporate-ca.pem"

# Lub w ustawieniach Claude Code
# ~/.claude/settings.json
{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corporate-ca.pem"
  }
}

Wydobywanie certyfikatów CA

Na macOS eksportuj z Keychain:

# Eksportuj wszystkie zaufane certyfikaty główne
security find-certificate -a -p /Library/Keychains/System.keychain > /tmp/corporate-cas.pem
security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain >> /tmp/corporate-cas.pem

Na Linuksie:

# Połącz certyfikaty systemowe z korporacyjnym
cat /etc/ssl/certs/ca-certificates.crt /path/to/corporate-ca.crt > /tmp/combined-cas.pem
export NODE_EXTRA_CA_CERTS="/tmp/combined-cas.pem"

Konfiguracje VPN

VPN Split-Tunnel

VPN-y split-tunnel kierują tylko ruch korporacyjny przez VPN. Wywołania API Claude Code idą do api.anthropic.com, które zazwyczaj są kierowane przez publiczny internet:

Jeśli api.anthropic.com nie znajduje się w tabeli tras VPN, działa bez konfiguracji proxy
Jeśli Twój VPN kieruje cały ruch (full tunnel), potrzebujesz powyższej konfiguracji proxy

VPN Full-Tunnel

VPN-y full-tunnel kierują cały ruch przez infrastrukturę korporacyjną. Prawie na pewno będziesz potrzebować:

Konfiguracji proxy (dla ruchu HTTP/HTTPS)
Niestandardowych certyfikatów CA (dla inspekcji TLS)
Rozdzielczości DNS dla api.anthropic.com przez korporacyjny DNS

Rozwiązywanie problemów z VPN

# Sprawdź, czy api.anthropic.com się rozwiązuje
nslookup api.anthropic.com

# Sprawdź, czy możesz dotrzeć do endpointu API
curl -v https://api.anthropic.com/v1/messages 2>&1 | head -30

# Sprawdź bieżące ustawienia proxy
env | grep -i proxy

# Testuj z trybem debug Claude Code
claude --debug "api"

Skrypt diagnostyczny do skopiowania dla problemów z proxy:

#!/bin/bash
echo "=== Proxy Environment ==="
env | grep -i proxy
echo ""
echo "=== CA Certificates ==="
echo "NODE_EXTRA_CA_CERTS: ${NODE_EXTRA_CA_CERTS:-not set}"
echo ""
echo "=== DNS Resolution ==="
nslookup api.anthropic.com 2>&1 | tail -5
echo ""
echo "=== Connection Test ==="
curl -s -o /dev/null -w "HTTP %{http_code} in %{time_total}s" https://api.anthropic.com/ 2>&1
echo ""

Zarządzana konfiguracja proxy

Dla wdrożenia w całej organizacji użyj zarządzanych ustawień, aby wymusić konfigurację proxy:

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

Wdróż to w lokalizacji zarządzanych ustawień dla Twojej platformy. Zobacz Integracja korporacyjna po szczegóły dotyczące lokalizacji plików zarządzanych ustawień.

Gdy to się psuje

ECONNREFUSED po konfiguracji proxy: URL proxy może być nieprawidłowy. Przetestuj za pomocą curl -x http://proxy.company.com:8080 https://api.anthropic.com/. Jeśli curl działa, ale Claude Code nie, sprawdź czy Twoje zmienne środowiskowe są wyeksportowane i widoczne dla procesu Claude Code.

Błędy certyfikatu SSL z proxy: Twoje proxy prawdopodobnie przeprowadza inspekcję TLS i musisz skonfigurować NODE_EXTRA_CA_CERTS. Zdobądź certyfikat CA od swojego działu IT.

Proxy działa dla curl, ale nie dla Claude Code: Node.js obsługuje proxy inaczej niż curl. Upewnij się, że używasz HTTPS_PROXY (nie tylko https_proxy — choć oba powinny działać, wersja wielką literą jest bardziej niezawodna w różnych narzędziach).

Timeout-y za VPN: VPN-y full-tunnel mogą dodać znaczne opóźnienie. Jeśli Claude Code dostaje timeout, sprawdź czy VPN dodaje więcej niż 2-3 sekundy RTT do api.anthropic.com.

Co dalej

Konfiguracja LLM Gateway — Kieruj przez bramy dostawców chmury zamiast bezpośredniego dostępu do API
Integracja korporacyjna — Zarządzane ustawienia dla wdrożenia proxy w całej organizacji
Monitoring i koszty — Zweryfikuj przepływ danych telemetrycznych przez Twoje proxy