Luncurkan gateway LLM untuk organisasi Anda

Terapkan produk gateway untuk Claude Code: konfigurasikan untuk meneruskan apa yang dikirim Claude Code, keluarkan kredensial pengembang, distribusikan konfigurasi melalui pengaturan terkelola, dan verifikasi peluncuran.

Halaman ini memandu administrator melalui peluncuran gateway LLM untuk Claude Code. Halaman ini mengasumsikan Anda memiliki produk gateway yang diterapkan yang memenuhi persyaratan gateway. Penerapan atau pengoperasian produk spesifik apa pun tidak tercakup di sini; terapkan milik Anda mengikuti dokumentasi vendor.

Prasyarat

Untuk menyelesaikan peluncuran, Anda akan memerlukan:

• Gateway yang diterapkan di infrastruktur Anda, melayani HTTPS di alamat yang tepat yang akan Anda distribusikan kepada pengembang, bukan alamat yang mengalihkannya, dan dikonfigurasi untuk merutekan nama model Claude ke penyedia Anda
• Kredensial penyedia untuk gateway yang akan diteruskan dengan:
  • Untuk API Anthropic: kunci API dari Konsol Claude
  • Untuk penyedia cloud: kredensial cloud dengan akses model. Lihat prasyarat di halaman Amazon Bedrock, Google Cloud's Agent Platform, atau Microsoft Foundry
• Cara untuk mengirimkan file pengaturan ke mesin pengembang, seperti MDM atau manajemen konfigurasi
  • Jika Anda belum memilikinya, bagaimana pengaturan mencapai perangkat membandingkan opsi

Persyaratan gateway

Produk apa pun yang menyediakan gateway harus:

• Terima format API yang didukung: salah satu format dalam tabel format API. Langkah peluncuran di bawah mengasumsikan API Pesan Anthropic di POST /v1/messages, yang dilayani sebagian besar gateway
• Alirkan respons: teruskan peristiwa yang dikirim server saat tiba, termasuk ping keep-alive, daripada membuffer seluruh respons; streaming mencakup apa yang buffering atau ping yang dilucuti rusak
• Rutekan nama model Claude: petakan setiap nama yang digunakan pengembang ke model upstream. Claude Code mengirimkan nama model seperti claude-sonnet-4-6 di setiap permintaan; di sebagian besar produk gateway pemetaan adalah daftar model atau tabel perutean dalam konfigurasi gateway sendiri
• Teruskan header dan body tanpa perubahan: teruskan anthropic-beta, anthropic-version, dan badan permintaan di kedua arah; tabel pass-through fitur memetakan masing-masing ke fitur yang rusak tanpanya
• Kembalikan kesalahan upstream tanpa modifikasi: pemulihan otomatis Claude Code cocok dengan kata-kata kesalahan, jadi membungkus kesalahan dalam amplop gateway sendiri memecahnya, kecuali amplop pesan membawa salah satu token capability_rejected: yang gateway aplikasi Claude menggantikan untuk kata-kata kesalahan penyedia cloud
• Bebaskan jalur dari inspeksi WAF badan permintaan: prompt Claude Code membawa kode sumber dan tag gaya XML yang cocok dengan aturan badan cross-site-scripting; WAF di depan gateway mengembalikan 403 pada sesi nyata sementara permintaan uji pendek lulus

Secara opsional, layani GET /v1/models sehingga Claude Code dapat mengisi pemilih model dari gateway Anda dengan penemuan model.

Langkah peluncuran

Peluncuran membutuhkan lima langkah, masing-masing dengan checkpoint:

1. Konfirmasi gateway merutekan model Anda
2. Keluarkan kredensial untuk setiap pengembang
3. Uji Claude Code terhadap gateway
4. Distribusikan URL dasar dan kredensial
5. Verifikasi dari mesin pengembang

Langkah-langkah melibatkan tiga kredensial berbeda, dan checkpoint menamai mereka dengan placeholder sehingga Anda dapat mengetahui mana yang salah ketika sesuatu gagal:

Konfirmasi gateway merutekan model Anda

Gateway Anda seharusnya sudah dikonfigurasi dengan kredensial penyedia Anda, mendengarkan di URL dasarnya, dan meneruskan permintaan ke API penyedia Anda. Uji bahwa jalur berfungsi end-to-end dengan permintaan minimal, mengganti dua nilai dari penerapan Anda:

