Konfigurasi jaringan enterprise

Konfigurasikan Claude Code untuk lingkungan enterprise dengan server proxy, Certificate Authorities (CA) kustom, dan autentikasi mutual Transport Layer Security (mTLS).

Claude Code mendukung berbagai konfigurasi jaringan dan keamanan enterprise melalui variabel lingkungan. Ini termasuk merutekan lalu lintas melalui server proxy perusahaan, mempercayai Certificate Authorities (CA) kustom, dan mengautentikasi dengan sertifikat mutual Transport Layer Security (mTLS) untuk keamanan yang ditingkatkan.

Atur variabel lingkungan ini sebelum Anda meluncurkan Claude Code. Variabel yang diekspor di shell Anda dibaca sekali saat startup, jadi sesi yang sedang berjalan tidak mengambil perubahan nanti ke lingkungan shell Anda.

Konfigurasi proxy

Variabel lingkungan

Claude Code menghormati variabel lingkungan proxy standar. Dalam sesi Claude Desktop di mana aplikasi mengelola koneksi penyedia, Claude Code membacanya hanya dari pengaturan terkelola dan ~/.claude/settings.json; lihat autentikasi mTLS untuk aturan cakupan.

# HTTPS proxy (direkomendasikan)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy (jika HTTPS tidak tersedia)
export HTTP_PROXY=http://proxy.example.com:8080

# Lewati proxy untuk permintaan tertentu - format terpisah spasi
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Lewati proxy untuk permintaan tertentu - format terpisah koma
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Lewati proxy untuk semua permintaan
export NO_PROXY="*"

Varian huruf kecil juga berfungsi, dan Claude Code menggunakan yang pertama yang diatur dalam urutan https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.

Claude Code tidak pernah mengirim koneksi WebSocket-nya ke localhost, ::1, atau 127.0.0.0/8 melalui proxy, jadi Anda tidak perlu entri loopback dalam NO_PROXY untuk mereka.

Autentikasi dasar

Jika proxy Anda memerlukan autentikasi dasar, sertakan kredensial dalam URL proxy:

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

Penyimpanan sertifikat CA

Secara default, Claude Code mempercayai baik sertifikat CA Mozilla yang disertakan maupun penyimpanan sertifikat sistem operasi Anda. Membaca penyimpanan OS memerlukan runtime dengan tls.getCACertificates: installer native selalu memilikinya, dan instalasi npm memerlukan Node 22.15 atau lebih baru. Pada versi Node yang lebih lama, hanya set yang disertakan dan NODE_EXTRA_CA_CERTS yang berlaku. Proxy inspeksi TLS enterprise bekerja tanpa konfigurasi tambahan ketika sertifikat akar mereka diinstal di penyimpanan kepercayaan OS dan runtime dapat membacanya.

CLAUDE_CODE_CERT_STORE menerima daftar sumber yang dipisahkan koma. Nilai yang dikenali adalah bundled untuk set CA Mozilla yang dikirimkan dengan Claude Code dan system untuk penyimpanan kepercayaan sistem operasi. Default adalah bundled,system.

Untuk mempercayai hanya set CA Mozilla yang disertakan:

export CLAUDE_CODE_CERT_STORE=bundled

Untuk mempercayai hanya penyimpanan sertifikat OS:

export CLAUDE_CODE_CERT_STORE=system

Sertifikat CA kustom

Jika lingkungan enterprise Anda menggunakan CA kustom, konfigurasikan Claude Code untuk mempercayainya secara langsung:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Autentikasi mTLS

Untuk lingkungan enterprise yang memerlukan autentikasi sertifikat klien:

# Sertifikat klien untuk autentikasi
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# Kunci privat klien
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# Opsional: Frasa sandi untuk kunci privat terenkripsi
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

Claude Code membaca file sertifikat dan kunci saat startup dan membacanya kembali setiap kali menerapkan pengaturan, seperti ketika organisasi Anda mengubah blok env dalam pengaturan terkelola di tengah sesi.

