Kurumsal Ağda Cursor ve Claude Code için HTTPS_PROXY Nasıl Ayarlanır

Şirketiniz çıkış trafiğini kurumsal proxy üzerinden kapatıyorsa, Cursor ve Claude Code gibi AI asistanları yanıt vermeyi durdurur: otomatik tamamlama takılır, CLI ETIMEDOUT veya SSL certificate problem hatası verir. Ortam değişkenlerini HTTPS_PROXY olarak doğru bir şekilde tanımlamayı, kimlik doğrulamasını ayarlamayı ve geliştiricilerin ağ ayarlarını kod yerine hata ayıklamak için saatler harcamasına neden olan yaygın hatalardan kaçınmayı inceleyelim.

Kurumsal ağda AI asistanlarına neden proxy gerekir

Cursor ve Claude Code yerel modeller değildir. Sürekli olarak dış API'lere başvururlar: Cursor, kod indeksleme sunucularına ve seçilen sağlayıcıya bağlı olarak OpenAI, Anthropic, Google gibi model API'lerine ulaşır; Claude Code ise doğrudan HTTPS üzerinden Anthropic API'sine erişir. Kurumsal ağda doğrudan internet erişimi genellikle bir güvenlik duvarı tarafından kapatılır ve tüm çıkış trafiği bir proxy sunucusu (Squid, Zscaler, Blue Coat, Fortinet FortiProxy veya iç kurumsal geçit) üzerinden gitmek zorundadır. Doğru ayarlanmış ortam değişkenleri olmadan, uygulama trafiğin proxy üzerinden yönlendirilmesi gerektiğini bilmez ve doğrudan internete erişmeye çalışır — zaman aşımı hatası alır.

Ayrı bir zorluk, Cursor'un Electron üzerinde inşa edilmiş olmasıdır (bu esasen Chromium + Node.js'dir), Claude Code ise bir Node.js CLI uygulamasıdır. Her birinin proxy ayarlarını okuma mantığı farklıdır: Electron kısmen sistemin ayarlarını miras alırken, Node.js süreçleri HTTP_PROXY/HTTPS_PROXY ortam değişkenlerini doğrudan veya undici ve node-fetch gibi kütüphaneler aracılığıyla okur. Bu da kafa karışıklığına neden olur: ayarlar tanımlanmıştır, ancak araç bunları "göremez".

HTTP_PROXY, HTTPS_PROXY ve NO_PROXY değişkenleri: nasıl çalışır

Konsol Node.js, Python ve Go uygulamaları için proxy belirtmenin klasik yolu, ortam değişkenleri aracılığıyladır. HTTP_PROXY ve HTTPS_PROXY arasındaki fark temeldir: ilki HTTP protokolü ile yapılan istekler için kullanılır, ikincisi ise HTTPS istekleri için (ve AI asistanlarının trafiğinin neredeyse tamamı HTTPS üzerinden geçmektedir). Her ikisini de belirtmek gerekir, gerçek trafik yalnızca HTTPS olsa bile — bazı kütüphaneler başlangıçta hizmet amaçlı HTTP istekleri yapar.

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"

Dikkat: HTTPS trafiği için bile proxy adresinde şema http:// olarak belirtilmelidir, https:// değil — bu, proxy sunucusunun adresidir, hedef kaynağın değil. Proxy ile HTTP üzerinden bağlantı kurmak normaldir, şifreleme yine de son sunucuya CONNECT tünelleme mekanizması aracılığıyla çalışır.

NO_PROXY değişkeni, şirketin iç adreslerini proxy'den hariç tutmak için gereklidir — aksi takdirde, iç git depolarına, Jira'ya veya yerel geliştirme hizmetlerine yapılan istekler de dış proxy üzerinden geçer ve ya bulunamaz ya da yavaşlar. Önemli bir nokta: bazı kütüphaneler değişkenlerin büyük/küçük harf duyarlıdır. Güvenilirlik için her iki versiyonu da belirtin — büyük ve küçük harflerle:

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

Cursor için proxy ayarları

