Hubungkan Claude Code ke gateway LLM

Gateway LLM 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. Halaman 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, dan mengonfigurasinya sendiri ketika mereka belum.

Untuk menerapkan gateway untuk organisasi Anda, lihat Luncurkan gateway LLM
Untuk apa yang Claude Code kirim ke gateway, lihat referensi protokol gateway

Periksa konfigurasi yang ada

Administrator dapat mendistribusikan alamat gateway dan kredensial melalui pengaturan terkelola, manajemen perangkat, atau apiKeyHelper, sehingga Claude Code mengambilnya saat startup tanpa apa pun yang perlu Anda atur. Untuk memeriksa apakah organisasi Anda sudah melakukan ini:

Mulai Claude Code

Jalankan claude. Jika membuka ke layar login alih-alih sesi, tidak ada kredensial gateway yang didistribusikan; konfigurasikan sendiri di bawah.

Periksa tab Status

Jika Claude Code memulai sesi tanpa menampilkan layar login, jalankan /status, buka tab Status, dan periksa dua baris:

Anthropic base URL: baris ini hanya muncul ketika alamat gateway diatur. Jika tidak ada, Claude Code tidak menunjuk ke gateway; konfigurasikan sendiri di bawah.
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.

Kirim pesan uji

Tutup menu /status dan kirim prompt apa pun di Claude Code. Respons normal dari Claude, tanpa kesalahan, mengonfirmasi koneksi gateway berfungsi.

Jika kedua baris di menu /status terlihat benar tetapi pesan ke Claude gagal, lihat tabel pemecahan masalah.

Konfigurasikan Claude Code sendiri

Untuk mengonfigurasi Claude Code untuk gateway sendiri, Anda memerlukan dari tim gateway Anda:

URL dasar gateway
Kredensial: string kunci atau token, atau perintah yang mengambilnya
- Jika tim gateway Anda tidak mengatakan jenis kredensial apa itu, bagian variabel kredensial di bawah mencakup apa yang harus dicoba

Bagian di bawah mencakup konfigurasi secara berurutan:

Atur variabel kredensial dan atur URL dasar: dua variabel yang setiap koneksi gateway butuhkan
Verifikasi koneksi: konfirmasi berfungsi sebelum menyimpan apa pun
Konfigurasikan setiap permukaan: jika Anda menggunakan permukaan selain CLI Claude Code, seperti VS Code, lihat cara mengonfigurasinya dengan kredensial gateway Anda
Konfigurasi tambahan: 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

Atur variabel kredensial

Untuk melakukan autentikasi Claude Code ke gateway, atur kredensial Anda dalam variabel lingkungan. Variabel mana tergantung pada apa yang diberitahu tim gateway Anda:

Atur kredensial di	Gunakan ketika
`ANTHROPIC_AUTH_TOKEN`	Tim gateway Anda mengatakan “bearer token” atau “Authorization header”
`ANTHROPIC_API_KEY`	Tim gateway Anda mengatakan “API key” atau “x-api-key”
`apiKeyHelper`	Kredensial berputar atau berasal dari vault

Jika Anda tidak diberitahu jenis mana, gunakan ANTHROPIC_AUTH_TOKEN; permintaan verifikasi di bawah menunjukkan cara mengetahui apakah Anda perlu beralih.

Atur URL dasar dan kredensial

Atur 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. Anda dapat mengaturnya di shell Anda, yang berlaku untuk satu sesi terminal, atau di file pengaturan Claude Code, yang bertahan di mana pun Claude Code berjalan. Untuk koneksi pertama Anda, mulai dengan ekspor shell dan jalankan permintaan verifikasi sebelum memindahkan nilai ke file pengaturan.

Atur sebagai variabel lingkungan shell

Ganti nilai dengan yang diberikan tim gateway Anda:

Bash atau Zsh
PowerShell

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

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

Ekspor 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.

Atur di file pengaturan

Untuk membuat konfigurasi berlaku di mana pun Claude Code berjalan tanpa bergantung pada shell Anda, atur variabel di blok env dari file pengaturan. File pengaturan memiliki cakupan berbeda:

~/.claude/settings.json berlaku untuk semua proyek Anda. Di Windows jalurnya adalah %USERPROFILE%\.claude\settings.json
.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

Jangan letakkan kredensial di .claude/settings.json proyek. File itu dilakukan komit dan dibagikan dengan semua orang yang mengkloning repositori.

Blok env terlihat sama di kedua file:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

Ketika 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.

