Cara Mengatur HTTPS_PROXY untuk Cursor dan Claude Code di Jaringan Perusahaan

Jika perusahaan Anda menutup lalu lintas keluar melalui proxy perusahaan, asisten AI seperti Cursor dan Claude Code akan berhenti merespons: autocompletion macet, CLI mengeluarkan ETIMEDOUT atau masalah sertifikat SSL. Mari kita bahas cara yang benar untuk menulis variabel lingkungan HTTPS_PROXY, mengatur otentikasi, dan menghindari kesalahan umum yang membuat pengembang menghabiskan berjam-jam untuk mendebug pengaturan jaringan alih-alih kode.

Mengapa asisten AI membutuhkan proxy di jaringan perusahaan

Cursor dan Claude Code bukanlah model lokal. Mereka terus-menerus mengakses API eksternal: Cursor menghubungi server pengindeksan kode dan API model (OpenAI, Anthropic, Google tergantung pada penyedia yang dipilih), sementara Claude Code — langsung ke API Anthropic melalui HTTPS. Di jaringan perusahaan, akses langsung ke internet sering kali diblokir oleh firewall, dan seluruh lalu lintas keluar harus melalui server proxy (Squid, Zscaler, Blue Coat, Fortinet FortiProxy, atau gateway perusahaan internal). Tanpa variabel lingkungan yang diatur dengan benar, aplikasi tidak tahu bahwa lalu lintas harus diarahkan melalui proxy, dan mencoba menghubungi internet secara langsung — mendapatkan timeout.

Kesulitan tambahan adalah bahwa Cursor dibangun di atas Electron (pada dasarnya ini adalah Chromium + Node.js), sementara Claude Code adalah aplikasi CLI Node.js. Masing-masing memiliki logika sendiri dalam membaca pengaturan proxy: Electron sebagian mewarisi pengaturan sistem OS, sementara proses Node.js membaca variabel lingkungan HTTP_PROXY/HTTPS_PROXY secara langsung atau melalui pustaka seperti undici dan node-fetch. Ini menciptakan kebingungan: pengaturan sudah ditulis, tetapi alat tidak "melihat"nya.

Variabel HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY: bagaimana cara kerjanya

Cara klasik untuk menentukan proxy untuk aplikasi Node.js, Python, dan Go di konsol adalah melalui variabel lingkungan. Perbedaan antara HTTP_PROXY dan HTTPS_PROXY adalah prinsip: yang pertama digunakan untuk permintaan melalui protokol HTTP, yang kedua — untuk permintaan HTTPS (dan hampir seluruh lalu lintas asisten AI berjalan melalui HTTPS). Sebaiknya tentukan keduanya, bahkan jika lalu lintas sebenarnya hanya HTTPS — beberapa pustaka pada awalnya melakukan permintaan HTTP administratif.

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"

Harap dicatat: bahkan untuk lalu lintas HTTPS, skema dalam alamat proxy ditentukan sebagai http://, bukan https:// — ini adalah alamat server proxy itu sendiri, bukan sumber daya tujuan. Koneksi ke proxy melalui HTTP adalah hal yang normal, enkripsi ke server akhir tetap berfungsi melalui mekanisme tunneling CONNECT.

Variabel NO_PROXY diperlukan, untuk mengecualikan alamat internal perusahaan dari pemrosesan proxy — jika tidak, permintaan ke repositori git internal, Jira atau layanan pengembangan lokal juga akan melalui proxy eksternal dan mungkin tidak ditemukan atau melambat. Penting untuk dicatat: beberapa pustaka sensitif terhadap huruf besar dan kecil variabel. Untuk keandalan, tuliskan kedua versi — huruf besar dan kecil:

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

Pengaturan proxy untuk Cursor

Cursor sebagian menggunakan pengaturan proxy sistem OS (terutama di macOS dan Windows), tetapi untuk kerja yang stabil di jaringan perusahaan, lebih baik mengatur secara eksplisit melalui variabel lingkungan dan, jika perlu, melalui file konfigurasi aplikasi.

Di macOS dan Linux cara termudah adalah menambahkan ekspor variabel ke file profil shell, sehingga mereka diambil saat setiap kali terminal dibuka, dari mana Cursor diluncurkan:

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

Setelah mengubah file profil, jalankan source ~/.zshrc dan restart Cursor sepenuhnya (jangan hanya meminimalkan jendela — akhiri proses melalui Activity Monitor atau Task Manager, karena aplikasi Electron menyimpan cache lingkungan saat startup).

Di Windows variabel lebih mudah ditetapkan melalui pengaturan lingkungan sistem (Control Panel → System → Advanced system settings → Environment Variables) atau melalui PowerShell untuk penyimpanan permanen:

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

