Come configurare HTTPS_PROXY per Cursor e Claude Code in una rete aziendale

Se la tua azienda blocca il traffico in uscita tramite un proxy aziendale, gli assistenti AI come Cursor e Claude Code smettono semplicemente di rispondere: l'autocompletamento si blocca, il CLI restituisce ETIMEDOUT o problema certificato SSL. Vediamo come configurare correttamente le variabili d'ambiente HTTPS_PROXY, impostare l'autenticazione e evitare errori comuni che portano gli sviluppatori a perdere ore nel debug delle impostazioni di rete anziché nel codice.

Perché gli assistenti AI hanno bisogno di un proxy in una rete aziendale

Cursor e Claude Code non sono modelli locali. Si connettono continuamente a API esterne: Cursor si collega ai suoi server di indicizzazione del codice e alle API dei modelli (OpenAI, Anthropic, Google a seconda del fornitore scelto), mentre Claude Code — direttamente all'API di Anthropic tramite HTTPS. In una rete aziendale, l'accesso diretto a Internet è spesso bloccato da un firewall, e tutto il traffico in uscita deve passare attraverso un server proxy (Squid, Zscaler, Blue Coat, Fortinet FortiProxy o un gateway aziendale interno). Senza variabili d'ambiente configurate correttamente, l'applicazione non sa che il traffico deve passare attraverso il proxy e tenta di connettersi a Internet direttamente, ricevendo timeout.

Una difficoltà aggiuntiva è che Cursor è costruito su Electron (essenzialmente Chromium + Node.js), mentre Claude Code è un 'applicazione CLI Node.js. Ognuno ha la propria logica per leggere le impostazioni del proxy: Electron eredita parzialmente le impostazioni di sistema del SO, mentre i processi Node.js leggono le variabili d'ambiente HTTP_PROXY/HTTPS_PROXY direttamente o tramite librerie come undici e node-fetch. Questo crea confusione: le impostazioni sono configurate, ma lo strumento non le "vede".

Variabili HTTP_PROXY, HTTPS_PROXY e NO_PROXY: come funziona

Il modo classico per specificare un proxy per applicazioni console Node.js, Python e Go è tramite variabili d'ambiente. La differenza tra HTTP_PROXY e HTTPS_PROXY è fondamentale: il primo è utilizzato per le richieste tramite il protocollo HTTP, il secondo — per le richieste HTTPS (e quasi tutto il traffico degli assistenti AI avviene tramite HTTPS). È consigliabile specificare entrambi, anche se il traffico effettivo è solo HTTPS — alcune librerie all'avvio effettuano richieste HTTP di servizio.

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"

Nota: anche per il traffico HTTPS, lo schema nell'indirizzo del proxy deve essere specificato come http://, e non https:// — questo è l'indirizzo del server proxy stesso, non della risorsa di destinazione. La connessione al proxy tramite HTTP è normale, la crittografia verso il server finale funziona comunque tramite il meccanismo di tunneling CONNECT.

La variabile NO_PROXY è necessaria per escludere gli indirizzi interni dell'azienda dalla proxy — altrimenti, le richieste ai repository git interni, Jira o ai servizi di sviluppo locali passeranno anch'esse attraverso il proxy esterno e potrebbero non essere trovate o rallentate. Un aspetto importante: alcune librerie sono sensibili al maiuscolo delle variabili. Per maggiore affidabilità, specifica entrambe le varianti — in maiuscolo e minuscolo:

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

Configurazione del proxy per Cursor

Cursor utilizza parzialmente le impostazioni proxy di sistema del SO (soprattutto su macOS e Windows), ma per un funzionamento stabile in una rete aziendale è meglio configurarlo esplicitamente tramite variabili d'ambiente e, se necessario, tramite il file di configurazione dell'applicazione.

Su macOS e Linux è più semplice aggiungere l'esportazione delle variabili nel file di profilo della shell, in modo che vengano caricate ad ogni avvio del terminale da cui viene avviato Cursor:

# ~/.zshrc o ~/.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"

Dopo aver modificato il file di profilo, esegui source ~/.zshrc e riavvia completamente Cursor (non basta ridurre a icona la finestra — termina il processo tramite Activity Monitor o Task Manager, poiché le applicazioni Electron memorizzano nella cache l'ambiente all'avvio).