Verifikasi koneksi

Dengan 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 bahkan jika Anda juga menempatkan nilai di file pengaturan.

Bash atau Zsh
PowerShell

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -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 "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Jika 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. Respons 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.

Konfirmasi di Claude Code

Mulai claude dari shell yang sama sehingga mewarisi ekspor, kirim pesan, dan jalankan /status. Di 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. Jika pesan gagal, atau /status tidak menampilkan URL gateway, lihat tabel pemecahan masalah di bawah.

Bagaimana variabel kredensial memetakan ke header

Setiap 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. Variabel 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. Jalankan /status untuk mengonfirmasi sumber kredensial mana yang aktif. Jika startup menampilkan peringatan konflik auth yang menamai dua sumber, lihat baris pertama tabel pemecahan masalah untuk mengetahui mana yang harus dihapus. Untuk menghapus login yang disimpan sehingga hanya kredensial gateway yang tersisa, jalankan /logout.

Konfigurasikan setiap permukaan

CLI 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.

Ekstensi VS Code

Atur variabel gateway untuk ekstensi 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.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

Aplikasi desktop

Aplikasi desktop membaca perutean gateway dari konfigurasi yang didistribusikan administrator, 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. Jika 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.

GitHub Actions

Claude Code 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. Untuk gateway x-api-key, atur URL dasar di env dan teruskan kunci gateway sebagai input:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Untuk 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:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Untuk opsi autentikasi lain tindakan, termasuk CLAUDE_CODE_OAUTH_TOKEN dan federasi identitas beban kerja, lihat Claude Code GitHub Actions dan README tindakan.

Agent SDK

Agent SDK 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:

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.
Python: ClaudeAgentOptions(env=...) menggabungkan di atas lingkungan yang diwarisi, jadi variabel gateway yang diatur dalam proses induk membawa tanpa penyebaran.

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

Slack, web, dan Remote Control

Claude Code di Slack dan Claude Code di 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. Remote Control dan 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.

Konfigurasi tambahan

Pengaturan ini mencakup kasus di luar URL dasar dan kredensial. Atur hanya jika instruksi administrator Anda atau tabel pemecahan masalah memanggil satu.

Kirim header tambahan

Beberapa gateway merutekan atau menandai permintaan menggunakan header khusus selain kredensial, misalnya pengidentifikasi penyewa atau kunci perutean. Untuk mengirim satu, atur ANTHROPIC_CUSTOM_HEADERS dengan satu pasangan Name: Value per baris. Contoh di bawah menambahkan header perutean bernama X-Org-Route:

Bash atau Zsh
PowerShell

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

Anda 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:

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
  }
}

Tambahkan model gateway ke pemilih model

Penemuan model menanyakan gateway untuk daftar modelnya saat startup dan menambahkan nama tersebut ke pemilih /model bersama entri bawaan. Aktifkan 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. Untuk 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. Model 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.

Putar kredensial dengan apiKeyHelper

apiKeyHelper adalah perintah yang dijalankan Claude Code untuk mengambil kredensial gateway Anda, alih-alih membacanya dari variabel lingkungan statis. Gunakan 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 adalah semua yang Anda butuhkan dan Anda dapat melewati bagian ini. Pembantu 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 Anda:

Bash atau Zsh
PowerShell

Misalnya, skrip yang membaca dari vault:

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code

Referensikan jalurnya di ~/.claude/settings.json:

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

Misalnya, skrip yang membaca dari vault:

vault kv get -field=api_key secret/llm-gateway/claude-code

Referensikan invokasi PowerShell di %USERPROFILE%\.claude\settings.json, meloloskan garis miring terbalik dalam string JSON:

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Claude 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. Nilai pembantu dikirim di header Authorization dan x-api-key, jadi berfungsi di mana pun header gateway Anda dibaca.

Rutekan ke penyedia cloud melalui gateway

Konfigurasi 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. Gunakan satu hanya jika tim gateway Anda secara khusus menamai Bedrock, Vertex, Foundry, atau Claude Platform di AWS. Jika permintaan verifikasi di atas mengembalikan JSON, Anda dapat melewati bagian ini. Atur 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.

Amazon Bedrock

Bash atau Zsh
PowerShell

export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
$env:CLAUDE_CODE_USE_BEDROCK = "1"

Google Vertex AI

Bash atau Zsh
PowerShell

export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "us-east5"

Microsoft Foundry

Letakkan 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.

Bash atau Zsh
PowerShell

