Sebuah setup Claude Code API router tidak sama dengan mengubah base URL OpenAI SDK. Claude Code menggunakan bentuk gateway Anthropic Messages, jadi pemeriksaan pentingnya adalah root router, header kredensial, nama model yang akan dikirim Claude Code, dan catatan penggunaan yang membuktikan permintaan mencapai akun yang सही.
Panduan ini memberikan setup Flatkey yang berorientasi produksi untuk developer, tim produk AI, pembangun otomasi, engineer platform, operator keuangan, dan reviewer pengadaan. Panduan ini mencakup base URL, preflight satu token, nama model, penemuan model gateway, log penggunaan, dan mode kegagalan sebelum Anda memindahkan pekerjaan coding harian ke Claude Code API router.
Catatan sumber: ini diperiksa pada 29 Juni 2026 terhadap dokumentasi resmi Claude Code LLM gateways, panduan koneksi gateway Claude Code, referensi protokol gateway, dokumentasi konfigurasi model, dokumentasi pemantauan, dan halaman publik Flatkey saat ini. Tidak ada kunci Flatkey spesifik akun yang digunakan untuk smoke test Claude Code langsung, jadi cuplikan di bawah adalah templat untuk dijalankan dengan kunci Anda sendiri dan model yang disetujui.
Jawaban singkat: setup Claude Code API router
Untuk setup Claude Code API router dengan Flatkey, konfigurasikan Claude Code dengan root router Claude Code Flatkey, kunci Flatkey, dan nama model Claude yang tepat yang dapat dipanggil akun Anda. Lalu uji endpoint Anthropic Messages sebelum membuka sesi coding yang panjang.
| Bidang setup | Nilai atau pemeriksaan Flatkey | Mengapa ini penting |
|---|---|---|
| Base URL | https://router.flatkey.ai untuk use case Claude Code kecuali akun Flatkey Anda menampilkan nilai khusus Claude Code yang lebih baru |
Claude Code menambahkan /v1/messages. Jangan tempel base OpenAI SDK yang berakhir dengan /v1 kecuali pengujian Anda memastikan itu tidak membuat /v1/v1/messages. |
| Kredensial | ANTHROPIC_AUTH_TOKEN untuk routing bearer-token, atau ANTHROPIC_API_KEY saat gateway mengharapkan x-api-key |
Dokumentasi resmi Claude Code memetakan setiap variabel ke header HTTP yang berbeda. Kunci yang valid di variabel yang salah tetap menghasilkan 401. |
| Preflight endpoint | $ANTHROPIC_BASE_URL/v1/messages |
Halaman harga Flatkey saat ini mencantumkan /v1/messages dalam peta endpoint, yang merupakan path yang dibutuhkan Claude Code untuk traffic Anthropic Messages. |
| Model | Gunakan ID model Claude yang tepat atau alias Claude Code yang terhubung ke route Flatkey yang diaktifkan | Pemilihan model terpisah dari routing base URL. Router menentukan ke mana traffic pergi; Claude Code tetap mengirim nama model. |
| Bukti penggunaan | Periksa penggunaan Flatkey dan telemetry Claude Code setelah prompt pertama | Output yang berhasil tidak cukup. Tim membutuhkan bukti key, model, timestamp, sesi, biaya, dan token. |
Itulah versi singkatnya. Sisa panduan Claude Code API router ini mengubah field-field tersebut menjadi runbook setup yang dapat diulang.
Apa yang dikonfirmasi oleh dokumen gateway resmi Claude Code
Gambaran umum gateway Claude Code resmi mendefinisikan LLM gateway sebagai proxy antara Claude Code dan penyedia model. Claude Code mengirim traffic API ke gateway, dan gateway meneruskannya dengan kredensial penyedia yang dikendalikan oleh organisasi. Halaman yang sama mencantumkan manfaat gateway seperti kredensial terpusat, pelacakan penggunaan, kontrol biaya, logging audit, dan pergantian penyedia.
Aturan base URL bersifat spesifik. Claude Code biasanya mengirim permintaan ke API Anthropic, tetapi mengatur ANTHROPIC_BASE_URL mengarahkan permintaan itu ke gateway. Panduan koneksi kemudian memverifikasi rute dengan mem-posting ke $ANTHROPIC_BASE_URL/v1/messages dengan anthropic-version: 2023-06-01.
Referensi protokol gateway menambahkan detail di sisi operator. Untuk format Anthropic Messages, gateway yang dipilih oleh ANTHROPIC_BASE_URL harus melayani /v1/messages dan secara opsional /v1/messages/count_tokens. Referensi itu juga menyatakan bahwa respons inferensi harus stream karena Claude Code mengonsumsi server-sent events saat diterima.
Untuk Claude Code API router, artinya Anda harus memvalidasi path Anthropic Messages, bukan hanya path chat-completions yang kompatibel dengan OpenAI. Route OpenAI bisa bekerja untuk tool lain sementara Claude Code tetap gagal jika /v1/messages, streaming, atau header Anthropic yang diperlukan tidak ada.
Nilai Flatkey yang diverifikasi untuk setup ini
Beranda Flatkey yang diperiksa pada 29 Juni 2026 memiliki judul One API gateway for production AI teams dan deskripsi meta yang menyatakan Flatkey menyatukan akses model, routing, billing, analitik penggunaan, dan kontrol operasional. Beranda yang sama masih menampilkan contoh bergaya OpenAI menggunakan https://console.flatkey.ai/v1 dan /v1/chat/completions, yang berguna untuk tool yang kompatibel dengan OpenAI tetapi bukan pola base URL Claude Code.
Halaman use-case Flatkey Claude Code saat ini menyebutkan bahwa Claude Code dikonfigurasi dengan https://router.flatkey.ai dan kunci API Flatkey. Halaman itu juga memberi tahu pengguna untuk membuat atau menyalin kunci di https://console.flatkey.ai/keys sebelum menjalankan installer. Gunakan root router khusus Claude Code tersebut untuk penyiapan manual di bawah ini, kecuali akun Flatkey Anda memberikan nilai yang lebih baru.
Halaman harga Flatkey yang diperiksa pada 29 Juni 2026 menerbitkan harga yang dirender di server untuk 635 model AI dari 23 penyedia. Peta endpoint-nya mencakup /v1/messages, /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/video/generations, dan /v1beta/models/{model}:generateContent. Artikel ini memperlakukan itu sebagai bukti publik yang sudah bertanggal untuk cakupan endpoint, bukan sebagai jaminan bahwa setiap akun bisa memanggil setiap model.
Penyiapan langkah demi langkah dengan Flatkey
- Buat atau pilih kunci Flatkey. Gunakan kunci yang dimiliki oleh orang, tim, atau lingkungan yang tepat. Jangan tampilkan di tangkapan layar, prompt, repositori, atau komentar issue.
- Mulai dengan ekspor shell. Jangan simpan pengaturan secara permanen sampai preflight satu token berhasil.
- Gunakan root router Claude Code. Untuk halaman Flatkey Claude Code saat ini, nilainya adalah
https://router.flatkey.ai. - Pilih variabel kredensial. Gunakan
ANTHROPIC_AUTH_TOKENketika kunci harus dikirim sebagaiAuthorization: Bearer. GunakanANTHROPIC_API_KEYhanya ketika gateway mengharapkanx-api-key. - Setel model untuk pengujian pertama. Gunakan ID model Claude terbaru yang diaktifkan untuk akun Flatkey Anda. Jika model tidak terlihat di pemilih Claude Code, gunakan discovery gateway atau tambahkan opsi model kustom setelah preflight berhasil.
- Jalankan preflight curl. Permintaan satu token memisahkan routing Flatkey dari status UI Claude Code.
- Mulai Claude Code dari shell yang sama. Ini membuat CLI mewarisi variabel yang baru saja Anda uji.
- Jalankan
/status. Pastikan baris Anthropic base URL menampilkan router Flatkey dan baris kredensial menyebutkan variabel yang Anda setel. - Kirim satu prompt kecil. Lalu periksa penggunaan Flatkey dan telemetry Claude Code apa pun yang Anda aktifkan.
Penyiapan shell
export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_AUTH_TOKEN="fk_replace_with_your_flatkey_key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"Jika instruksi gateway Anda secara eksplisit menyebut x-api-key, ganti ANTHROPIC_AUTH_TOKEN dengan ANTHROPIC_API_KEY dan perbarui header preflight. Jangan setel keduanya untuk pengujian pertama; sumber kredensial yang tercampur membuat kegagalan lebih sulit diisolasi.
Pengaturan persisten setelah pengujian berhasil
Setelah pengujian shell berhasil, Anda bisa menempatkan variabel yang sama di blok env pada ~/.claude/settings.json. Jangan letakkan kredensial di .claude/settings.json proyek yang sudah dikomit.
{
"env": {
"ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
"ANTHROPIC_AUTH_TOKEN": "fk_replace_with_your_flatkey_key",
"ANTHROPIC_MODEL": "claude-sonnet-4-6"
}
}Preflight route Messages sebelum meluncurkan Claude Code
Pemeriksaan Claude Code API router tercepat adalah permintaan Messages satu token. Jika ini gagal, perbaiki kunci Flatkey, base URL, jalur jaringan, atau model sebelum mengubah pengaturan Claude Code.
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": "."}
]
}'Respons JSON yang dimulai dengan ID pesan dan menyertakan field content berarti route dan kredensial berfungsi. Dokumen resmi juga mencatat bahwa error unknown-model tetap membuktikan gateway mengautentikasi permintaan sebelum menolak nama model. 401 berarti kredensial ditolak atau dikirim di header yang salah.
Perhatikan URL yang terselesaikan dengan cermat. Dengan ANTHROPIC_BASE_URL=https://router.flatkey.ai, pengujian mencapai https://router.flatkey.ai/v1/messages. Jika perintah Anda membuat /v1/v1/messages, Anda menyalin base URL SDK klien ke field gateway Claude Code.
Nama model: alias, discovery, dan entri kustom
Nama model adalah sumber kegagalan Claude Code API router kedua yang paling umum. Base URL mengarahkan lalu lintas ke Flatkey, tetapi Claude Code tetap memerlukan nilai model untuk dikirim dalam permintaan.
Dokumentasi konfigurasi model mengatakan bahwa Claude Code mendukung pengaturan model bawaan seperti default, best, sonnet, opus, haiku, serta varian konteks panjang seperti sonnet[1m] dan opus[1m]. Dokumen yang sama mengatakan bahwa ANTHROPIC_MODEL hanya berlaku untuk sesi yang Anda luncurkan dengannya, sedangkan /model dapat menyimpan pilihan interaktif untuk sesi berikutnya.
Untuk route Flatkey, aturan aman adalah memulai dengan ID model Claude lengkap yang telah diaktifkan Flatkey untuk kunci Anda, lalu memutuskan apakah akan menampilkannya di pemilih. Jangan mengasumsikan bahwa nama keluarga generik, label pemasaran, atau judul baris penyedia diterima sebagai ID model permintaan.
| Kebutuhan pengaturan model | Mekanisme Claude Code | Pemeriksaan Flatkey |
|---|---|---|
| Uji satu sesi | ANTHROPIC_MODEL atau claude --model |
Gunakan ID model Claude yang mendukung Flatkey dan jaga pengujian tetap kecil. |
| Seleksi interaktif | /model |
Konfirmasikan bahwa nama yang dipilih adalah ID sebenarnya yang diharapkan Flatkey. |
| Daftar model yang disediakan gateway | CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 |
Gateway harus menyajikan /v1/models dengan cepat di base URL yang dikonfigurasi. |
| Entri pemilih manual | ANTHROPIC_CUSTOM_MODEL_OPTION |
Gunakan ini ketika discovery dinonaktifkan atau tidak mengembalikan model yang Anda butuhkan. |
| Fallback ketersediaan | --fallback-model atau fallbackModel |
Fallback tidak memperbaiki kesalahan autentikasi, penagihan, rate limit, ukuran permintaan, atau transport. |
Discovery model gateway
Claude Code dapat mengkueri endpoint /v1/models milik gateway saat startup ketika ANTHROPIC_BASE_URL mengarah ke gateway Anthropic Messages dan discovery diaktifkan. Dokumen protokol menyebutkan bahwa permintaannya adalah GET /v1/models?limit=1000 dengan timeout 3 detik, dan Claude Code membaca id plus display_name opsional dari respons.
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude --debugDiscovery dimatikan secara default agar satu kunci bersama tidak mengekspos semua model yang dapat dijangkau kepada setiap pengguna. Jika discovery gagal, Claude Code akan kembali ke pemilih yang dicache atau bawaan. Jika akun Flatkey Anda menyajikan model dengan alias yang tidak ditampilkan oleh discovery, tambahkan opsi kustom sebagai gantinya.
Opsi model kustom
export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet via Flatkey"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Model Claude yang dirutekan melalui Flatkey API router"Opsi model kustom melewati validasi sisi klien untuk ID model tersebut, sehingga berguna untuk pilot yang terkontrol. Ini bukan pengganti request preflight. Jika allowlist organisasi aktif, sertakan juga ID model kustom di sana.
Log penggunaan: apa yang harus diperiksa setelah prompt pertama
Setup Claude Code API router yang andal berakhir dengan bukti penggunaan, bukan hanya respons yang berhasil. Posisi publik Flatkey menyatakan bahwa ia menyatukan penagihan, analitik penggunaan, dan kontrol operasional; dokumen gateway Claude Code juga membingkai pelacakan penggunaan dan kontrol biaya sebagai manfaat gateway. Gunakan kedua lapisan ini secara sengaja.
| Sumber log | Yang perlu diperiksa | Mengapa ini penting |
|---|---|---|
| Penggunaan Flatkey | Pemilik kunci, timestamp, model, keluarga endpoint, penggunaan token, dan catatan biaya jika tersedia | Memastikan permintaan mencapai akun gateway yang dituju dan dapat direkonsiliasi oleh ops atau finance. |
/status Claude Code |
Base URL Anthropic dan sumber kredensial aktif | Memastikan sesi yang berjalan menggunakan rute Flatkey alih-alih login claude.ai yang tersimpan. |
| Metrik OpenTelemetry | claude_code.cost.usage, claude_code.token.usage, jumlah sesi, waktu aktif, dan entrypoint |
Menciptakan observabilitas tingkat tim untuk sesi Claude Code. |
| Log/event OpenTelemetry | Event prompt, hasil alat, error API, dan field biaya saat dikonfigurasi | Membantu men-debug kegagalan di tingkat permintaan, tetapi harus dibatasi karena log detail dapat mengekspos konten sensitif. |
| Header gateway | x-claude-code-session-id, ID agen, dan header routing kustom |
Memungkinkan pengelompokan permintaan berdasarkan sesi atau subagent tanpa mem-parsing seluruh body permintaan. |
Untuk telemetry Claude Code, aktifkan OpenTelemetry hanya dengan pengaturan privasi yang disengaja. Dokumen monitoring mengatakan teks prompt disunting secara default, sementara pengaturan seperti OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1, dan OTEL_LOG_RAW_API_BODIES menambahkan detail sensitif. Jangan sertakan logging body mentah dalam setup developer default kecuali tinjauan keamanan Anda menyetujuinya.
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"Gunakan OTEL_RESOURCE_ATTRIBUTES untuk field kepemilikan dengan kardinalitas rendah seperti departemen, ID tim, atau cost center. Hindari nama proyek atau ID tiket yang dimasukkan pengguna sebagai label kecuali backend observabilitas Anda dapat menangani dampak kardinalitas dan privasi.
Mode kegagalan yang harus di-debug terlebih dahulu
| Gejala | Kemungkinan penyebab | Perbaikan pertama |
|---|---|---|
401 atau token tidak valid |
Kunci ditolak, kedaluwarsa, disalin ke variabel yang salah, atau dikirim dalam header yang tidak dibaca gateway. | Berpindahlah antara ANTHROPIC_AUTH_TOKEN dan ANTHROPIC_API_KEY hanya setelah mengonfirmasi header mana yang diharapkan Flatkey. |
| Koneksi ditolak atau timeout | Base URL salah, jalur jaringan diblokir, masalah VPN, atau endpoint router yang tidak dapat dijangkau dari mesin developer. | Jalankan preflight curl dan verifikasi URL dengan instruksi akun Flatkey Anda. |
| Respons tidak valid dengan HTTP 200 | Proxy atau halaman login mengembalikan HTML вместо API JSON. | Periksa body respons preflight dan perbaiki rute gateway yang mengembalikan non-JSON. |
400 menyebut context_management atau field tambahan |
Gateway meneruskan field permintaan format Anthropic ke upstream yang menolaknya. | Teruskan pasangan header/body beta dengan benar atau set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 sebagai mitigasi sementara. |
400 menyebut thinking atau adaptive |
Build model upstream tidak menerima penalaran adaptif yang diminta untuk model Claude yang lebih baru. | Upgrade rute upstream, atau gunakan flag nonaktif adaptive-thinking yang didokumentasikan hanya di tempat yang berlaku. |
Model tidak muncul di /model |
Model tidak ada di pemilih bawaan Claude Code dan discovery dinonaktifkan atau gagal. | Aktifkan discovery model gateway atau tambahkan ANTHROPIC_CUSTOM_MODEL_OPTION. |
| Claude Code meminta login setelah curl berhasil | CLI tidak menerima kredensial di tempat yang dapat dibaca oleh pengaturan pertama kali. | Atur kredensial di shell, ~/.claude/settings.json, atau managed settings sebelum startup. |
| Penggunaan tidak dapat direkonsiliasi | Setup tidak memiliki pemilik kunci, nama model, environment, ID sesi, atau label telemetry. | Tambahkan baris runbook sebelum lebih banyak developer menggunakan rute tersebut. |
Checklist produksi untuk tim
Sebelum Anda menstandardisasi Claude Code API router di seluruh tim, catat fakta operasional yang akan dibutuhkan oleh insiden di masa depan atau review keuangan.
| Item checklist | Catat ini |
|---|---|
| Base URL | Nilai tepat yang disimpan di shell, managed settings, pengaturan VS Code, CI, atau konfigurasi Agent SDK. |
| Sumber kredensial | Pemilik kunci Flatkey, environment, pemilik rotasi, dan apakah sifatnya statis atau berasal dari apiKeyHelper. |
| Nama model | ID model yang diminta, label pemilih, rantai fallback, aturan allowlist, dan tanggal pengujian. |
| Bukti endpoint | Hasil /v1/messages satu token, timestamp permintaan, dan request ID apa pun yang dikembalikan gateway. |
| Tinjauan penggunaan | Tampilan penggunaan Flatkey, backend telemetry Claude Code, label, dan pemilik dashboard. |
| Pagar privasi | Apakah prompt, detail tool, body API mentah, atau konten tool diizinkan dalam telemetry. |
| Rollback | Login Claude Code atau jalur provider sebelumnya, model sebelumnya, dan siapa yang dapat menghapus variabel gateway. |
Jalur migrasi internal
Jika Flatkey menjadi rute bersama untuk beberapa alat developer, jaga agar setup Claude Code selaras dengan klaster integrasi lainnya. Gunakan panduan migrasi API yang kompatibel dengan OpenAI untuk pola base URL SDK, tetapi ingat bahwa Claude Code menggunakan rute Anthropic Messages alih-alih /v1/chat/completions.
Untuk setup desktop client, bandingkan dengan panduan setup API Cherry Studio. Untuk pola routing mesin developer yang berdekatan dengan Claude Code, lihat setup cc-switch Claude Code. Setelah prompt pertama berfungsi, tinjau harga model Flatkey, lalu Dapatkan kunci untuk setiap environment tambahan yang memerlukan batas kredensial terpisah.
Pertanyaan yang sering diajukan
Base URL apa yang harus saya gunakan untuk router API Claude Code dengan Flatkey?
Gunakan root router Flatkey khusus Claude Code yang ditampilkan untuk akun Anda. Pada 29 Juni 2026, halaman use-case Claude Code milik Flatkey menyebutkan bahwa Claude Code dikonfigurasi dengan https://router.flatkey.ai. Preflight harus mencapai tepat satu path /v1/messages.
Haruskah saya menggunakan ANTHROPIC_AUTH_TOKEN atau ANTHROPIC_API_KEY?
Gunakan ANTHROPIC_AUTH_TOKEN ketika gateway mengharapkan bearer token di header Authorization. Gunakan ANTHROPIC_API_KEY ketika gateway mengharapkan x-api-key. Jika Anda menebak dan mendapatkan 401, ganti variabelnya dan uji ulang.
Bisakah saya menggunakan base URL Flatkey yang kompatibel dengan OpenAI untuk Claude Code?
Tidak secara langsung sebagai field yang disalin. Alat yang kompatibel dengan OpenAI sering menggunakan base URL yang berakhiran /v1, sedangkan Claude Code menambahkan /v1/messages ke ANTHROPIC_BASE_URL. Gunakan nilai router Flatkey Claude Code dan verifikasi URL akhirnya.
Bagaimana cara menambahkan model Flatkey ke pemilih model Claude Code?
Aktifkan CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 saat gateway menyajikan /v1/models, atau tambahkan satu baris pemilih manual dengan ANTHROPIC_CUSTOM_MODEL_OPTION. Dalam kedua kasus, pastikan ID model yang tepat diaktifkan untuk kunci Flatkey Anda.
A log penggunaan apa yang harus saya periksa setelah setup?
Periksa penggunaan Flatkey untuk kunci, model, family endpoint, stempel waktu, token, dan biaya jika tersedia. Juga gunakan /status Claude Code dan metrik OpenTelemetry seperti claude_code.cost.usage dan claude_code.token.usage saat telemetri organisasi diaktifkan.
Kesimpulan
Setup Claude Code API router yang andal memiliki empat poin pembuktian: base URL Claude Code Flatkey, header kredensial yang benar, nama model yang telah diuji, dan jejak penggunaan yang dapat ditinjau oleh tim keuangan dan platform. Mulailah dengan preflight satu token /v1/messages, konfirmasikan /status, lalu skalakan rute hanya setelah log dan rollback didokumentasikan. Saat Anda siap merutekan Claude Code melalui gateway bersama, Dapatkan kunci dan uji prompt paling kecil terlebih dahulu.