Su Windows è più comodo impostare le variabili tramite le impostazioni di sistema (Pannello di controllo → Sistema → Impostazioni di sistema avanzate → Variabili d'ambiente) o tramite PowerShell per una conservazione permanente:

[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')

Se dopo questo Cursor non si connette ancora all'API dei modelli, controlla le impostazioni del proxy all'interno dell'applicazione stessa: Impostazioni → Rete (o Generale) — potrebbe esserci un campo Proxy URL separato, che sovrascrive le variabili di sistema. In alcune versioni di Cursor è anche necessario abilitare esplicitamente l'opzione "Usa le impostazioni proxy di sistema".

Configurazione del proxy per Claude Code

Claude Code è uno strumento CLI su Node.js, avviato tramite npm/npx, quindi legge direttamente le variabili d'ambiente dalla sessione del terminale in cui è stato invocato. Questo semplifica la configurazione: basta esportare le variabili prima dell'avvio.

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

Se esegui Claude Code come parte di un pipeline CI o da uno script, passa esplicitamente le variabili al comando di avvio, per evitare dipendenze dall'ambiente globale della shell:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "Controlla i test nel progetto"

Per una configurazione permanente, è più comodo fissare le variabili in un file .env nella radice del progetto e caricarlo tramite direnv o il supporto integrato per dotenv, se la tua shell lo supporta. Questo è particolarmente utile quando diversi progetti richiedono diverse impostazioni proxy (ad esempio, un progetto lavora con un'API interna, mentre un altro con servizi esterni).

Autenticazione su un proxy aziendale

La maggior parte dei proxy aziendali richiede autenticazione — Basic Auth, Digest o NTLM. Per Basic Auth, il login e la password possono essere incorporati direttamente nell'URL del proxy, come mostrato sopra: http://user:[email protected]:8080. Un aspetto importante — se nella password ci sono caratteri speciali (@, #, %), devono essere URL-codificati, altrimenti il parser della stringa del proxy si romperà al confine tra il login e l'host.

# Se la password è P@ssw0rd#2024, codifichiamo i caratteri speciali:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

È più complicato con l'autenticazione NTLM (spesso utilizzata in combinazione con Microsoft ISA Server, Forefront TMG o Fortinet) — Node.js e la maggior parte dei client HTTP non supportano NTLM "out of the box". In questo caso, la soluzione standard è sollevare un proxy intermedio locale, che si occupa dell'handshake NTLM, e poi fornisce un "pulito" HTTP proxy per l'applicazione. Per questo si usano spesso cntlm o px (proxy NTLM locale in Python). Lo schema è semplice: Cursor/Claude Code → localhost:3128 (cntlm) → proxy NTLM aziendale → internet.

# Esempio di configurazione cntlm (/etc/cntlm.conf)
Username    tuo_login
Domain      AZIENDA
Password    tua_password_o_hash
Proxy       proxy.company.local:8080
Listen      3128

# Dopo aver avviato cntlm, specifichiamo l'indirizzo locale:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

Certificati e MITM: problema SSL in una rete aziendale

Se in azienda è implementato un prodotto di classe Zscaler, Netskope o qualsiasi altro filtro web con ispezione SSL, il traffico viene decrittografato sul proxy e firmato con il certificato Root CA aziendale. Node.js (e quindi anche Claude Code, e gran parte dei moduli interni di Cursor) per impostazione predefinita si fida solo del proprio set integrato di certificati root e restituirà un errore UNABLE_TO_VERIFY_LEAF_SIGNATURE o certificato firmato da se nella catena di certificati.

La soluzione è esportare il certificato CA aziendale (di solito può essere ottenuto dal dipartimento IT o estratto dal deposito dei certificati del browser) e specificare a Node.js il percorso tramite la variabile NODE_EXTRA_CA_CERTS:

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

È fortemente sconsigliato disabilitare globalmente la verifica dei certificati tramite NODE_TLS_REJECT_UNAUTHORIZED=0 — questo rimuove la protezione contro gli attacchi MITM per l'intero processo, comprese le connessioni legittime. Usa questo flag solo per diagnosi una tantum e assicurati di ripristinare la protezione.

Errori comuni e le loro soluzioni

Errore	Causa	Soluzione
ETIMEDOUT / ECONNREFUSED	Le variabili proxy non sono esportate nella sessione in cui è in esecuzione l'applicazione	Controlla echo $HTTPS_PROXY nello stesso terminale, riavvia completamente l'applicazione
407 Proxy Authentication Required	Login/password non specificati o scaduti	Aggiorna le credenziali nella stringa del proxy, URL-codifica i caratteri speciali della password
certificato firmato da se nella catena di certificati	Il proxy MITM aziendale sostituisce il certificato	Specifica NODE_EXTRA_CA_CERTS con il Root CA aziendale
Il proxy funziona nel terminale, ma non in Cursor	Cursor è avviato da un terminale diverso o tramite un collegamento senza ambiente	Avviare Cursor con il comando dal terminale con le variabili esportate, oppure specificare le variabili globalmente nel sistema
NTLM authentication failed	Il client non supporta l'handshake NTLM	Sollevare un proxy intermedio cntlm o px tra l'applicazione e il proxy aziendale

Verifica della connessione tramite curl

Prima di capire perché Cursor o Claude Code non funzionano, assicurati che il proxy sia accessibile e che proxy correttamente il traffico HTTPS. Per questo usa curl — legge le stesse variabili d'ambiente e consente di localizzare rapidamente il problema senza avviare applicazioni pesanti.

# Verifica della disponibilità del proxy e dell'autenticazione
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# Verifica tenendo conto del certificato aziendale
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

Se curl riceve una risposta con successo (anche 401 o 403 — va bene, significa che l'handshake TLS è andato a buon fine), e Claude Code non si connette comunque — il problema non è nella rete, ma nel fatto che il processo non vede le variabili d'ambiente. Se curl restituisce anche un errore di certificato o timeout — il problema è a livello di rete o proxy, e gli strumenti non c'entrano.

Quando è necessario un proxy esterno invece di quello aziendale

A volte il compito non si limita all'accesso dalla rete aziendale verso l'esterno. Gli sviluppatori che testano integrazioni con API geolocalizzate, controllano il comportamento del servizio da diversi paesi o debug delle politiche di limitazione del rate dei fornitori di modelli, si trovano di fronte al fatto che il proxy aziendale restituisce lo stesso IP aziendale per tutte le richieste. In tali scenari è comodo far passare il traffico di test attraverso un proxy esterno parallelamente all'ambiente di lavoro principale.

Per sessioni di test stabili e a lungo termine con un rischio minimo di blocco per IP, sono adatti proxy residenziali — utilizzano indirizzi IP reali di provider domestici e sembrano traffico di utenti normali, il che è importante per controllare le risposte API geo-specifiche. Se è necessario riprodurre il comportamento di un client mobile o testare scenari sensibili al tipo di rete, vale la pena considerare proxy mobili. E per test paralleli massivi di richieste a API pubbliche, dove la velocità e il costo del traffico sono più importanti della mascheratura come utente normale, di solito sono sufficienti proxy di data center.

Importante: tale proxy esterno viene configurato esattamente allo stesso modo tramite le variabili HTTPS_PROXY/HTTP_PROXY, ma per un ambiente di test o un profilo di terminale separato, in modo da non mescolarlo con il traffico di lavoro principale tramite il gateway aziendale. Se la politica aziendale richiede che tutto il traffico dell'azienda passi solo attraverso il proxy interno, l'uso di un proxy esterno deve essere concordato con IT/Sicurezza — molte aziende vietano esplicitamente di aggirare il gateway aziendale senza autorizzazione.

Checklist di configurazione

Conclusione

La maggior parte dei problemi con Cursor e Claude Code dietro un proxy aziendale si riduce a tre cose: le variabili d'ambiente non raggiungono il processo, l'autenticazione è configurata in modo errato, oppure il certificato MITM aziendale non è stato aggiunto ai certificati fidati. Controllando questi tre punti in ordine — tramite curl, e non direttamente tramite l'applicazione — risparmi ore di debug e localizzi rapidamente la causa.

Se il compito va oltre la rete aziendale e hai bisogno di testare il comportamento delle API da diverse regioni o con diversi tipi di IP, ti consigliamo di provare proxy residenziali — forniscono un traffico stabile e meno sospetto per i servizi esterni rispetto agli indirizzi di data center normali.