Kunci API Claude Code—di mana mendapatkannya, di mana menaruhnya, dan mengapa variabel yang salah gagal secara diam-diam

Claude Code dapat melakukan autentikasi dengan dua cara berbeda, dan cara yang Anda perlukan menentukan hal-hal lainnya. Login langganan claude.ai mencakup penggunaan dalam paket Pro atau Max Anda. Kunci API menagih per token tanpa batas paket. Panduan ini menjelaskan tempat mendapatkan kunci, lokasi tepat untuk menaruhnya, dua variabel kredensial dan alasan pemilihan variabel yang salah menyebabkan kegagalan diam-diam, serta cara menjaga tagihan tetap terkendali setelah semuanya berjalan.

Apakah Anda benar-benar memerlukan kunci?

Perlu diketahui sebelum memulai: menetapkan kunci menjeda langganan Anda. Selama variabel kredensial aktif, Claude Code menggunakannya sebagai pengganti login claude.ai yang tersimpan, batas paket tidak lagi berlaku, dan penggunaan ditagihkan kepada pemilik kunci. Hapus variabel tersebut dan Claude Code kembali ke langganan.

Opsi 1 — kunci Anthropic pihak pertama

1. Masuk ke console.anthropic.com (akun terpisah dari claude.ai).
2. Tambahkan kredit di Billing. API bersifat prabayar dan terpisah dari langganan apa pun — paket Pro tidak membiayainya.
3. Buat kunci di API Keys. Kunci tersebut diawali sk-ant- dan hanya ditampilkan sekali.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

Perhatikan langkah kedua dalam cuplikan tersebut. ANTHROPIC_API_KEY dikirim dalam header x-api-key dan memerlukan persetujuan interaktif satu kali sebelum Claude Code dapat menggunakannya. Jika prompt tersebut pernah ditolak, kunci akan diabaikan setelahnya tanpa prompt sama sekali — yang terlihat persis seperti variabel tidak terbaca. Aktifkan kembali melalui /config → Use custom API key.

Opsi 2 — kunci dengan biaya per token lebih rendah

Claude Code membaca ANTHROPIC_BASE_URL secara native, sehingga dapat digunakan pada endpoint apa pun yang menyediakan Anthropic Messages API — tanpa plugin, proxy, atau binary yang ditambal. Itulah jalur yang didukung untuk gateway, dan cara menjalankan model Claude yang sama dengan tarif lebih rendah:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL hanya merupakan asal — Claude Code sendiri menambahkan /v1/messages. Pertahankan baris model: default bawaan Claude Code dan alias opus keduanya mengarah ke Opus terbaru, dan jika Kunavo belum menyediakan model tersebut, permintaan pertama mengembalikan 404. Baris opus menetapkannya ke Claude Opus 5.5, yang memerlukan Claude Code v2.1.280 atau yang lebih baru (jalankan claude update pada versi yang lebih lama). Alias sonnet meminta Sonnet 5.5, yang tidak disediakan Kunavo, sehingga tanpa ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, fase eksekusi opusplan dan subagen yang disetel ke sonnet semuanya mengembalikan 404. Buat kunci sk-kn- di dasbor setelah mendaftar dan mengisi ulang $10. Tidak ada biaya bulanan dan saldo tidak kedaluwarsa.

Itu sekitar 30% di bawah harga daftar untuk model utama. Tarif lengkap tersedia dalam panduan harga Claude API, dan harga Claude Code membandingkan rute ini dengan biaya paket Pro dan Max; penyiapan lengkap, termasuk perutean model per tugas dan perubahan di balik gateway, tersedia dalam panduan router Claude Code. Jika CLI belum terpasang, mulai dari instal Claude Code.

Tempat kunci sebenarnya diletakkan

Dua variabel, dua header HTTP yang berbeda. Kunci pada header yang tidak dibaca server akan gagal dengan 401:

Jika Anda tidak diberi tahu jenis kunci yang dimiliki, mulai dengan ANTHROPIC_AUTH_TOKEN, yang tidak memerlukan langkah persetujuan. Di Kunavo, kedua variabel juga memungkinkan Claude Code menemukan daftar model, karena /v1/models membaca kunci dari salah satu header.

Ekspor shell vs file settings

Ekspor shell hanya berlaku untuk terminal tersebut dan proses turunannya. Editor yang dibuka dari dock tidak akan melihatnya, begitu pula agent latar belakang. Untuk penggunaan permanen, gunakan blok env dari ~/.claude/settings.json — kunci yang sama berlaku di mana pun Claude Code berjalan. Jangan menaruh kunci dalam .claude/settings.json proyek; file itu di-commit dan dibagikan kepada semua orang yang mengkloning repositori.

Jalankan /status untuk mengonfirmasi kredensial yang aktif. Baris Auth token atau API key yang menyebut variabel Anda berarti kunci aktif; baris Login method yang menyebut akun claude.ai berarti kunci tidak aktif.

Merotasi kunci tanpa mengedit file

Jika kredensial kedaluwarsa menurut jadwal atau berasal dari vault, arahkan apiKeyHelper ke perintah yang mencetak kunci terbaru:

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

Referensikan sebagai "apiKeyHelper": "~/bin/get-key.sh" dalam file settings Anda. Claude Code menyimpan output selama lima menit dan menjalankannya kembali pada 401; sesuaikan dengan CLAUDE_CODE_API_KEY_HELPER_TTL_MS. Nilai tersebut dikirim dalam kedua header, sehingga dapat digunakan dengan cara apa pun.

Menjaga tagihan tetap dapat diprediksi

Coding agentic menghabiskan banyak token — setiap langkah mengirim ulang system prompt, riwayat tugas, dan konteks file terbaru. Empat hal yang lebih penting daripada yang lain:

1. Pertahankan baris Haiku. Tanpa ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5, alias haiku Claude Code meminta ID model yang tidak disediakan Kunavo (Haiku 5.5 sejak v2.1.293), sehingga /model haiku dan subagen yang ditetapkan ke haiku menghasilkan 404. Baris yang sama mengalihkan pembuatan ringkasan dan judul otomatis Claude Code dari model utama Anda, dengan penghematan yang makin besar saat pekerjaan dibagi ke beberapa tugas, seperti dijelaskan dalam biaya alur kerja Claude Code.
2. Dua variabel yang sama juga merutekan Agent SDK. Agent SDK tidak memiliki opsi base URL sendiri — SDK ini menjalankan CLI tersebut dan meneruskan lingkungan Anda secara langsung, sehingga program Agent SDK dirutekan tepat berdasarkan konfigurasi di atas.
3. Mulai tugas baru daripada memperpanjang satu tugas selamanya. Konteks dikirim ulang di setiap langkah, sehingga sesi panjang menjadi mahal secara kuadratik. Tingkat yang sebaiknya dipasang pada model utama dibahas dalam Opus vs Sonnet vs Haiku, berdasarkan biaya per tugas selesai, bukan biaya per token.
4. Biarkan caching prompt bekerja. Input yang di-cache ditagih sebesar 10% dari tarif input, dan rute Messages API native meneruskan cache_control tanpa diterjemahkan (detail).
5. Beri editor kuncinya sendiri dengan batas pengeluaran di dasbor, lalu periksa penggunaan setelah seminggu. Batas per kunci mengubah loop yang tidak terkendali menjadi loop yang dibatasi.

Pemecahan masalah

Pertanyaan umum