Cursor, sistemin proxy ayarlarını kısmen kullanır (özellikle macOS ve Windows'ta), ancak kurumsal ağda stabil bir şekilde çalışması için ortam değişkenleri aracılığıyla açıkça ayarlanması ve gerekirse uygulama yapılandırma dosyası aracılığıyla yapılması daha iyidir.

macOS ve Linux'ta en kolay yol, ortam değişkenlerini her terminal açılışında alınması için kabuk profil dosyasına eklemektir, bu da Cursor'un başlatıldığı terminaldir:

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

Profil dosyasını değiştirdikten sonra source ~/.zshrc komutunu çalıştırın ve Cursor'u tamamen yeniden başlatın (sadece pencereyi küçültmekle kalmayın — süreci Activity Monitor veya görev yöneticisi aracılığıyla sonlandırın, çünkü Electron uygulamaları başlangıçta ortamı önbelleğe alır).

Windows'ta değişkenleri sistem ortam ayarları aracılığıyla (Denetim Masası → Sistem → Gelişmiş sistem ayarları → Ortam değişkenleri) veya PowerShell aracılığıyla kalıcı olarak ayarlamak daha uygundur:

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

Eğer bundan sonra Cursor hala model API'sine bağlanamıyorsa, uygulamanın içindeki proxy ayarlarını kontrol edin: Settings → Network (veya Genel) — orada sistem değişkenlerini geçersiz kılabilecek ayrı bir Proxy URL alanı olabilir. Bazı Cursor sürümlerinde "Sistem proxy ayarlarını kullan" seçeneğini açıkça etkinleştirmek de gerekebilir.

Claude Code için proxy ayarları

Claude Code, npm/npx aracılığıyla başlatılan bir Node.js CLI aracıdır, bu nedenle doğrudan çağrıldığı terminal oturumundan ortam değişkenlerini okur. Bu, ayarı basitleştirir: yalnızca başlatmadan önce değişkenleri dışa aktarmanız yeterlidir.

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

Eğer Claude Code'u bir CI boru hattının parçası olarak veya bir betikten çalıştırıyorsanız, başlatma komutuna değişkenleri açıkça iletin, böylece kabuk ortamına bağımlı kalmazsınız:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "Projede testleri kontrol et"

Kalıcı yapılandırma için, değişkenleri projenin kökünde .env dosyasında sabitlemek ve bunu direnv veya shell'inizin destekliyorsa yerleşik dotenv desteği aracılığıyla almak daha uygundur. Bu, farklı projelerin farklı proxy ayarlarına ihtiyaç duyduğu durumlarda özellikle kullanışlıdır (örneğin, bir proje iç API ile çalışırken, diğeri dış hizmetlerle çalışır).

Kurumsal proxy'de kimlik doğrulama

Çoğu kurumsal proxy kimlik doğrulaması gerektirir — Basic Auth, Digest veya NTLM. Basic Auth için kullanıcı adı ve şifre doğrudan proxy URL'sine entegre edilebilir, yukarıda gösterildiği gibi: http://user:[email protected]:8080. Önemli bir nokta — eğer şifrede özel karakterler varsa (@, #, %), bunları URL ile kodlamak gerekir, aksi takdirde proxy dizesinin ayrıştırıcı hatası oluşur.

# Eğer şifre P@ssw0rd#2024 ise, özel karakterleri kodlayın:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

NTLM kimlik doğrulaması ile daha karmaşık bir durum söz konusudur (genellikle Microsoft ISA Server, Forefront TMG veya Fortinet ile birlikte kullanılır) — Node.js ve çoğu HTTP istemcisi NTLM'yi "kutudan çıkar çıkmaz" desteklemez. Bu durumda standart çözüm, NTLM el sıkışmasını üstlenen yerel bir proxy aracı kurmak ve ardından uygulama için "temiz" bir HTTP proxy sağlamak olacaktır. Bunun için genellikle cntlm veya px (Python'da yerel NTLM proxy). Şema basittir: Cursor/Claude Code → localhost:3128 (cntlm) → kurumsal NTLM proxy → internet.

# cntlm yapılandırma örneği (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    şifreniz veya hash
Proxy       proxy.company.local:8080
Listen      3128

# cntlm başlatıldıktan sonra yerel adresi belirtiyoruz:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

Sertifikalar ve MITM: Kurumsal ağda SSL sorunu

