1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Hubungkan Claude Code ke gateway LLM
6
7> Arahkan Claude Code ke gateway LLM organisasi Anda. Periksa apakah admin Anda sudah mengonfigurasinya, atau atur URL dasar dan kredensial sendiri untuk CLI, VS Code, GitHub Actions, dan Agent SDK, kemudian verifikasi koneksi dan perbaiki kesalahan gateway.
8
9[Gateway LLM](/id/llm-gateway) adalah proxy yang dijalankan organisasi Anda antara Claude Code dan penyedia model. Ketika organisasi Anda menggunakan satu, Claude Code melakukan autentikasi ke gateway dengan kredensial yang dikeluarkan organisasi Anda, bukan login claude.ai pribadi Anda.
10
11Halaman ini untuk pengembang yang menjalankan Claude Code melalui gateway yang dioperasikan organisasi mereka. Ini mencakup dua jalur: [memeriksa apakah administrator Anda sudah mengonfigurasinya untuk Anda](#check-for-an-existing-configuration), dan [mengonfigurasinya sendiri](#configure-claude-code-yourself) ketika mereka belum.
12
13<Note>
14 * Untuk menerapkan gateway untuk organisasi Anda, lihat [Luncurkan gateway LLM](/id/llm-gateway-rollout)
15 * Untuk apa yang Claude Code kirim ke gateway, lihat [referensi protokol gateway](/id/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 Periksa konfigurasi yang ada
20</h2>
21
22Administrator dapat mendistribusikan alamat gateway dan kredensial melalui [pengaturan terkelola](/id/settings#settings-files), manajemen perangkat, atau [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper), sehingga Claude Code mengambilnya saat startup tanpa apa pun yang perlu Anda atur. Untuk memeriksa apakah organisasi Anda sudah melakukan ini:
23
24<Steps>
25 <Step title="Mulai Claude Code">
26 Jalankan `claude`. Jika membuka ke layar login alih-alih sesi, tidak ada kredensial gateway yang didistribusikan; [konfigurasikan sendiri](#configure-claude-code-yourself) di bawah.
27 </Step>
28
29 <Step title="Periksa tab Status">
30 Jika Claude Code memulai sesi tanpa menampilkan layar login, jalankan `/status`, buka tab **Status**, dan periksa dua baris:
31
32 * `Anthropic base URL`: baris ini hanya muncul ketika alamat gateway diatur. Jika tidak ada, Claude Code tidak menunjuk ke gateway; [konfigurasikan sendiri](#configure-claude-code-yourself) di bawah.
33 * `Auth token` atau `API key`: baris yang menamai `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, atau `apiKeyHelper` mengonfirmasi kredensial gateway aktif. Baris `Login method` yang menamai akun claude.ai sebagai gantinya berarti kredensial tidak didistribusikan; [aturnya sendiri](#set-the-credential-variable).
34 </Step>
35
36 <Step title="Kirim pesan uji">
37 Tutup menu `/status` dan kirim prompt apa pun di Claude Code. Respons normal dari Claude, tanpa kesalahan, mengonfirmasi koneksi gateway berfungsi.
38 </Step>
39</Steps>
40
41Jika kedua baris di menu `/status` terlihat benar tetapi pesan ke Claude gagal, lihat [tabel pemecahan masalah](#troubleshoot-gateway-errors).
42
43<h2 id="configure-claude-code-yourself">
44 Konfigurasikan Claude Code sendiri
45</h2>
46
47Untuk mengonfigurasi Claude Code untuk gateway sendiri, Anda memerlukan dari tim gateway Anda:
48
49* URL dasar gateway
50* Kredensial: string kunci atau token, atau perintah yang mengambilnya
51 * Jika tim gateway Anda tidak mengatakan jenis kredensial apa itu, bagian [variabel kredensial](#set-the-credential-variable) di bawah mencakup apa yang harus dicoba
52
53Bagian di bawah mencakup konfigurasi secara berurutan:
54
55* [Atur variabel kredensial](#set-the-credential-variable) dan [atur URL dasar](#set-the-base-url-and-credential): dua variabel yang setiap koneksi gateway butuhkan
56* [Verifikasi koneksi](#verify-the-connection): konfirmasi berfungsi sebelum menyimpan apa pun
57* [Konfigurasikan setiap permukaan](#configure-each-surface): jika Anda menggunakan permukaan selain CLI Claude Code, seperti VS Code, lihat cara mengonfigurasinya dengan kredensial gateway Anda
58* [Konfigurasi tambahan](#additional-configuration): variabel yang beberapa gateway butuhkan di luar URL dasar dan kredensial, seperti header khusus, pembantu kredensial, penemuan model, atau URL dasar format penyedia. Atur ini hanya jika administrator Anda menamakannya
59
60<h3 id="set-the-credential-variable">
61 Atur variabel kredensial
62</h3>
63
64Untuk melakukan autentikasi Claude Code ke gateway, atur kredensial Anda dalam variabel lingkungan. Variabel mana tergantung pada apa yang diberitahu tim gateway Anda:
65
66| Atur kredensial di | Gunakan ketika |
67| :------------------------------------------------------ | :--------------------------------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | Tim gateway Anda mengatakan "bearer token" atau "Authorization header" |
69| `ANTHROPIC_API_KEY` | Tim gateway Anda mengatakan "API key" atau "x-api-key" |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | Kredensial berputar atau berasal dari vault |
71
72Jika Anda tidak diberitahu jenis mana, gunakan `ANTHROPIC_AUTH_TOKEN`; [permintaan verifikasi](#verify-the-connection) di bawah menunjukkan cara mengetahui apakah Anda perlu beralih.
73
74<h3 id="set-the-base-url-and-credential">
75 Atur URL dasar dan kredensial
76</h3>
77
78Atur URL dasar gateway dan variabel kredensial yang Anda pilih di atas sebagai variabel lingkungan. Contoh menggunakan `ANTHROPIC_AUTH_TOKEN`; tukarnya dengan `ANTHROPIC_API_KEY` jika itu [variabel yang Anda pilih](#set-the-credential-variable). Anda dapat mengaturnya [di shell Anda](#set-as-shell-environment-variables), yang berlaku untuk satu sesi terminal, atau [di file pengaturan Claude Code](#set-in-a-settings-file), yang bertahan di mana pun Claude Code berjalan.
79
80Untuk koneksi pertama Anda, mulai dengan ekspor shell dan jalankan [permintaan verifikasi](#verify-the-connection) sebelum memindahkan nilai ke file pengaturan.
81
82<h4 id="set-as-shell-environment-variables">
83 Atur sebagai variabel lingkungan shell
84</h4>
85
86Ganti nilai dengan yang diberikan tim gateway Anda:
87
88<Tabs>
89 <Tab title="Bash atau Zsh">
90 ```bash theme={null}
91 export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
92 export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
93 ```
94 </Tab>
95
96 <Tab title="PowerShell">
97 ```powershell theme={null}
98 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
99 $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
100 ```
101 </Tab>
102</Tabs>
103
104Ekspor shell hanya berlaku untuk sesi terminal itu dan program yang dimulai darinya; editor yang diluncurkan dari dock atau menu Start tidak akan melihatnya. Untuk membuatnya bertahan di terminal baru, tambahkan baris yang sama ke profil shell Anda, seperti `~/.zshrc`, `~/.bashrc`, atau `$PROFILE` PowerShell Anda, atau gunakan file pengaturan sebagai gantinya.
105
106<h4 id="set-in-a-settings-file">
107 Atur di file pengaturan
108</h4>
109
110Untuk membuat konfigurasi berlaku di mana pun Claude Code berjalan tanpa bergantung pada shell Anda, atur variabel di blok `env` dari [file pengaturan](/id/settings). File pengaturan memiliki cakupan berbeda:
111
112* `~/.claude/settings.json` berlaku untuk semua proyek Anda. Di Windows jalurnya adalah `%USERPROFILE%\.claude\settings.json`
113* `.claude/settings.local.json` berlaku untuk satu proyek. Claude Code menambahkannya ke gitignore Anda ketika membuat file; jika Anda membuatnya sendiri, tambahkan ke gitignore Anda secara manual terlebih dahulu sehingga Anda tidak secara tidak sengaja melakukan komit kredensial Anda
114
115<Warning>
116 Jangan letakkan kredensial di `.claude/settings.json` proyek. File itu dilakukan komit dan dibagikan dengan semua orang yang mengkloning repositori.
117</Warning>
118
119Blok `env` terlihat sama di kedua file:
120
121```json theme={null}
122{
123 "env": {
124 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
125 "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
126 }
127}
128```
129
130Ketika ekspor shell dan blok `env` file pengaturan mengatur variabel yang sama, nilai file pengaturan berlaku. Jalankan `/status` untuk melihat URL dasar dan sumber kredensial mana yang digunakan Claude Code.
131
132<h3 id="verify-the-connection">
133 Verifikasi koneksi
134</h3>
135
136Dengan variabel yang diekspor di shell Anda, kirim permintaan satu token ke gateway secara langsung. Ini mengonfirmasi URL dan kredensial berfungsi sebelum Anda membuka Claude Code, sehingga kegagalan menunjuk ke gateway daripada konfigurasi Anda. Perintah di bawah membaca variabel shell, jadi mereka memerlukan [ekspor shell](#set-as-shell-environment-variables) bahkan jika Anda juga menempatkan nilai di file pengaturan.
137
138<Tabs>
139 <Tab title="Bash atau Zsh">
140 ```bash theme={null}
141 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
142 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
143 -H "anthropic-version: 2023-06-01" \
144 -H "content-type: application/json" \
145 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
146 ```
147 </Tab>
148
149 <Tab title="PowerShell">
150 ```powershell theme={null}
151 Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
152 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
153 -ContentType "application/json" `
154 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
155 ```
156 </Tab>
157</Tabs>
158
159Jika gateway Anda mengharapkan kunci di header `x-api-key`, ganti header `Authorization` dengan `x-api-key: $ANTHROPIC_API_KEY` di perintah Bash, atau entri hashtable `"Authorization"` dengan `"x-api-key" = "$env:ANTHROPIC_API_KEY"` di perintah PowerShell.
160
161Respons JSON yang dimulai dengan `{"id":"msg_` dan menyertakan bidang `"content":[...]` berarti gateway dapat dijangkau dan kredensial berfungsi. Kesalahan yang menamai model yang tidak dikenal masih membuktikan URL dan kredensial berfungsi, karena gateway melakukan autentikasi permintaan sebelum menolak nama model; Anda tidak perlu menemukan model yang dilayani gateway Anda untuk tes ini. `401` berarti kredensial ditolak: jika Anda menebak variabel, beralih ke yang lain dan ekspor ulang.
162
163<h4 id="confirm-in-claude-code">
164 Konfirmasi di Claude Code
165</h4>
166
167Mulai `claude` dari shell yang sama sehingga mewarisi ekspor, kirim pesan, dan jalankan `/status`.
168
169Di tab **Status**, baris `Anthropic base URL` harus menampilkan alamat gateway Anda, yang mengonfirmasi permintaan dirutekan ke sana; jika baris tidak ada, variabel tidak mencapai sesi. Baris `Auth token` atau `API key` yang menamai variabel yang Anda atur mengonfirmasi kredensial gateway aktif daripada login claude.ai yang disimpan.
170
171Jika pesan gagal, atau `/status` tidak menampilkan URL gateway, lihat [tabel pemecahan masalah](#troubleshoot-gateway-errors) di bawah.
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 Bagaimana variabel kredensial memetakan ke header
175</h3>
176
177Setiap variabel mengirim kredensial di header HTTP berbeda: `ANTHROPIC_AUTH_TOKEN` di `Authorization: Bearer`, `ANTHROPIC_API_KEY` di `x-api-key`, dan `apiKeyHelper` di keduanya. Kredensial dalam variabel yang salah mencapai gateway di header yang tidak dibacanya, dan permintaan gagal dengan `401`. Jika permintaan verifikasi mengembalikan `401`, beralih ke variabel lain dan coba lagi.
178
179<h3 id="conflicts-with-an-existing-login">
180 Konflik dengan login yang ada
181</h3>
182
183Variabel kredensial gateway mengambil alih login claude.ai yang disimpan atau kunci Console. Login claude.ai Anda tetap disimpan dan tidak digunakan sementara variabel diatur; batalkan pengaturan variabel dan Claude Code kembali ke itu. Dengan `ANTHROPIC_AUTH_TOKEN`, variabel mengambil alih segera. Dengan `ANTHROPIC_API_KEY`, Anda diminta sekali dalam mode interaktif untuk menyetujui kunci sebelum mengambil alih.
184
185Jalankan `/status` untuk mengonfirmasi sumber kredensial mana yang aktif. Jika startup menampilkan peringatan konflik auth yang menamai dua sumber, lihat baris pertama [tabel pemecahan masalah](#troubleshoot-gateway-errors) untuk mengetahui mana yang harus dihapus. Untuk menghapus login yang disimpan sehingga hanya kredensial gateway yang tersisa, jalankan `/logout`.
186
187<h2 id="configure-each-surface">
188 Konfigurasikan setiap permukaan
189</h2>
190
191CLI membaca variabel lingkungan dan file pengaturan di atas. Permukaan lainnya adalah ekstensi VS Code, aplikasi desktop, GitHub Actions, Agent SDK, dan permukaan cloud seperti Slack dan web; bagian di bawah mencakup apakah pengaturan itu mencapai masing-masing.
192
193<h3 id="vs-code-extension">
194 Ekstensi VS Code
195</h3>
196
197Atur variabel gateway untuk [ekstensi VS Code](/id/vs-code) di `claudeCode.environmentVariables`, di pengaturan pengguna VS Code sendiri yang dibuka dengan perintah **Preferences: Open User Settings (JSON)**. Ekstensi memeriksa kredensial dari pengaturan ini sebelum meluncurkan, jadi itu tempat yang andal untuk kredensial gateway; nilai di `~/.claude/settings.json` mencapai proses yang dihasilkan tetapi bukan pemeriksaan login ekstensi sendiri.
198
199```json theme={null}
200{
201 "claudeCode.environmentVariables": [
202 { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
203 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
204 ]
205}
206```
207
208<h3 id="desktop-app">
209 Aplikasi desktop
210</h3>
211
212Aplikasi desktop membaca perutean gateway dari [konfigurasi yang didistribusikan administrator](https://claude.com/docs/cowork/3p/gateway), bukan dari `ANTHROPIC_BASE_URL` atau `settings.json`. Jika organisasi Anda telah mendistribusikannya, aplikasi desktop merutekan melalui gateway tanpa pengaturan di pihak Anda; jika tidak, gunakan CLI terminal atau ekstensi VS Code untuk sesi gateway. Administrator mendistribusikan konfigurasi seperti yang dijelaskan dalam [peluncuran organisasi](/id/llm-gateway-rollout#distribute-through-managed-settings).
213
214Jika aplikasi desktop menampilkan `Gateway was unreachable`, aplikasi tidak dapat menjangkau URL dasar yang dikonfigurasi saat startup; periksa URL dan jalur jaringan dengan [tes curl di atas](#verify-the-connection).
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/id/github-actions) membaca `ANTHROPIC_BASE_URL` dan `ANTHROPIC_CUSTOM_HEADERS` dari blok `env` alur kerja. Teruskan kredensial sebagai input `anthropic_api_key` tindakan; tindakan mengaturnya sebagai `ANTHROPIC_API_KEY`, sehingga mencapai gateway di header `x-api-key`.
221
222Untuk gateway `x-api-key`, atur URL dasar di `env` dan teruskan kunci gateway sebagai input:
223
224```yaml theme={null}
225env:
226 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
227
228steps:
229 - uses: anthropics/claude-code-action@v1
230 with:
231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
232```
233
234Untuk gateway bearer-token, teruskan rahasia yang sama sebagai input `anthropic_api_key` dan `ANTHROPIC_AUTH_TOKEN` di blok `env` alur kerja. Tindakan memerlukan `anthropic_api_key`, `CLAUDE_CODE_OAUTH_TOKEN`, atau federasi identitas beban kerja sebelum meluncurkan Claude Code, dan tidak membaca `ANTHROPIC_AUTH_TOKEN`, jadi input memenuhi pemeriksaan peluncuran itu sementara variabel env menempatkan kunci di header `Authorization` yang dibaca gateway. Salinan di `x-api-key` diabaikan:
235
236```yaml theme={null}
237env:
238 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
239 ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}
240
241steps:
242 - uses: anthropics/claude-code-action@v1
243 with:
244 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
245```
246
247Untuk opsi autentikasi lain tindakan, termasuk `CLAUDE_CODE_OAUTH_TOKEN` dan federasi identitas beban kerja, lihat [Claude Code GitHub Actions](/id/github-actions) dan [README](https://github.com/anthropics/claude-code-action#readme) tindakan.
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253[Agent SDK](/id/agent-sdk/overview) tidak memiliki opsi khusus gateway; itu melewatkan variabel lingkungan ke proses Claude Code yang dihasilkannya. Setiap SDK menerima opsi `env` yang mengatur lingkungan proses yang dihasilkan, dan SDK TypeScript dan Python memperlakukannya berbeda:
254
255* TypeScript: proses yang dihasilkan mewarisi lingkungan induk secara default, tetapi pengaturan `options.env` mengganti lingkungan sepenuhnya. Sebarkan `process.env` ke dalamnya untuk menyimpan variabel gateway Anda.
256* Python: `ClaudeAgentOptions(env=...)` menggabungkan di atas lingkungan yang diwarisi, jadi variabel gateway yang diatur dalam proses induk membawa tanpa penyebaran.
257
258<CodeGroup>
259 ```ts TypeScript theme={null}
260 const result = query({
261 prompt: "...",
262 options: {
263 env: {
264 ...process.env,
265 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
266 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
267 },
268 },
269 })
270 ```
271
272 ```python Python theme={null}
273 options = ClaudeAgentOptions(
274 env={
275 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
276 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
277 }
278 )
279 ```
280</CodeGroup>
281
282<h3 id="slack-web-and-remote-control">
283 Slack, web, dan Remote Control
284</h3>
285
286[Claude Code di Slack](/id/slack) dan [Claude Code di web](/id/claude-code-on-the-web) adalah produk yang dihosting Anthropic yang selalu menggunakan API Anthropic; mereka bukan bagian dari penerapan gateway. Variabel gateway yang diatur dalam konfigurasi lingkungan sesi cloud tidak diterapkan. Jika lalu lintas Anda harus tetap di gateway, jangan aktifkan permukaan ini untuk pengguna tersebut.
287
288[Remote Control](/id/remote-control) dan [voice dictation](/id/voice-dictation) keduanya mengandalkan identitas claude.ai: Remote Control untuk memasangkan sesi langsung dengan akun Anda, dan voice dictation untuk menjangkau titik akhir transkripsi claude.ai. Mereka tidak tersedia sementara `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, atau `apiKeyHelper` aktif. Untuk menggunakan salah satu, batalkan pengaturan kredensial gateway dan masuk dengan claude.ai sebagai gantinya; `/doctor` menamai variabel untuk dibatalkan pengaturannya.
289
290<h2 id="additional-configuration">
291 Konfigurasi tambahan
292</h2>
293
294Pengaturan ini mencakup kasus di luar URL dasar dan kredensial. Atur hanya jika instruksi administrator Anda atau [tabel pemecahan masalah](#troubleshoot-gateway-errors) memanggil satu.
295
296<h3 id="send-additional-headers">
297 Kirim header tambahan
298</h3>
299
300Beberapa gateway merutekan atau menandai permintaan menggunakan header khusus selain kredensial, misalnya pengidentifikasi penyewa atau kunci perutean. Untuk mengirim satu, atur [`ANTHROPIC_CUSTOM_HEADERS`](/id/env-vars) dengan satu pasangan `Name: Value` per baris. Contoh di bawah menambahkan header perutean bernama `X-Org-Route`:
301
302<Tabs>
303 <Tab title="Bash atau Zsh">
304 ```bash theme={null}
305 export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
306 ```
307 </Tab>
308
309 <Tab title="PowerShell">
310 ```powershell theme={null}
311 $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
312 ```
313 </Tab>
314</Tabs>
315
316Anda juga dapat mengatur `ANTHROPIC_CUSTOM_HEADERS` di blok `env` file pengaturan. Gunakan `\n` antara pasangan di sana, karena string JSON tidak dapat mencakup beberapa baris:
317
318```json theme={null}
319{
320 "env": {
321 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
322 }
323}
324```
325
326<h3 id="add-gateway-models-to-the-model-picker">
327 Tambahkan model gateway ke pemilih model
328</h3>
329
330Penemuan model menanyakan gateway untuk daftar modelnya saat startup dan menambahkan nama tersebut ke pemilih `/model` bersama entri bawaan.
331
332Aktifkan jika gateway Anda melayani nama model yang tidak ada dalam daftar bawaan Claude Code dan Anda ingin memilihnya dari pemilih. Jika model bawaan adalah apa yang Anda gunakan, Anda tidak memerlukan penemuan; administrator Anda mungkin juga telah mengaktifkannya melalui pengaturan terkelola.
333
334Untuk mengaktifkannya, atur `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` di shell Anda atau di blok `env` dari `~/.claude/settings.json`. Penemuan memerlukan Claude Code v2.1.129 atau lebih baru. {/* min-version: 2.1.129 */}
335
336Model yang ditemukan muncul sebagai entri `/model` tambahan berlabel `From gateway`. Untuk mengonfirmasi penemuan berjalan, mulai `claude --debug` dan cari baris `[gatewayDiscovery]`: keberhasilan mencatat berapa banyak model yang di-cache, dan `404`, timeout, atau pengalihan dicatat di sana juga. Untuk kapan penemuan berjalan, apa yang disaringnya, dan format respons yang dilayani gateway, lihat [referensi penemuan model](/id/llm-gateway-protocol#model-discovery).
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 Putar kredensial dengan apiKeyHelper
340</h3>
341
342`apiKeyHelper` adalah perintah yang dijalankan Claude Code untuk mengambil kredensial gateway Anda, alih-alih membacanya dari variabel lingkungan statis.
343
344Gunakan pembantu ketika kredensial kedaluwarsa sesuai jadwal, berasal dari vault atau perintah SSO, atau administrator Anda mengatakan untuk mengonfigurasi satu. Jika kredensial Anda adalah string tetap yang Anda atur sekali, [variabel kredensial](#set-the-credential-variable) adalah semua yang Anda butuhkan dan Anda dapat melewati bagian ini.
345
346Pembantu adalah perintah shell apa pun yang mencetak kredensial saat ini ke stdout. Claude Code menjalankannya melalui shell sistem Anda, jadi di Windows itu dapat berupa executable atau invokasi PowerShell. Tulis skrip, buat dapat dieksekusi, dan referensikan dari `apiKeyHelper` di [file pengaturan](/id/settings) Anda:
347
348<Tabs>
349 <Tab title="Bash atau Zsh">
350 Misalnya, skrip yang membaca dari vault:
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 Referensikan jalurnya di `~/.claude/settings.json`:
358
359 ```json theme={null}
360 {
361 "apiKeyHelper": "~/bin/get-gateway-key.sh"
362 }
363 ```
364 </Tab>
365
366 <Tab title="PowerShell">
367 Misalnya, skrip yang membaca dari vault:
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 Referensikan invokasi PowerShell di `%USERPROFILE%\.claude\settings.json`, meloloskan garis miring terbalik dalam string JSON:
374
375 ```json theme={null}
376 {
377 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
378 }
379 ```
380 </Tab>
381</Tabs>
382
383Claude Code menyimpan output pembantu selama lima menit secara default dan menjalankannya kembali ketika permintaan mengembalikan HTTP 401. Untuk mengubah masa pakai cache, atur `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` dalam milidetik, misalnya `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` untuk 15 menit.
384
385Nilai pembantu dikirim di header `Authorization` dan `x-api-key`, jadi berfungsi di mana pun header gateway Anda dibaca.
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 Rutekan ke penyedia cloud melalui gateway
389</h3>
390
391Konfigurasi ini menunjukkan Claude Code ke gateway melalui variabel URL dasar khusus penyedia sebagai pengganti `ANTHROPIC_BASE_URL`. Gateway Bedrock dan Vertex menerima format permintaan asli penyedia tersebut; gateway Foundry dan Claude Platform di AWS menerima format Anthropic Messages dan berbeda hanya dalam variabel URL dasar mana yang mencapainya.
392
393Gunakan satu hanya jika tim gateway Anda secara khusus menamai Bedrock, Vertex, Foundry, atau Claude Platform di AWS. Jika [permintaan verifikasi](#verify-the-connection) di atas mengembalikan JSON, Anda dapat melewati bagian ini.
394
395Atur blok untuk penyedia yang dinamai tim gateway Anda. Variabel skip-auth memberitahu Claude Code untuk tidak menandatangani permintaan dengan kredensial penyedia, karena gateway menyimpannya. Jika gateway memerlukan token sendiri, tambahkan `ANTHROPIC_AUTH_TOKEN` setelah blok, kecuali untuk Foundry, yang menggunakan `ANTHROPIC_FOUNDRY_API_KEY` seperti yang ditunjukkan.
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash atau Zsh">
403 ```bash theme={null}
404 export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
405 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
406 export CLAUDE_CODE_USE_BEDROCK=1
407 ```
408 </Tab>
409
410 <Tab title="PowerShell">
411 ```powershell theme={null}
412 $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
413 $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
414 $env:CLAUDE_CODE_USE_BEDROCK = "1"
415 ```
416 </Tab>
417</Tabs>
418
419<h4 id="google-vertex-ai">
420 Google Vertex AI
421</h4>
422
423<Tabs>
424 <Tab title="Bash atau Zsh">
425 ```bash theme={null}
426 export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
427 export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
428 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
429 export CLAUDE_CODE_USE_VERTEX=1
430 export CLOUD_ML_REGION=us-east5
431 ```
432 </Tab>
433
434 <Tab title="PowerShell">
435 ```powershell theme={null}
436 $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
437 $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
438 $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
439 $env:CLAUDE_CODE_USE_VERTEX = "1"
440 $env:CLOUD_ML_REGION = "us-east5"
441 ```
442 </Tab>
443</Tabs>
444
445<h4 id="microsoft-foundry">
446 Microsoft Foundry
447</h4>
448
449Letakkan kredensial gateway di `ANTHROPIC_FOUNDRY_API_KEY`; itu dikirim ke gateway sebagai header `x-api-key`. `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` tidak berlaku di sini: tanpa kunci API, klien Foundry gagal setiap permintaan sebelum meninggalkan mesin.
450
451<Tabs>
452 <Tab title="Bash atau Zsh">
453 ```bash theme={null}
454 export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
455 export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
456 export CLAUDE_CODE_USE_FOUNDRY=1
457 ```
458 </Tab>
459
460 <Tab title="PowerShell">
461 ```powershell theme={null}
462 $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
463 $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
464 $env:CLAUDE_CODE_USE_FOUNDRY = "1"
465 ```
466 </Tab>
467</Tabs>
468
469<h4 id="claude-platform-on-aws">
470 Claude Platform di AWS
471</h4>
472
473Lihat [Claude Platform di AWS](/id/claude-platform-on-aws) untuk ID ruang kerja.
474
475<Tabs>
476 <Tab title="Bash atau Zsh">
477 ```bash theme={null}
478 export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
479 export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
480 export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
481 export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
482 ```
483 </Tab>
484
485 <Tab title="PowerShell">
486 ```powershell theme={null}
487 $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
488 $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
489 $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
490 $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
491 ```
492 </Tab>
493</Tabs>
494
495<h2 id="troubleshoot-gateway-errors">
496 Pemecahan masalah kesalahan gateway
497</h2>
498
499Ini adalah kesalahan paling umum saat menjalankan Claude Code melalui gateway, dengan penyebab sisi gateway dan perbaikannya:
500
501| Kesalahan | Penyebab | Perbaikan |
502| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| Peringatan startup yang menamai dua sumber kredensial dan berakhir dengan `auth may not work as expected`. Versi lebih lama menampilkan `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` sebagai gantinya. | Kredensial gateway dan login yang disimpan keduanya aktif; variabel digunakan untuk permintaan, tetapi login basi dapat menyebabkan perilaku auth yang tidak terduga | Batalkan pengaturan variabel untuk menggunakan login yang disimpan, atau jalankan `/logout` untuk menggunakan kredensial gateway |
504| Kesalahan `401` yang menamai token yang tidak valid atau tidak dikenali | Kredensial bukan yang dikeluarkan gateway, atau berada di header yang tidak dibaca gateway | Konfirmasi variabel cocok dengan jenis kredensial Anda di [tabel kredensial](#set-the-credential-variable), dan regenerasi kunci di gateway jika itu dicabut |
505| `Unable to connect to API (ConnectionRefused)`, atau `(ECONNREFUSED)` dari instalasi npm, sering setelah jeda senyap sementara Claude Code [mencoba ulang dengan backoff](/id/errors#automatic-retries) | Tidak ada yang menjawab di URL dasar: alamatnya salah, atau VPN atau firewall memblokir jalur ke gateway | Jalankan [tes curl di atas](#verify-the-connection), yang gagal segera dengan penyebab yang sama, dan konfirmasi URL dan jalur jaringan dengan tim gateway Anda |
506| `API returned an empty or malformed response (HTTP 200)` | Gateway atau proxy perantara mengembalikan respons non-API, sering halaman HTML error atau login | Uji dengan [permintaan curl di atas](#verify-the-connection); perbaiki rute gateway yang mengembalikan non-JSON |
507| Kesalahan `400` yang menamai `context_management`, `Extra inputs are not permitted`, atau bidang lain yang tidak dikenali | Gateway meneruskan permintaan ke upstream yang menolak bidang yang dikirim Claude Code ke titik akhir format Anthropic | Atur `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, yang menekan sebagian besar bidang pra-rilis; lihat [feature pass-through](/id/llm-gateway-protocol#feature-pass-through). Beberapa beta tidak dijaga oleh bendera ini; untuk itu, atur variabel penyedia `CLAUDE_CODE_USE_*` yang cocok sehingga Claude Code hanya mengirim apa yang diterima penyedia itu |
508| Kesalahan `400` yang menamai `thinking` atau `adaptive`, seperti `Input tag 'adaptive' found` | Build model upstream tidak menerima adaptive reasoning, yang diminta Claude Code untuk model Claude 4.6 dan lebih baru | Tingkatkan upstream gateway. Di Opus 4.6 dan Sonnet 4.6, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` berfungsi sebagai gantinya. Variabel kemampuan [konfigurasi model](/id/model-config) hanya berlaku untuk konfigurasi penyedia, seperti `CLAUDE_CODE_USE_BEDROCK` dan `CLAUDE_CODE_USE_VERTEX`, bukan di belakang gateway `ANTHROPIC_BASE_URL` |
509| Kesalahan `400` yang menyatakan batas konteks atau token dalam kata-kata gateway sendiri, seperti `ContextWindowExceededError` atau `prompt token count of N exceeds the limit of M` | Gateway memberlakukan konteks yang lebih kecil dari jendela asli model dan menulis ulang kesalahan upstream, jadi compact-and-retry otomatis, yang cocok dengan pesan `prompt is too long` Anthropic, tidak terbangkitkan | Jalankan `/compact` untuk memulihkan sesi. Untuk mencegahnya, atur `CLAUDE_CODE_AUTO_COMPACT_WINDOW` ke batas gateway; nilainya diklem ke setidaknya 100.000 token dan paling banyak jendela konteks model, jadi batas gateway di bawah 100.000 tidak dapat dicocokkan dan `/compact` tetap menjadi pemulihan di sana. Juga atur `CLAUDE_CODE_MAX_OUTPUT_TOKENS` di bawah batas output model gateway |
510| Model hilang dari pemilih `/model` | Nama model gateway tidak ada dalam daftar bawaan Claude Code | Aktifkan [penemuan model gateway](#add-gateway-models-to-the-model-picker) atau tambahkan nama dengan variabel [konfigurasi model](/id/model-config) |
511| Claude Code meminta Anda untuk masuk meskipun [tes curl](#verify-the-connection) berhasil | CLI tidak memiliki kredensial sendiri: URL dasar yang dapat dijangkau bukan satu, dan blok `env` di `.claude/settings.json` atau `.claude/settings.local.json` proyek hanya berlaku setelah wizard first-run dan prompt kepercayaan | Atur `ANTHROPIC_AUTH_TOKEN` di mana pun Claude Code membaca sebelum pengaturan first-run: ekspor shell, blok `env` di `~/.claude/settings.json`, atau pengaturan terkelola |
512| `ANTHROPIC_API_KEY` diatur tetapi diabaikan, tanpa prompt | Kunci memerlukan persetujuan satu kali dalam sesi interaktif, dan kunci yang sebelumnya ditolak diabaikan tanpa bertanya lagi | Aktifkannya di bawah `/config` dengan opsi `Use custom API key` |
513| `This machine's managed settings require a first-party login` | Pengaturan terkelola menyertakan `forceLoginMethod` atau `forceLoginOrgUUID`, yang pada Claude Code v2.1.146 dan lebih baru tidak dapat hidup berdampingan dengan `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, atau `apiKeyHelper` | Administrator Anda harus menghapus `forceLoginMethod` dan `forceLoginOrgUUID` dari pengaturan terkelola untuk menggunakan kredensial gateway, atau menghapus kredensial gateway untuk menggunakan login pihak pertama. Keduanya tidak dapat digabungkan |
514| `403` dengan badan HTML seperti `403 Forbidden`, ketika log gateway sendiri menunjukkan tidak ada permintaan yang diterima | Firewall aplikasi web atau proxy terbalik di depan gateway memblokir badan permintaan sebelum mencapai gateway. Prompt Claude Code menyertakan tag gaya XML dan kode sumber yang cocok dengan aturan badan cross-site-scripting, jadi tes curl pendek lulus sementara sesi nyata tidak | Bebaskan jalur `/v1/messages` gateway dari inspeksi badan permintaan. Di AWS WAF ini adalah aturan terkelola `CrossSiteScripting_Body`; di nginx dengan ModSecurity itu adalah aturan badan OWASP CRS yang setara |
515| Kesalahan sertifikat atau TLS seperti `SSL certificate verification failed` atau `Self-signed certificate detected`, ketika [tes curl](#verify-the-connection) berhasil | Runtime Claude Code tidak mempercayai otoritas sertifikat yang sama dengan yang digunakan `curl`. Umum di belakang proxy inspeksi TLS korporat | Atur `NODE_EXTRA_CA_CERTS` ke jalur bundel CA; lihat [CA certificate store](/id/network-config#ca-certificate-store) |
516
517Jika Claude Code meminta Anda untuk masuk berulang kali setelah menghapus konfigurasi gateway, penyebabnya biasanya penyimpanan kredensial daripada gateway; lihat [kesalahan autentikasi](/id/errors#authentication-errors).
518
519<h2 id="related-resources">
520 Sumber daya terkait
521</h2>
522
523* [Ikhtisar gateway LLM](/id/llm-gateway): apa itu gateway dan bagaimana berinteraksi dengan langganan claude.ai
524* [Luncurkan gateway LLM untuk organisasi Anda](/id/llm-gateway-rollout): daftar periksa yang menghadap admin untuk menerapkan dan mendistribusikan konfigurasi gateway
525* [Referensi protokol gateway](/id/llm-gateway-protocol): apa yang dikirim Claude Code ke gateway, termasuk header dan bidang yang harus diteruskan gateway
526* [Pengaturan](/id/settings): di mana file pengaturan berada dan bagaimana blok `env` dibaca
527* [Autentikasi](/id/authentication): bagaimana variabel kredensial, `apiKeyHelper`, dan login OAuth berinteraksi