Jika setelah ini Cursor tetap tidak terhubung ke API model, periksa pengaturan proxy di dalam aplikasi itu sendiri: Settings → Network (atau General) — mungkin ada kolom Proxy URL terpisah yang menimpa variabel sistem. Di beberapa build Cursor, Anda juga perlu secara eksplisit mengaktifkan opsi "Gunakan pengaturan proxy sistem".

Pengaturan proxy untuk Claude Code

Claude Code adalah alat CLI di Node.js, yang dijalankan melalui npm/npx, sehingga ia langsung membaca variabel lingkungan dari sesi terminal di mana ia dipanggil. Ini menyederhanakan pengaturan: cukup ekspor variabel sebelum menjalankan.

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

Jika Anda menjalankan Claude Code sebagai bagian dari pipeline CI atau dari skrip, kirimkan variabel secara eksplisit dalam perintah peluncuran, untuk menghindari ketergantungan pada lingkungan shell global:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "Periksa tes di proyek"

Untuk konfigurasi permanen, lebih nyaman untuk menetapkan variabel di file .env di root proyek dan mengambilnya melalui direnv atau dukungan bawaan dotenv, jika shell Anda mendukungnya. Ini sangat nyaman ketika proyek yang berbeda memerlukan pengaturan proxy yang berbeda (misalnya, satu proyek bekerja dengan API internal, sementara yang lain — dengan layanan eksternal).

Otentikasi di proxy perusahaan

Sebagian besar proxy perusahaan memerlukan otentikasi — Basic Auth, Digest, atau NTLM. Untuk Basic Auth, login dan kata sandi dapat disematkan langsung ke dalam URL proxy, seperti yang ditunjukkan di atas: http://user:[email protected]:8080. Hal penting yang perlu diperhatikan — jika kata sandi mengandung karakter khusus (@, #, %), mereka perlu di-URL encode, jika tidak, parser string proxy akan rusak di batas login dan host.

# Jika kata sandi P@ssw0rd#2024, encode karakter khusus:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

Lebih rumit dengan otentikasi NTLM (sering digunakan bersama Microsoft ISA Server, Forefront TMG, atau Fortinet) — Node.js dan sebagian besar klien HTTP tidak mendukung NTLM "secara default". Dalam hal ini, solusi standar — mendirikan proxy perantara lokal yang menangani negosiasi NTLM, dan kemudian memberikan HTTP proxy "bersih" untuk aplikasi. Untuk ini, sering digunakan cntlm atau px (proxy NTLM lokal di Python). Skemanya sederhana: Cursor/Claude Code → localhost:3128 (cntlm) → proxy NTLM perusahaan → internet.

# Contoh konfigurasi cntlm (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    kata_sandi_atau_hash_Anda
Proxy       proxy.company.local:8080
Listen      3128

# Setelah menjalankan cntlm, tentukan alamat lokal:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

Sertifikat dan MITM: masalah SSL di jaringan perusahaan

Jika perusahaan menerapkan produk kelas Zscaler, Netskope, atau filter web lainnya dengan inspeksi SSL, lalu lintas didekripsi di proxy dan ditandatangani dengan sertifikat Root CA perusahaan. Node.js (dan berarti Claude Code, serta sebagian besar modul internal Cursor) secara default hanya mempercayai set sertifikat root yang terintegrasi dan akan mengeluarkan kesalahan UNABLE_TO_VERIFY_LEAF_SIGNATURE atau sertifikat yang ditandatangani sendiri dalam rantai sertifikat.

Solusinya adalah mengekspor sertifikat CA perusahaan (biasanya dapat diperoleh dari departemen TI atau diekspor dari penyimpanan sertifikat browser) dan menunjukkan Node.js jalur ke sana melalui variabel NODE_EXTRA_CA_CERTS:

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

Sangat tidak disarankan untuk menonaktifkan pemeriksaan sertifikat secara global melalui NODE_TLS_REJECT_UNAUTHORIZED=0 — ini menghilangkan perlindungan terhadap serangan MITM di seluruh proses, termasuk koneksi yang sah. Gunakan bendera ini hanya untuk diagnosis satu kali dan pastikan untuk mengembalikan perlindungan.

Kesalahan umum dan solusinya