Şirket içinde Zscaler, Netskope veya herhangi bir SSL denetimi yapan web filtre ürünü kuruluysa, trafik proxy üzerinde şifrelenir ve kurumsal Root CA sertifikası ile imzalanır. Node.js (yani Claude Code ve Cursor'un büyük kısmı) varsayılan olarak yalnızca kendi yerleşik kök sertifika setine güvenir ve UNABLE_TO_VERIFY_LEAF_SIGNATURE veya self signed certificate in certificate chain hatası verir.

Çözüm, kurumsal CA sertifikasını dışa aktarmaktır (genellikle IT departmanından alınabilir veya tarayıcı sertifika deposundan çıkarılabilir) ve Node.js'e bu sertifikanın yolunu NODE_EXTRA_CA_CERTS değişkeni aracılığıyla belirtmektir:

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

Sertifika doğrulamasını NODE_TLS_REJECT_UNAUTHORIZED=0 ile küresel olarak devre dışı bırakmak kesinlikle önerilmez — bu, tüm süreç için MITM saldırılarına karşı korumayı kaldırır, meşru bağlantılar dahil. Bu bayrağı yalnızca tek seferlik teşhis için kullanın ve korumayı geri döndürmeyi unutmayın.

Yaygın hatalar ve çözümleri

Hata	Sebep	Çözüm
ETIMEDOUT / ECONNREFUSED	Proxy değişkenleri, uygulamanın çalıştığı oturumda dışa aktarılmamış	Aynı terminalde echo $HTTPS_PROXY kontrol edin, uygulamayı tamamen yeniden başlatın
407 Proxy Authentication Required	Kullanıcı adı/şifre belirtilmemiş veya süresi dolmuş	Proxy dizesindeki kimlik bilgilerini güncelleyin, şifre özel karakterlerini URL ile kodlayın
self signed certificate in certificate chain	Kurumsal MITM proxy sertifikayı değiştiriyor	Kurumsal Root CA ile NODE_EXTRA_CA_CERTS belirtin
Proxy terminalde çalışıyor, ancak Cursor'da çalışmıyor	Cursor, o terminalden başlatılmamış veya ortam olmadan kısayoldan başlatılmış	Cursor'u dışa aktarılmış değişkenlerle terminalden başlatın veya değişkenleri sistemde küresel olarak tanımlayın
NTLM authentication failed	İstemci NTLM el sıkışmasını desteklemiyor	Uygulama ile kurumsal proxy arasında geçici bir cntlm veya px proxy kurun

curl ile bağlantı kontrolü

Cursor veya Claude Code'un neden çalışmadığını anlamadan önce, proxy'nin aslında erişilebilir olduğunu ve HTTPS trafiğini doğru bir şekilde proxy'lediğini kontrol edin. Bunun için curl kullanın — aynı ortam değişkenlerini okur ve ağır uygulamaları başlatmadan sorunu hızlı bir şekilde yerelleştirmenizi sağlar.

# Proxy ve kimlik doğrulama erişilebilirliğini kontrol etme
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# Kurumsal sertifika ile kontrol
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

Eğer curl başarılı bir yanıt alıyorsa (401 veya 403 bile olsa — bu normaldir, TLS el sıkışması başarılı oldu demektir) ve Claude Code hala bağlanamıyorsa — sorun ağda değil, sürecin ortam değişkenlerini görememesiyle ilgilidir. Eğer curl de sertifika hatası veya zaman aşımı hatası veriyorsa — sorun ağ veya proxy seviyesindedir ve araçların burada bir etkisi yoktur.

Kurumsal yerine dış proxy ne zaman gereklidir

Bazen görev, kurumsal ağdan dışarıya erişimle sınırlı değildir. Coğrafi bağımlı API'lerle entegrasyonları test eden geliştiriciler, hizmetin farklı ülkelerden davranışını kontrol ederken veya model sağlayıcılarının rate-limit politikalarını ayarlarken, kurumsal proxy'nin tüm istekler için aynı kurumsal IP'yi verdiğiyle karşılaşırlar. Bu tür senaryolar için, test trafiğini ana çalışma ortamıyla paralel olarak dış proxy üzerinden yönlendirmek uygundur.

Stabil, uzun ömürlü test oturumları için, IP bazında engellenme riski en az olan rezidans proxy'leri uygundur — bunlar gerçek ev sağlayıcılarının IP adreslerini kullanır ve normal kullanıcı trafiği gibi görünür, bu da API'nin coğrafi spesifik yanıtlarını kontrol ederken önemlidir. Eğer mobil istemcinin davranışını yeniden oluşturmanız veya ağ türüne duyarlı senaryoları test etmeniz gerekiyorsa, mobil proxy'leri düşünmelisiniz. Kamu API'lerine toplu paralel istek testleri için, hız ve trafik maliyeti önemli olduğunda, genellikle veri merkezi proxy'leri yeterlidir.

Önemli: bu tür bir dış proxy, HTTPS_PROXY/HTTP_PROXY değişkenleri aracılığıyla tam olarak aynı şekilde ayarlanır, ancak test ortamı veya ayrı bir terminal profili için, böylece kurumsal geçit üzerinden ana çalışma trafiği ile karışmaz. Eğer kurumsal politika, şirketin tüm trafiğinin yalnızca iç proxy üzerinden gitmesini gerektiriyorsa, dış proxy kullanımı IT/Güvenlik ile onaylanmalıdır — birçok şirket, izin olmadan kurumsal geçidi aşmayı açıkça yasaklamaktadır.

Ayar kontrol listesi

Sonuç

Cursor ve Claude Code ile kurumsal proxy arkasındaki çoğu sorun, üç şeye indirgenir: ortam değişkenleri sürece ulaşmaz, kimlik doğrulama yanlış ayarlanmıştır veya kurumsal MITM sertifikası güvenilirler listesine eklenmemiştir. Bu üç noktayı sırayla kontrol ederek — curl ile, doğrudan uygulama üzerinden değil — hata ayıklamak için saatler kazanır ve nedeni hızlı bir şekilde yerelleştirirsiniz.

Eğer görev kurumsal ağın ötesine geçiyorsa ve API'nin farklı bölgelerden veya farklı IP türlerinden davranışını test etmeniz gerekiyorsa, rezidans proxy'lerini denemenizi öneririz — bunlar, normal veri merkezi adreslerine kıyasla dış hizmetler için daha stabil ve daha az şüpheli bir trafik sağlar.