Untuk merotasi sertifikat dan kunci, ganti file di jalur yang sama. Claude Code mengambil penggantian dalam sesi yang sedang berjalan tanpa perlu restart. Ketika permintaan API gagal dengan kesalahan tingkat koneksi, seperti reset koneksi atau kesalahan handshake TLS, Claude Code membaca kembali kedua file dan mencoba ulang permintaan dengan pasangan baru. Sebelum v2.1.232, Claude Code tidak membaca ulang pada kesalahan koneksi, jadi Claude Code tetap menggunakan pasangan yang sudah dimuat sampai berikutnya menerapkan pengaturan atau Anda melakukan restart.

Claude Code membaca kembali file sebagai respons terhadap permintaan yang gagal, bukan dengan memantau perubahan file:

• Waktu: Claude Code tidak melakukan apa pun pada saat Anda mengganti file. Claude Code menyajikan pasangan baru pada percobaan ulang setelah kegagalan yang memenuhi syarat, atau pada permintaan berikutnya setelah menerapkan pengaturan, mana pun yang lebih dulu.
• Penolakan gateway: Claude Code membaca ulang ketika gateway Anda mereset koneksi atau menolak handshake TLS setelah berhenti menerima pasangan lama. Claude Code tidak membaca ulang ketika gateway menyelesaikan handshake dan menjawab dengan kesalahan HTTP. Dalam hal ini, Claude Code memuat pasangan baru ketika berikutnya menerapkan pengaturan atau ketika Anda melakukan restart.
• Rotasi setengah tertulis: ketika Claude Code membaca ulang saat rotasi Anda sedang dalam proses penulisan, seperti membaca sertifikat dan kunci yang tidak cocok satu sama lain, Claude Code tetap menggunakan pasangan sebelumnya dan membaca ulang pada kegagalan berikutnya.
• Pengekspor telemetri OTLP: Claude Code menyimpan sertifikat yang pengekspor dimuat pada penggunaan pertama, jadi restart Claude Code untuk sertifikat yang dirotasi agar dapat menjangkau kolektor telemetri Anda.
• Matikan pemuatan ulang: atur CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 untuk mematikan pembacaan ulang kesalahan koneksi. Claude Code kemudian mengambil file yang dirotasi hanya ketika berikutnya menerapkan pengaturan atau pada startup berikutnya.

Untuk mengonfirmasi Claude Code mengambil rotasi, mulai sesi dengan pencatatan debug dan cari Stale connection — reloaded rotated mTLS client material dalam log. Claude Code tidak mencatat baris ini ketika mengambil rotasi saat menerapkan pengaturan, jadi baris yang hilang saja tidak berarti rotasi gagal.

Ganti file sebelum pasangan saat ini kedaluwarsa sehingga Claude Code tidak memuat pasangan yang sudah kedaluwarsa pada startup berikutnya.

Dalam sesi cloud, lingkungan hosting mengelola koneksi ke API, jadi Claude Code mengabaikan variabel berikut ketika berasal dari blok env file pengaturan:

• CLAUDE_CODE_CLIENT_CERT
• CLAUDE_CODE_CLIENT_KEY
• CLAUDE_CODE_CLIENT_KEY_PASSPHRASE
• NODE_EXTRA_CA_CERTS
• NODE_TLS_REJECT_UNAUTHORIZED
• CLAUDE_CODE_OAUTH_SCOPES

Claude Code mencatat setiap kunci yang diabaikan dalam log debug sesi.

