Konfigurasi Jaringan Claude Code: Proxy, mTLS, dan Domain

Konfigurasi proxy korporat yang bekerja sempurna di terminal saya sama sekali tidak berpengaruh pada background agent, dan butuh waktu yang memalukan untuk memahami sebabnya. Proses supervisor yang menampung sesi background hidup lebih lama daripada shell yang memulainya, mewarisi shell mana pun yang kebetulan menyalakannya dari dingin, dan ketika dipasang sebagai service sama sekali tidak menerima environment shell. Export saya hanya sampai ke satu dari sekian tempat yang saya kira.

Konfigurasi jaringan enterprise untuk Claude Code sebagian besar berupa daftar variabel, dan bagian menariknya adalah tiga perilaku di sekitarnya: apa yang sebenarnya divalidasi dan kapan, di mana variabelnya harus tinggal supaya menjangkau semuanya, dan bagaimana rotasi sertifikat diambil. Tulisan ini membahas allowlist domain, variabel proxy dan TLS, jalur verifikasinya, serta watchdog streaming yang menentukan kapan koneksi yang senyap dinyatakan mati.

Allowlist-nya, dan entri yang mengejutkan orang

Dua entri di sini menjegal sebagian besar allowlist pertama. Host Console dibutuhkan bahkan untuk sign-in claude.ai, karena pertukaran, penyegaran, dan pencabutan token OAuth semuanya menuju ke sana — izinkan hanya host claude.ai dan autentikasinya berfungsi sampai sebuah token perlu disegarkan. Dan registry npm dibutuhkan untuk instalasi plugin serta MCP server mana pun yang diluncurkan lewat runner npm, bukan cuma untuk memasang CLI-nya sendiri.

# The allowlist. Blocking any of these breaks something
# specific, and the error rarely names the host.

api.anthropic.com        API requests, the WebFetch domain safety
                         check, feature flags, telemetry events
claude.ai                claude.ai account authentication
claude.com               sign-in page; pre-approved doc lookups
platform.claude.com      Console auth AND OAuth token exchange,
                         refresh and revocation — so claude.ai
                         sign-ins need it too
mcp-proxy.anthropic.com  claude.ai MCP connectors
downloads.claude.ai      plugin executables, native installer
                         and auto-updater
registry.npmjs.org       plugin installs, npx-launched MCP
                         servers, npm/bun installs of the CLI
storage.googleapis.com   plugin install counts and metadata
raw.githubusercontent.com  the changelog feed for release notes
code.claude.com          documentation lookups only

# Optional, and safe to block:
bridge.claudeusercontent.com     Claude in Chrome
*.frame.claudeusercontent.com    Artifact content reads
http-intake.logs.us5.datadoghq.com    operational telemetry
browser-intake-us5-datadoghq.com      operational error reports
formulae.brew.sh                 Homebrew update checks

Beberapa entri memang opsional dan aman dibuang. Dua host intake Datadog hanya membawa telemetri operasional dan laporan error, dan satu variabel mematikan keduanya. Bridge Chrome dan host konten artifact hanya dibutuhkan untuk fitur tersebut. Memblokir host dokumentasi hanya memengaruhi pencarian dokumentasi dan tidak lebih. Memutuskan itu semua dengan sengaja memberi Anda daftar yang jauh lebih pendek untuk dipertahankan.

Proxy dan TLS, dengan tiga sudut tajam

Variabelnya standar dan sebagian besar membosankan, dan justru itu yang membuat pengecualiannya layak dinyatakan lugas: proxy SOCKS sama sekali tidak didukung, proxy yang butuh NTLM atau Kerberos lebih baik ditangani LLM gateway yang memahaminya alih-alih oleh Claude Code, dan certificate store sistem operasi hanya bisa dibaca pada runtime yang mengeksposnya — native installer selalu bisa, instalasi npm butuh Node yang cukup baru.

# Standard variables. Lowercase variants also work; Claude
# Code uses the FIRST one set, in this order:
#   https_proxy  HTTPS_PROXY  http_proxy  HTTP_PROXY

HTTPS_PROXY=https://proxy.example.com:8080
NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Comma-separated also works. NO_PROXY="*" bypasses everything.

# SOCKS proxies are NOT supported.
# For NTLM or Kerberos, use an LLM gateway that speaks them.

# CA trust. Default is both, and reading the OS store needs a
# runtime with tls.getCACertificates — the native installer
# always has it, npm installs need Node 22.15 or later.
CLAUDE_CODE_CERT_STORE=bundled,system   # default
NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

# mTLS
CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="…"

Rotasi sertifikat terjadi saat gagal, bukan saat berubah

Claude Code membaca ulang client certificate dan key ketika menerapkan setting dan ketika sebuah request gagal di level koneksi, dan itu desain yang disengaja dengan konsekuensi yang layak diketahui:

• Tidak terjadi apa-apa pada saat Anda mengganti filenya. Pasangan baru disajikan pada percobaan ulang setelah kegagalan yang memenuhi syarat, atau pada penerapan setting berikutnya, mana pun yang lebih dulu.
• Gateway yang mereset koneksi atau menolak handshake memicu pembacaan ulang. Gateway yang menyelesaikan handshake lalu menjawab dengan error HTTP tidak.
• Kalau ia membaca ulang di tengah rotasi dan menemukan sertifikat serta key yang tidak berpasangan, ia mempertahankan pasangan sebelumnya dan mencoba lagi pada kegagalan berikutnya — jadi rotasi yang setengah tertulis menurun kualitasnya alih-alih rusak.
• Exporter telemetri mempertahankan sertifikat yang dimuatnya saat pertama dipakai, jadi sertifikat yang dirotasi baru sampai ke collector Anda setelah restart.

Memverifikasi, dan asimetri pada apa yang diperiksa

Hanya satu dari setting ini yang divalidasi ketika Claude Code membacanya. URL proxy yang tidak bisa diurainya menghentikan peluncuran dengan error yang menyebut variabel mana yang perlu diperbaiki. Selebihnya — path sertifikat yang keliru, key yang tak terbaca — baru muncul sebagai error koneksi atau sertifikat pada request berikutnya, dan itu pengalaman debug yang jauh lebih buruk sekaligus alasan untuk memverifikasi dengan sengaja alih-alih menunggu.

# Only ONE of these settings is validated at startup: the
# proxy URL. A value it cannot parse — one missing the scheme,
# say — stops launch with an error naming the variable. Every
# other setting here fails later, on a request.

claude --debug
# Output goes to ~/.claude/debug/<session-id>.txt, NOT the
# terminal. Override with --debug-file <path>. Look for:
#
#   CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS
#   mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
#   mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

/status
#   Proxy                  the active URL; marked invalid if unparseable
#   mTLS client cert/key   appear ONLY when the files loaded, so a
#                          missing row means the load failed
#   Additional CA cert(s)  shows the path WITHOUT checking it loaded —
#                          confirm this one in the debug log

Background agent butuh setting, bukan export

Inilah kegagalan yang saya ceritakan di awal, dan ia bersifat struktural, bukan bug. Background agent tidak berjalan di dalam terminal yang mengirimnya: sebuah proses supervisor per pengguna menyala sesuai kebutuhan, hidup lebih lama daripada shell Anda, dan menampung setiap sesi background. Ia mewarisi environment dari shell mana pun yang pertama menyalakannya, dan supervisor yang dipasang OS sama sekali tidak menerima environment shell.

Jadi variabel proxy, path CA, atau mTLS yang hanya di-export di shell Anda akan sampai ke background agent ketika shell itu kebetulan menyalakan supervisor dari dingin, dan diam-diam tidak sampai ketika shell lain yang melakukannya. Setiap variabel di halaman ini bisa disetel di blok environment sebuah file setting, dan setting adalah satu-satunya konfigurasi yang menjangkau setiap sesi background di setiap mesin. Pakai shell untuk eksperimen dan file setting untuk apa pun yang serius.

Tiga watchdog menentukan kapan stream yang senyap dinyatakan mati

Claude Code menjalankan timer independen yang membatalkan respons streaming yang mendadak senyap, sehingga koneksi mati gagal dan diulang alih-alih menggantung selamanya. Mereka mengamati sinyal berbeda, dan itulah sebabnya sebuah stream bisa selamat dari satu timer dan tidak dari yang lain.

Apa yang diamati tiap timer:

Di mana proxy diam-diam melakukan buffering

Satu batasan layak disampaikan kepada siapa pun yang mengelola proxy Anda, karena ia menghasilkan kegagalan yang terlihat seperti masalah Claude Code. Streaming sesi memakai server-sent events di atas HTTPS, dan proxy di jalurnya tidak boleh melakukan buffering pada respons. Proxy yang melakukan buffering menahan stream-nya sampai punya cukup data untuk diteruskan, watchdog level byte melihat tidak ada yang tiba, dan request-nya dibatalkan lalu diulang — berkali-kali, tanpa error yang menunjuk pada buffering.

Kehalusan sejenis berlaku untuk fast mode di balik gateway: pemeriksaan ketersediaannya tetap memanggil Anthropic API alih-alih base URL gateway Anda. Ia memang menghormati HTTP proxy yang dikonfigurasi, jadi bila penyebabnya blokir jaringan, satu entri allowlist di proxy adalah perbaikannya. Kalau pemeriksaan itu menyodorkan kredensial terbitan gateway yang ditolak Anthropic, Anda mendapat error konektivitas yang sama dan allowlist tidak akan menolong, karena sebenarnya tidak ada yang diblokir.

Aturan yang akan menyelamatkan sore saya itu pendek: letakkan variabel jaringan di file setting, jangan pernah di profil shell, karena setting adalah satu-satunya tempat yang menjangkau setiap permukaan termasuk supervisor background. Setelah itu, verifikasi lewat debug log alih-alih output status, ingat bahwa hanya URL proxy yang gagal cepat, dan beri tahu pengelola proxy Anda bahwa ia tidak boleh melakukan buffering — satu kalimat itu mencegah satu kelas kegagalan yang tampak seperti hal lain sama sekali.