export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
export CLAUDE_CODE_USE_FOUNDRY=1

$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

Claude Platform di AWS

Lihat Claude Platform di AWS untuk ID ruang kerja.

Bash atau Zsh
PowerShell

export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

Pemecahan masalah kesalahan gateway

Ini adalah kesalahan paling umum saat menjalankan Claude Code melalui gateway, dengan penyebab sisi gateway dan perbaikannya:

Kesalahan	Penyebab	Perbaikan
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
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, dan regenerasi kunci di gateway jika itu dicabut
`Unable to connect to API (ConnectionRefused)`, atau `(ECONNREFUSED)` dari instalasi npm, sering setelah jeda senyap sementara Claude Code mencoba ulang dengan backoff	Tidak ada yang menjawab di URL dasar: alamatnya salah, atau VPN atau firewall memblokir jalur ke gateway	Jalankan tes curl di atas, yang gagal segera dengan penyebab yang sama, dan konfirmasi URL dan jalur jaringan dengan tim gateway Anda
`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; perbaiki rute gateway yang mengembalikan non-JSON
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. 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
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 hanya berlaku untuk konfigurasi penyedia, seperti `CLAUDE_CODE_USE_BEDROCK` dan `CLAUDE_CODE_USE_VERTEX`, bukan di belakang gateway `ANTHROPIC_BASE_URL`
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
Model hilang dari pemilih `/model`	Nama model gateway tidak ada dalam daftar bawaan Claude Code	Aktifkan penemuan model gateway atau tambahkan nama dengan variabel konfigurasi model
Claude Code meminta Anda untuk masuk meskipun tes curl 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
`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`
`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
`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
Kesalahan sertifikat atau TLS seperti `SSL certificate verification failed` atau `Self-signed certificate detected`, ketika tes curl 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

Jika Claude Code meminta Anda untuk masuk berulang kali setelah menghapus konfigurasi gateway, penyebabnya biasanya penyimpanan kredensial daripada gateway; lihat kesalahan autentikasi.

Ikhtisar gateway LLM: apa itu gateway dan bagaimana berinteraksi dengan langganan claude.ai
Luncurkan gateway LLM untuk organisasi Anda: daftar periksa yang menghadap admin untuk menerapkan dan mendistribusikan konfigurasi gateway
Referensi protokol gateway: apa yang dikirim Claude Code ke gateway, termasuk header dan bidang yang harus diteruskan gateway
Pengaturan: di mana file pengaturan berada dan bagaimana blok env dibaca
Autentikasi: bagaimana variabel kredensial, apiKeyHelper, dan login OAuth berinteraksi

​Periksa konfigurasi yang ada

​Konfigurasikan Claude Code sendiri

​Atur variabel kredensial

​Atur URL dasar dan kredensial

​Atur sebagai variabel lingkungan shell

​Atur di file pengaturan

​Verifikasi koneksi

​Konfirmasi di Claude Code

​Bagaimana variabel kredensial memetakan ke header

​Konflik dengan login yang ada

​Konfigurasikan setiap permukaan

​Ekstensi VS Code

​Aplikasi desktop

​GitHub Actions

​Agent SDK

​Slack, web, dan Remote Control

​Konfigurasi tambahan

​Kirim header tambahan

​Tambahkan model gateway ke pemilih model

​Putar kredensial dengan apiKeyHelper

​Rutekan ke penyedia cloud melalui gateway

​Amazon Bedrock

​Google Vertex AI

​Microsoft Foundry

​Claude Platform di AWS

​Pemecahan masalah kesalahan gateway

​Sumber daya terkait

Periksa konfigurasi yang ada

Konfigurasikan Claude Code sendiri

Atur variabel kredensial

Atur URL dasar dan kredensial

Atur sebagai variabel lingkungan shell

Atur di file pengaturan

Verifikasi koneksi

Konfirmasi di Claude Code

Bagaimana variabel kredensial memetakan ke header

Konflik dengan login yang ada

Konfigurasikan setiap permukaan

Ekstensi VS Code

Aplikasi desktop

GitHub Actions

Agent SDK

Slack, web, dan Remote Control

Konfigurasi tambahan

Kirim header tambahan

Tambahkan model gateway ke pemilih model

Putar kredensial dengan apiKeyHelper

Rutekan ke penyedia cloud melalui gateway

Amazon Bedrock

Google Vertex AI

Microsoft Foundry

Claude Platform di AWS

Pemecahan masalah kesalahan gateway

Sumber daya terkait