Dalam sesi Claude Desktop di mana aplikasi mengelola koneksi penyedia, seperti tab Code pada penyedia pihak ketiga dan sesi Cowork, Claude Code membaca variabel ini dan variabel proxy HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY hanya dari pengaturan terkelola dan ~/.claude/settings.json: Claude Code mengabaikannya dalam file pengaturan repositori sendiri, jadi repositori yang diperiksa tidak dapat mengalihkan jalur TLS atau proxy dari sesi yang kredensialnya berasal dari aplikasi. Dalam sesi tab Code lokal, SSH, atau WSL yang masuk melalui claude.ai, aplikasi tidak mengelola koneksi, dan Claude Code membaca variabel ini dari setiap cakupan pengaturan, seperti sesi terminal apa pun; sesi cloud mengikuti aturan sesi cloud di atas di mana pun Anda memulainya. Sebelum v2.1.217, Claude Code mengabaikan variabel ini dalam setiap file pengaturan ketika aplikasi mengelola koneksi.

Verifikasi konfigurasi Anda

Biasanya Anda mengetahui tentang alamat proxy yang salah atau jalur sertifikat yang buruk dari kesalahan koneksi atau sertifikat pada permintaan yang lebih lambat, karena Claude Code tidak memvalidasi sebagian besar pengaturan ini saat membacanya. Satu-satunya pengaturan yang diperiksa saat startup adalah URL proxy: ketika tidak dapat mengurai nilainya, seperti yang hilang skema http://, Claude Code menghentikan peluncuran dengan kesalahan yang menamai variabel untuk diperbaiki.

Untuk mengonfirmasi konfigurasi Anda dimuat sebelum Anda mengirim permintaan, mulai Claude Code dengan pencatatan debug:

claude --debug

Output debug masuk ke ~/.claude/debug/<session-id>.txt daripada terminal, atau ke jalur yang Anda atur dengan --debug-file <path>. Dalam log, cari baris yang mengonfirmasi setiap file dimuat:

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

Jika Claude Code tidak dapat membaca salah satu file ini, log menunjukkan baris Failed to read atau Failed to load dengan alasan sebagai gantinya.

Anda juga dapat menjalankan /status dalam sesi interaktif dan memeriksa baris-baris ini:

• Proxy: menampilkan URL proxy aktif, dan menandai nilai yang tidak dapat diurakannya sebagai tidak valid dan diabaikan.
• mTLS client cert dan mTLS client key: muncul hanya ketika file dimuat, jadi baris yang hilang berarti pemuatan gagal dan log debug memiliki alasannya.
• Additional CA cert(s): menampilkan jalur NODE_EXTRA_CA_CERTS tanpa memeriksa bahwa file dimuat, jadi konfirmasi yang satu ini dalam log debug.

Terapkan pengaturan jaringan ke agen latar belakang

Agen latar belakang tidak berjalan di dalam terminal yang mengirimnya. Proses supervisor per-pengguna dimulai sesuai permintaan, bertahan lebih lama dari shell Anda, dan menghosting setiap sesi claude agents, --bg, dan /background. Lihat Bagaimana sesi latar belakang dihosting. Ini mengubah cara konfigurasi di halaman ini mencapai sesi-sesi tersebut.

Atur variabel jaringan dalam pengaturan, bukan shell

Supervisor adalah satu proses yang dibagikan oleh setiap terminal. Supervisor mewarisi lingkungan dari shell mana pun yang memulainya terlebih dahulu, dan supervisor yang diinstal OS tidak menerima lingkungan shell sama sekali. Jika Anda mengekspor proxy, jalur CA, atau variabel mTLS hanya di shell Anda, variabel tersebut mencapai agen latar belakang ketika shell itu kebetulan cold-start supervisor, dan diam-diam tidak mencapai ketika shell yang berbeda melakukannya.

Letakkan variabel yang sama dalam blok env dari ~/.claude/settings.json atau pengaturan terkelola sebagai gantinya. Setiap variabel di halaman ini dapat diatur di sana, dan pengaturan adalah satu-satunya konfigurasi yang mencapai setiap sesi latar belakang di setiap mesin.

Konfigurasikan peluncur perusahaan sebagai pengaturan