• <gateway-key> adalah kredensial apa pun yang memungkinkan Anda memanggil gateway sekarang: kunci administratif, kunci uji, atau kunci pengembang Anda sendiri jika Anda sudah mengeluarkan satu. Tidak setiap produk gateway memiliki kredensial admin terpisah; jika milik Anda tidak, keluarkan kunci pengembang untuk diri sendiri di Keluarkan kredensial pengembang terlebih dahulu
• model adalah nama model Claude yang dikonfigurasi gateway untuk dirutekan. Contoh menggunakan claude-sonnet-4-6; ganti dengan nama yang telah Anda konfigurasi

curl -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <gateway-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
-Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Checkpoint: 200 dengan bidang content berarti gateway mencapai penyedia dengan nama model itu. 404 berarti nama itu tidak dirutekan di gateway; 401 dari penyedia berarti kredensial penyedia gateway salah.

Ulangi permintaan sekali per nama model Claude dalam konfigurasi perutean gateway Anda. Nama yang tidak dirutekan gateway mengembalikan 404 kepada pengembang mana pun yang memilihnya, jadi uji setiap nama sebelum peluncuran.

Keluarkan kredensial pengembang

Setiap pengembang memerlukan kunci gateway mereka sendiri untuk autentikasi. Buat kredensial per pengembang di gateway, mengikuti dokumentasi manajemen kredensial produk Anda.

Konfirmasi kunci yang baru dikeluarkan berfungsi terhadap gateway dengan permintaan yang sama seperti Konfirmasi gateway merutekan model Anda, mengganti <gateway-key> dengan <developer-key> baru:

curl -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <developer-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
-Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
-ContentType "application/json" `
-Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Checkpoint: 200 dengan bidang content berarti kunci pengembang mencapai gateway dan gateway meneruskannya. 401 di sini, ketika langkah sebelumnya berhasil, berarti kunci pengembang salah atau belum berlaku di gateway.

Mengeluarkan satu kunci per pengembang daripada kunci bersama adalah apa yang membuat atribusi penggunaan per pengembang dan offboarding individual berfungsi. Variabel lingkungan yang menyimpan kunci tergantung pada header mana yang dibaca gateway. Untuk gateway yang memeriksa kredensial di header Authorization: Bearer, pengembang menetapkan kunci mereka di ANTHROPIC_AUTH_TOKEN. Untuk gateway yang membaca kunci dari header x-api-key, pengembang menetapkan ANTHROPIC_API_KEY sebagai gantinya; tabel kredensial mencakup pemetaan.

Uji Claude Code terhadap gateway

Jalankan Claude Code melalui gateway sendiri sebelum mendistribusikan apa pun, menggunakan konfigurasi yang sama dengan yang akan didistribusikan peluncuran di seluruh armada. Ketik ini langsung di terminal, bukan di file .env atau pengaturan; mereka hanya berlaku untuk sesi terminal ini, jadi menutupnya mengembalikan mesin Anda ke konfigurasi normalnya. Gunakan ANTHROPIC_API_KEY daripada ANTHROPIC_AUTH_TOKEN jika gateway Anda membaca header x-api-key:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "<developer-key>"

Kemudian kirim prompt satu kali melalui gateway:

claude -p "Reply with one word: connected"

Checkpoint: prompt mengembalikan respons, dan permintaan muncul dalam log gateway sebagai POST ke jalur /v1/messages dengan status 200. Claude Code menambahkan string kueri seperti ?beta=true, jadi cocokkan pada jalur, bukan URL lengkap. Dua pesan kegagalan menunjuk ke arah berbeda:

• Not logged in: periksa log gateway untuk membedakan dua penyebab. Jika kosong, tidak ada kredensial yang mencapai sesi dan tidak ada permintaan yang meninggalkan mesin; jalankan kembali ekspor di shell yang Anda uji. Jika menunjukkan permintaan yang ditolak dengan x-api-key dalam badan 401, gateway mengharapkan kunci di header itu; beralih ke ANTHROPIC_API_KEY
• Failed to authenticate. API Error: 401 berarti kredensial dikirim dan ditolak, dan log gateway mengatakan di mana: 401 yang menyebutkan api.anthropic.com atau endpoint penyedia Anda berarti gateway mencapai upstream tetapi kredensial penyedia yang dipegang gateway ditolak, jadi kunci pengembang bekerja dan kredensial penyedia yang dipegang gateway salah atau placeholder

URL dasar yang salah atau tidak dapat dijangkau menghasilkan gejala berbeda: Claude Code mencoba ulang koneksi dengan backoff dan dapat duduk tanpa output selama beberapa menit sebelum melaporkan kesalahan. Jika perintah tampak hang, periksa log gateway daripada menunggu; tidak ada permintaan yang tiba berarti ANTHROPIC_BASE_URL tidak menunjuk ke gateway.

Distribusikan konfigurasi

Setiap mesin pengembang memerlukan alamat gateway dan kredensial. Anda dapat mendistribusikannya secara terpusat melalui pengaturan terkelola, sehingga pengembang tidak mengonfigurasi apa pun, atau berikan pengembang nilai untuk menetapkan sendiri.

Apa yang harus didistribusikan

Set variabel yang sama berlaku jalur mana pun yang Anda pilih. Sebagian besar peluncuran hanya memerlukan ANTHROPIC_BASE_URL dan kredensial; sertakan baris bersyarat ketika pengaturan gateway Anda memanggilnya.

Distribusikan melalui pengaturan terkelola

Berikan variabel melalui blok env dari file pengaturan terkelola, didorong oleh MDM, kebijakan registri, atau manajemen konfigurasi:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

Tambahkan variabel bersyarat dari tabel ke blok env yang sama. ANTHROPIC_BASE_URL yang dikelola diberlakukan dan tidak dapat ditimpa oleh ekspor shell pengembang, karena Claude Code menerapkannya di atas lingkungan proses dan pengaturan prioritas lebih rendah.

Jangan sertakan forceLoginMethod atau forceLoginOrgUUID dalam pengaturan terkelola bersama kredensial gateway. Salah satu kunci, dengan nilai apa pun, memblokir ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, dan apiKeyHelper saat startup, dan pengembang tidak dapat melanjutkan. Mereka melihat This machine's managed settings require a first-party login, atau Administrator policy requires a Cloud gateway sign-in di bawah nilai "gateway".

Pengiriman pengaturan terkelola server memerlukan koneksi langsung ke api.anthropic.com, sehingga tidak mencapai sesi yang dirutekan gateway. Penerapan gateway menggunakan jalur pengaturan terkelola berbasis file ini, yang memberlakukan kunci yang sama.

Untuk kredensial, distribusikan satu perintah apiKeyHelper dalam file pengaturan terkelola seperti yang ditunjukkan di atas; perintah mengautentikasi ke penyimpanan rahasia Anda sebagai pengembang lokal, sehingga setiap mesin menerima kuncinya sendiri. Alternatifnya, berikan setiap pengembang kunci mereka melalui proses rahasia yang ada dan minta mereka menetapkan ANTHROPIC_AUTH_TOKEN sendiri.

Beberapa lingkungan memerlukan pengiriman terpisah:

• Aplikasi desktop membaca perutean gateway dari konfigurasi inferensi pihak ketiga, bukan dari pengaturan terkelola; terapkan file itu melalui MDM bersama pengaturan terkelola sehingga sesi desktop juga merutekan melalui gateway. Lihat dokumentasi konfigurasi pihak ketiga desktop dan dokumentasi gateway desktop
• Runner CI memerlukan ANTHROPIC_BASE_URL dan kredensial yang ditetapkan di lingkungan runner
• WSL pada mesin Windows terkelola membaca pengaturan terkelola Windows hanya ketika wslInheritsWindowsSettings adalah true

Berikan pengembang nilai untuk menetapkan sendiri

Jika Anda tidak memiliki distribusi pengaturan terkelola, kirim setiap pengembang apa yang mereka butuhkan untuk mengikuti halaman koneksi:

• URL gateway
• Kredensial pribadi mereka
• Variabel mana yang harus dimasukkan kredensial: ANTHROPIC_AUTH_TOKEN untuk gateway token-bearer, atau ANTHROPIC_API_KEY untuk gateway x-api-key. Memberitahu pengembang mana yang menghemat mereka dari trial-and-error yang dijelaskan di halaman koneksi
• Variabel bersyarat apa pun dari tabel Apa yang harus didistribusikan, dengan nilainya

Halaman koneksi memandu pengembang melalui pengaturan masing-masing.

Checkpoint: pada mesin pengembang, claude memulai sesi tanpa menampilkan layar login, karena kredensial yang didistribusikan memenuhi autentikasi. Kemudian jalankan /status dan buka tab Status: baris Anthropic base URL menunjukkan alamat gateway, dan untuk distribusi terkelola baris Setting sources mencakup pengaturan terkelola. Layar login, atau baris Anthropic base URL yang hilang, berarti konfigurasi tidak mencapai mesin.

Verifikasi peluncuran

Konfirmasi semuanya berfungsi dari mesin pengembang, bukan host gateway, sehingga tes mencakup jalur jaringan yang digunakan pengembang. Kirim permintaan streaming, yang memeriksa endpoint, pass-through streaming, dan perutean model sekaligus:

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
-H "Authorization: Bearer <developer-key>" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
-H "Authorization: Bearer <developer-key>" `
-H "anthropic-version: 2023-06-01" `
-H "content-type: application/json" `
--data-binary '@-'