Kesalahan	Penyebab	Solusi
ETIMEDOUT / ECONNREFUSED	Variabel proxy tidak diekspor di sesi di mana aplikasi dijalankan	Periksa echo $HTTPS_PROXY di terminal yang sama, restart aplikasi sepenuhnya
407 Proxy Authentication Required	Login/kata sandi tidak ditentukan atau sudah kadaluarsa	Perbarui kredensial di string proxy, URL-encode karakter khusus dalam kata sandi
sertifikat yang ditandatangani sendiri dalam rantai sertifikat	Proxy MITM perusahaan mengganti sertifikat	Tentukan NODE_EXTRA_CA_CERTS dengan Root CA perusahaan
Proxy berfungsi di terminal, tetapi tidak di Cursor	Cursor dijalankan tidak dari terminal yang sama atau melalui pintasan tanpa lingkungan	Jalankan Cursor dengan perintah dari terminal dengan variabel yang diekspor, atau tentukan variabel secara global di sistem
NTLM authentication failed	Klien tidak mendukung negosiasi NTLM	Mendirikan proxy perantara cntlm atau px antara aplikasi dan proxy perusahaan

Memeriksa koneksi melalui curl

Sebelum mencari tahu mengapa Cursor atau Claude Code tidak berfungsi, pastikan bahwa proxy itu sendiri dapat diakses dan memproses lalu lintas HTTPS dengan benar. Untuk ini, gunakan curl — ia membaca variabel lingkungan yang sama dan memungkinkan Anda dengan cepat mengidentifikasi masalah tanpa menjalankan aplikasi berat.

# Memeriksa ketersediaan proxy dan otentikasi
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# Memeriksa dengan sertifikat perusahaan
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

Jika curl berhasil mendapatkan respons (bahkan 401 atau 403 — itu normal, berarti negosiasi TLS berhasil), tetapi Claude Code tetap tidak terhubung — masalahnya bukan di jaringan, tetapi di proses yang tidak melihat variabel lingkungan. Namun, jika curl juga gagal dengan kesalahan sertifikat atau timeout — masalahnya ada di tingkat jaringan atau proxy, dan alat tidak ada hubungannya.

Kapan perlu menggunakan proxy eksternal daripada perusahaan

Terkadang tugas tidak terbatas pada akses dari jaringan perusahaan ke luar. Pengembang yang menguji integrasi dengan API yang bergantung pada lokasi, memeriksa perilaku layanan dari berbagai negara, atau menguji kebijakan rate-limit penyedia model, menghadapi kenyataan bahwa proxy perusahaan memberikan IP perusahaan yang sama untuk semua permintaan. Dalam skenario seperti itu, nyaman untuk mengalirkan lalu lintas pengujian melalui proxy eksternal bersamaan dengan lingkungan kerja utama.

Untuk sesi pengujian yang stabil dan tahan lama dengan risiko pemblokiran IP minimal, proxy residensial cocok — mereka menggunakan alamat IP nyata dari penyedia rumah dan terlihat seperti lalu lintas pengguna biasa, yang penting saat memeriksa respons API yang spesifik untuk lokasi. Jika perlu mereproduksi perilaku klien seluler atau menguji skenario yang sensitif terhadap jenis jaringan, pertimbangkan proxy seluler. Dan untuk pengujian massal paralel permintaan ke API publik, di mana kecepatan dan biaya lalu lintas lebih penting daripada menyamarkan diri sebagai pengguna biasa, biasanya cukup menggunakan proxy pusat data.

Penting: proxy eksternal seperti itu diatur dengan cara yang sama melalui variabel HTTPS_PROXY/HTTP_PROXY, tetapi untuk lingkungan pengujian atau profil terminal terpisah, agar tidak mencampurkannya dengan lalu lintas kerja utama melalui gateway perusahaan. Jika kebijakan perusahaan mengharuskan semua lalu lintas perusahaan hanya melalui proxy internal, penggunaan eksternal harus disetujui oleh TI/Keamanan — banyak perusahaan secara eksplisit melarang penghindaran gateway perusahaan tanpa izin.

Daftar periksa pengaturan

Kesimpulan

Sebagian besar masalah dengan Cursor dan Claude Code di balik proxy perusahaan berkisar pada tiga hal: variabel lingkungan tidak sampai ke proses, otentikasi diatur dengan salah, atau sertifikat MITM perusahaan tidak ditambahkan ke yang dipercaya. Dengan memeriksa ketiga poin ini secara berurutan — melalui curl, bukan langsung melalui aplikasi itu sendiri — Anda menghemat berjam-jam untuk mendebug dan dengan cepat mengidentifikasi penyebabnya.

Namun, jika tugas melampaui jaringan perusahaan dan Anda perlu menguji perilaku API dari berbagai wilayah atau dengan berbagai jenis IP, kami sarankan untuk mencoba proxy residensial — mereka memberikan lalu lintas yang stabil dan kurang mencurigakan untuk layanan eksternal dibandingkan dengan alamat pusat data biasa.