Beberapa organisasi memerlukan setiap proses Claude Code dimulai melalui peluncur perusahaan yang menerapkan sandboxing, kontrol jaringan, atau injeksi kredensial. Supervisor dan pekerja-pekerjanya memulai Claude Code dari jalur tetap daripada mencari claude di PATH, sehingga setiap agen latar belakang melewati wrapper yang Anda tempatkan lebih awal di PATH.

Atur pengaturan processWrapper untuk menambahkan awalan supervisor, pekerja-pekerjanya, dan proses latar belakang lainnya yang tercantum di bawah Apa yang dicakup peluncur dengan peluncur Anda. Variabel lingkungan CLAUDE_CODE_PROCESS_WRAPPER yang setara mengambil prioritas ketika keduanya diatur, dan variabel tersebut tunduk pada aturan yang sama: berikan melalui pengaturan terkelola atau ~/.claude/settings.json, bukan ekspor shell. Jalankan Claude Code di balik peluncur perusahaan mencakup kontrak yang harus dipenuhi peluncur, apa yang dilakukan dan tidak dilakukan, dan cara menerapkannya.

Watchdog idle streaming

Claude Code menjalankan empat timer independen yang menghentikan respons model streaming ketika diam, sehingga koneksi yang mati gagal dan mencoba ulang alih-alih menggantung. Tenggat waktu byte pertama mencakup penantian header respons, sebelum ada respons yang tiba. Masing-masing dari tiga lainnya memantau respons langsung untuk sinyal yang berbeda.

Konfigurasikan timer dengan variabel-variabel ini, masing-masing dirinci dalam referensi variabel lingkungan:

• CLAUDE_ENABLE_STREAM_WATCHDOG dan CLAUDE_ENABLE_BYTE_WATCHDOG memaksa watchdog yang sesuai dengan 1 atau mematikan dengan 0, dalam koneksi yang tabel sebutkan; tidak ada variabel yang memperluas watchdog ke tipe koneksi yang tidak dicakupnya. CLAUDE_ENABLE_BYTE_WATCHDOG diatur ke 0 juga mematikan first-byte deadline.
• CLAUDE_STREAM_IDLE_TIMEOUT_MS menetapkan tenggat waktu kedua watchdog. Claude Code menaikkan nilai di bawah 5 menit menjadi 5 menit, dan membatasi nilai pada 30 menit untuk byte-level watchdog.
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS menetapkan tenggat waktu byte-level watchdog tanpa mengubah event-level watchdog, diklem antara 10 detik dan 30 menit, dan mengambil prioritas atas CLAUDE_STREAM_IDLE_TIMEOUT_MS untuk watchdog itu.
• CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS menetapkan first-byte deadline secara langsung. Biarkan tidak diatur dan Claude Code menggunakan tenggat waktu byte-level watchdog, sehingga CLAUDE_STREAM_IDLE_TIMEOUT_MS dan CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS juga mengubah deadline. Untuk klem, tunjangan unggah, batas API_TIMEOUT_MS, dan berapa lama percobaan ulang menunggu setelah penghentian tanpa respons, lihat No response from API.
• API_FORCE_IDLE_TIMEOUT diatur ke 0 mematikan body idle timeout, dan diatur ke 1 menghidupkannya untuk setiap penyedia. Watchdog berjalan independen darinya, jadi untuk membiarkan stream berhenti lebih lama dari ambang batas mereka, juga naikkan atau nonaktifkan mereka.

Ketika watchdog menghentikan stream yang macet, Claude Code memperlakukan penghentian sebagai kegagalan mid-stream, dan apa yang Anda lihat tergantung pada seberapa jauh respons telah sampai. Claude Code mencoba ulang permintaan atau mengakhiri giliran dengan kesalahan, menyimpan output yang selesai dan menampilkan pemberitahuan respons tidak lengkap, atau mengakhiri giliran secara normal. Percobaan ulang otomatis mengatakan di mana setiap hasil berlaku.