Anda seharusnya melihat baris data: tiba secara bertahap. Seluruh respons tiba sekaligus setelah jeda berarti gateway membuffer, yang menghentikan Claude Code; 404 berarti nama model tidak dirutekan. Ulangi per nama model.

Kemudian mulai claude dan kirim pesan. Setiap gejala pada langkah ini memiliki satu penyebab:

• Prompt login berarti celah kredensial. Jalankan /status dan buka tab Status: ketika baris Setting sources tidak mencakup pengaturan terkelola, distribusi tidak mencapai mesin; ketika itu terjadi, kredensial pengembang tidak dikirimkan, jadi atur ANTHROPIC_AUTH_TOKEN atau apiKeyHelper
• Kesalahan Failed to authenticate berarti gateway menolak permintaan; lognya mengatakan kredensial mana yang gagal. Penolakan yang dicatat gateway sendiri menyebutkan kunci pengembang, sementara 401 dari api.anthropic.com atau endpoint penyedia Anda berarti kredensial penyedia yang dipegang gateway ditolak
• Prompt persetujuan satu kali untuk kunci diharapkan pada penggunaan pertama ketika gateway mengharapkan kunci di header x-api-key, ditetapkan sebagai ANTHROPIC_API_KEY. Dengan ANTHROPIC_AUTH_TOKEN, tidak ada prompt yang muncul dan variabel mengambil alih secara diam-diam; login claude.ai yang sebelumnya disimpan tidak aktif untuk sesi itu

Jika organisasi Anda menggunakan fast mode, jalankan /fast di sini juga: pemeriksaan ketersediaan memanggil api.anthropic.com secara langsung daripada mengikuti URL dasar gateway, sehingga sesi yang dirutekan gateway dapat melaporkan fast mode sebagai tidak tersedia atau dinonaktifkan meskipun inferensi berfungsi. Gunakan fast mode di belakang proxy dan gateway LLM memetakan setiap pesan ke variabel yang mengembalikannya, didistribusikan dengan sisa konfigurasi.

Terakhir, periksa log gateway untuk pesan yang Anda kirim: kredensial mengidentifikasi pengembang, dan header x-claude-code-session-id mengelompokkan permintaan berdasarkan sesi. Jika fitur gagal dengan gejala pemecahan masalah, gateway menghapus header atau menulis ulang kesalahan; lihat persyaratan gateway di atas.

Pertahankan gateway

Setelah peluncuran, tiga jenis perubahan mencapai gateway seiring waktu. Masing-masing memiliki gejala untuk diperhatikan dan tindakan yang harus diambil.

Saat mengukur batas laju per kunci, akun untuk klien mencoba ulang kegagalan transien, termasuk respons 429, hingga 10 kali dengan backoff, menghormati Retry-After. Simpan panduan kompatibilitas sebagai referensi untuk apa yang dikirim setiap rilis Claude Code.

Rencanakan upgrade versi Claude Code

Beberapa perilaku Claude Code dibangun ke dalam versi yang diinstal daripada diatur di gateway Anda, jadi memindahkan pengembang ke rilis baru dapat mengubah perilaku di seluruh deployment Anda bahkan ketika konfigurasi gateway belum berubah. Untuk mengontrol kapan itu terjadi, pin pengembang ke versi yang telah diuji dengan requiredMaximumVersion, atau dengan DISABLE_UPDATES jika Anda mendistribusikan Claude Code melalui saluran Anda sendiri. Sebelum Anda menaikkan pin, baca entri changelog rilis baru dan uji terhadap gateway.

Ketika Anda menguji rilis, header baru atau bidang permintaan yang ditolak gateway muncul sebagai kesalahan 400 yang dijelaskan dalam Pertahankan gateway. Tabel di bawah mencakup perubahan yang bergantung pada versi yang tidak menghasilkan kesalahan, dengan pengaturan yang membuat masing-masing tetap konstan di seluruh upgrade.

Sumber daya terkait

• Hubungkan Claude Code ke gateway LLM: langkah pengaturan yang menghadap pengembang, dengan konfigurasi per-permukaan dan tabel pemecahan masalah yang dapat Anda berikan kepada pengembang
• Panduan kompatibilitas gateway: referensi untuk operator gateway, mencakup endpoint, header untuk diteruskan, dan tabel pass-through fitur
• Nilai mana yang digunakan Claude Code: bagaimana pengaturan terkelola, proyek, dan pengguna digabungkan
• Mekanisme pengiriman: di mana file terkelola berada di setiap platform
• Siapkan Claude Code untuk organisasi Anda: peluncuran yang lebih luas yang merupakan bagian dari gateway ini, termasuk penegakan kebijakan, visibilitas penggunaan, dan penanganan data