Dalam sesi non-interaktif, dan untuk respons subagent dalam sesi apa pun, Claude Code mungkin terlebih dahulu meminta Claude untuk melanjutkan respons yang dipotong; entri pemberitahuan itu mengatakan kapan itu terjadi dan kapan Anda masih melihat pemberitahuan.

Ketika first-byte deadline menyala, tidak ada respons yang telah dimulai, jadi tidak ada output parsial untuk disimpan. Untuk cara Claude Code mengirim ulang permintaan dan kapan giliran berakhir, lihat No response from API.

Persyaratan akses jaringan

Claude Code memerlukan akses ke URL berikut. Daftarkan URL ini dalam konfigurasi proxy dan aturan firewall Anda, terutama di lingkungan jaringan terkontainer atau terbatas. Pemeriksaan konektivitas pengaturan pertama kali menunjuk ke sini ketika tidak dapat menjangkau api.anthropic.com atau platform.claude.com; lihat Unable to connect to Anthropic services untuk pesan pemeriksaan dan langkah pemulihan.

Jika Anda menginstal Claude Code melalui npm atau mengelola distribusi biner Anda sendiri, pengguna akhir tidak memerlukan installer asli dan penggunaan auto-updater dari downloads.claude.ai, tetapi instalasi npm dan bun memerlukan registri paket mereka, registry.npmjs.org, kecuali organisasi Anda mencerminkannya. Penggunaan lain dalam tabel berlaku terlepas dari metode instalasi.

Dua host intake Datadog hanya membawa telemetri operasional opsional, dan pengaturan CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC menonaktifkan keduanya. Sesi pada penyedia pihak ketiga tidak pernah mengirim ke host ini, bahkan ketika platform menetapkan CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST dan metrik telemetri default aktif. Lihat Telemetry services untuk semua yang Claude Code kirim dan cara menonaktifkannya sebelum menyelesaikan daftar putih Anda.

Saat menggunakan Amazon Bedrock, Agent Platform Google Cloud, Microsoft Foundry, atau sesi Claude apps gateway yang masuk, lalu lintas model dan autentikasi menuju penyedia atau gateway Anda alih-alih api.anthropic.com, claude.ai, atau platform.claude.com. Alat WebFetch masih memanggil api.anthropic.com untuk domain safety check kecuali Anda menetapkan skipWebFetchPreflight: true dalam settings.

Saat merutekan melalui LLM gateway dengan ANTHROPIC_BASE_URL, pemeriksaan ketersediaan fast mode masih memanggil api.anthropic.com daripada URL dasar gateway. Pemeriksaan menghormati proxy HTTP yang dikonfigurasi, jadi di mana blokir jaringan adalah penyebabnya, entri daftar putih untuk api.anthropic.com dalam proxy adalah perbaikannya. Blokir jaringan hanya gagal pemeriksaan di mana host tidak dapat dijangkau bahkan melalui proxy, dan fast mode kemudian melaporkan kesalahan konektivitas. Kesalahan konektivitas yang sama muncul ketika pemeriksaan menyajikan kredensial yang dikeluarkan gateway yang ditolak Anthropic; daftar putih tidak membantu di sana, karena tidak ada yang diblokir. Lihat use fast mode behind proxies and LLM gateways untuk variabel yang memulihkannya.

Daftar putih IP organisasi dan egress proxy

Jika organisasi Anda memiliki IP allowlisting diaktifkan untuk Claude, rutekan bridge.claudeusercontent.com melalui egress proxy yang sama dengan claude.ai dan api.anthropic.com, misalnya dengan menempatkannya dalam segmen aplikasi Zscaler yang sama atau kebijakan steering Netskope. Jika Anda tidak dapat meroutekannya dengan cara itu, tambahkan alamat egress yang digunakan proxy Anda untuk host itu ke daftar putih IP organisasi Anda, tetapi hanya ketika alamat itu didedikasikan untuk organisasi Anda: rentang egress proxy bersama juga mengakui pelanggan lain dari vendor proxy.

Anthropic memeriksa koneksi ke bridge.claudeusercontent.com terhadap daftar putih IP organisasi Anda menggunakan alamat yang mereka tiba dari. Jika proxy Anda mengirim lalu lintas untuk host itu melalui alamat yang tidak ada di daftar putih itu, Claude Code tidak dapat terhubung ke ekstensi Claude in Chrome meskipun sisa Claude Code berfungsi.

Daftar putih GitHub dan firewall

Cloud sessions di lingkungan yang dihosting Anthropic dan Code Review terhubung ke repositori Anda dari infrastruktur yang dikelola Anthropic; sesi di lingkungan yang dihosting sendiri terhubung dari dalam jaringan Anda, kecuali runner memilih Anthropic git proxy, yang mengambil dari sisi Anthropic.

Jika organisasi GitHub Enterprise Cloud Anda membatasi akses berdasarkan alamat IP, aktifkan IP allow list inheritance untuk GitHub Apps yang diinstal dan juga tambahkan entri daftar putih untuk alamat IP keluar Anthropic. Warisan mencakup hanya permintaan yang dibuat Claude GitHub App sebagai instalasi, bukan permintaan yang dibuat atas nama pengguna Anda. Untuk firewall lain, lihat Anthropic API IP addresses.

Untuk instans GitHub Enterprise Server yang dihosting sendiri di belakang firewall, daftarkan putih alamat IP keluar Anthropic sehingga infrastruktur Anthropic dapat menjangkau host GHES Anda untuk mengkloning repositori dan memposting komentar ulasan. Sesi di lingkungan yang dihosting sendiri menjangkau host GHES Anda dari dalam jaringan Anda sebagai gantinya, jadi paparan itu hanya berlaku untuk sesi yang dihosting Anthropic, untuk alur pra-sesi yang dihosting seperti pemilih repositori, dan untuk runner yang dihosting sendiri yang memilih Anthropic git proxy, yang mengambil dari sisi Anthropic. Untuk host GHES yang hanya dapat dirutekan di dalam jaringan Anda, SCM connector membawa alur pra-sesi yang dihosting melalui koneksi keluar sebagai gantinya, jadi daftar putih tidak diperlukan untuk mereka.

Desktop dan claude.ai

Tabel sebelumnya mencakup CLI mandiri. Aplikasi Claude Desktop dan claude.ai di browser memuat kode aplikasi dan konten pengguna mereka dari host CDN Anthropic tambahan, termasuk assets-proxy.anthropic.com dan asal *.claudeusercontent.com lainnya yang melayani artifacts di aplikasi tersebut. Mengizinkan claude.ai sambil memblokir host tersebut menghasilkan halaman kosong daripada kesalahan. Lihat network access requirements di halaman Desktop.

Artifact yang memuat typeface dari Google Fonts juga meminta fonts.googleapis.com dan fonts.gstatic.com. Kedua host bersifat opsional. Jika Anda memblokir mereka, artifact merender dalam typeface fallback. Blokir dengan penolakan cepat daripada penjatuhan senyap sehingga permintaan font gagal segera daripada menunda render pertama halaman.

Artifact juga dapat memuat pustaka JavaScript, seperti React atau paket charting, dari cdnjs.cloudflare.com, cdn.jsdelivr.net, cdn.tailwindcss.com, dan code.jquery.com, dan dari tidak ada host eksternal lainnya. Jika Anda memblokir host tersebut, bagian dari artifact yang bergantung pada pustaka tidak berfungsi, dan tidak seperti font yang diblokir, pustaka yang diblokir tidak memiliki fallback. Blokir dengan penolakan cepat di sini juga, sehingga permintaan pustaka yang diblokir gagal sekaligus daripada menggantung sampai waktu habis.

Sumber daya tambahan

• File pengaturan dan urutan prioritas
• Referensi variabel lingkungan
• Panduan pemecahan masalah