Prasyarat
Sebelum mengonfigurasi Claude Code dengan Amazon Bedrock, pastikan Anda memiliki:- Akun AWS dengan akses Amazon Bedrock yang diaktifkan
- Akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6) di Amazon Bedrock
- AWS CLI terinstal dan dikonfigurasi (opsional - hanya diperlukan jika Anda tidak memiliki mekanisme lain untuk mendapatkan kredensial)
- Izin IAM yang sesuai
Masuk dengan Bedrock
Jika Anda memiliki kredensial AWS dan ingin mulai menggunakan Claude Code melalui Amazon Bedrock, wizard login akan memandu Anda. Anda menyelesaikan prasyarat sisi AWS sekali per akun; wizard menangani sisi Claude Code.1
Aktifkan model Anthropic di akun AWS Anda
Di konsol Amazon Bedrock, buka katalog Model, pilih model Anthropic, dan kirimkan formulir kasus penggunaan. Akses diberikan segera setelah pengiriman. Lihat Kirimkan detail kasus penggunaan untuk AWS Organizations dan konfigurasi IAM untuk izin yang dibutuhkan peran Anda.
2
Mulai Claude Code dan pilih Amazon Bedrock
Jalankan
claude. Pada prompt login, pilih 3rd-party platform, kemudian Amazon Bedrock.3
Ikuti prompt wizard
Pilih cara Anda melakukan autentikasi ke AWS: profil AWS yang terdeteksi dari direktori
~/.aws Anda, kunci API Amazon Bedrock, kunci akses dan rahasia, atau kredensial yang sudah ada di lingkungan Anda. Wizard mengambil wilayah Anda, memverifikasi model Claude mana yang dapat dijalankan akun Anda, dan memungkinkan Anda untuk meminnya. Ini menyimpan hasilnya ke blok env dari file pengaturan pengguna Anda, jadi Anda tidak perlu mengekspor variabel lingkungan sendiri./setup-bedrock kapan saja untuk membuka kembali wizard dan mengubah kredensial, wilayah, atau pin model Anda. Langkah pin model dimulai dari model yang saat ini Anda pin. Wizard menulis ke ~/.claude/settings.json, atau ke $CLAUDE_CONFIG_DIR/settings.json ketika CLAUDE_CONFIG_DIR diatur.
Pengaturan manual
Untuk mengonfigurasi Amazon Bedrock melalui variabel lingkungan alih-alih wizard, misalnya di CI atau peluncuran perusahaan yang ditulis skrip, ikuti langkah-langkah di bawah ini.
- Kirimkan detail kasus penggunaan
Pengguna pertama kali dari model Anthropic harus mengirimkan detail kasus penggunaan sebelum memanggil model. Ini dilakukan sekali per akun AWS.
- Pastikan Anda memiliki izin IAM yang tepat seperti yang dijelaskan di bawah
- Navigasikan ke konsol Amazon Bedrock
- Pilih model Anthropic dari Model catalog
- Lengkapi formulir kasus penggunaan. Akses diberikan segera setelah pengiriman.
PutUseCaseForModelAccess API. Panggilan ini memerlukan izin IAM bedrock:PutUseCaseForModelAccess. Persetujuan meluas ke akun anak secara otomatis.
- Konfigurasi kredensial AWS
Claude Code menggunakan rantai kredensial SDK AWS default. Atur kredensial Anda menggunakan salah satu metode berikut:
Opsi A: Konfigurasi AWS CLI
your-profile-name dengan nama profil AWS Anda sebelum menjalankan perintah ini.
sso_region profil, yang tidak perlu cocok dengan wilayah tempat Anda menjalankan Amazon Bedrock. Dalam v2.1.207, wilayah Amazon Bedrock mengganti sso_region, jadi profil yang instance IAM Identity Center-nya berada di wilayah berbeda gagal untuk mengautentikasi dengan kesalahan Session token not found or invalid.
Opsi D: Kredensial AWS Management Console
aws login.
Opsi E: Kunci API Amazon Bedrock
Caching kredensial dan timeout resolusi
Claude Code menyelesaikan rantai penyedia kredensial default AWS sekali dan menyimpan kredensial yang diselesaikan dalam memori. Kredensial tersebut digunakan kembali hingga lima menit sebelum kedaluwarsa, atau selama satu jam ketika tidak memiliki kedaluwarsa, jadi profil yang didukung SSO meminta kredensial dari IAM Identity Center sekitar sekali per masa hidup kredensial. Kesalahan kredensial dari API menghapus cache, dan retry menyelesaikan kredensial segar. Sebelum v2.1.207, Claude Code menyelesaikan rantai pada setiap permintaan API, jadi profil yang didukung SSO meminta kredensial segar dari IAM Identity Center setiap kali dan dapat dibatasi dalam penerapan besar. Cache mencakup setiap opsi kredensial di atas kecuali kunci API Amazon Bedrock, yang tidak menggunakan rantai penyedia. Untuk menyelesaikan rantai pada setiap permintaan alih-alih, aturCLAUDE_CODE_SKIP_AWS_CRED_CACHE=1.
Setiap resolusi rantai habis waktu setelah 60 detik. Jika langkah dalam rantai macet, misalnya pembantu credential_process yang menunggu input yang tidak dapat diterima, permintaan gagal dengan AWS default-chain credential resolve timed out. Jika rantai Anda menjalankan sign-in interaktif yang secara sah memerlukan waktu lebih lama, seperti SSO berbasis browser dengan MFA melalui wrapper seperti aws-vault, naikkan batas dalam milidetik dengan CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS. Sebelum v2.1.207, resolusi kredensial yang macet membiarkan permintaan menunggu tanpa batas.
Konfigurasi kredensial lanjutan
Claude Code mendukung penyegaran kredensial otomatis untuk AWS SSO dan penyedia identitas perusahaan. Tambahkan pengaturan ini ke file pengaturan Claude Code Anda (lihat Settings untuk lokasi file). Kedua pengaturan ini memiliki kondisi pemicu yang berbeda:awsAuthRefresh: berjalan hanya ketika Claude Code mendeteksi bahwa kredensial AWS Anda telah kedaluwarsa, baik secara lokal berdasarkan stempel waktu mereka atau ketika API mengembalikan kesalahan kredensial, kemudian mencoba ulang permintaan dengan kredensial yang disegarkan.awsCredentialExport: berjalan saat awal sesi dan pada setiap pemuatan ulang kredensial, bahkan ketika kredensial di rantai penyedia kredensial default AWS Anda masih valid. Gunakan ini ketika akun Amazon Bedrock Anda memerlukan kredensial lintas akun yang berbeda dari yang akan diselesaikan oleh rantai penyedia default.
awsAuthRefresh: Gunakan ini untuk perintah yang memodifikasi direktori .aws, seperti memperbarui kredensial, cache SSO, atau file konfigurasi. Output perintah ditampilkan kepada pengguna, tetapi input interaktif tidak didukung. Ini bekerja dengan baik untuk alur SSO berbasis browser di mana CLI menampilkan URL atau kode dan Anda menyelesaikan autentikasi di browser.
awsCredentialExport: Hanya gunakan ini jika Anda tidak dapat memodifikasi .aws dan harus secara langsung mengembalikan kredensial. Perintah ini berjalan setiap kali kredensial perlu disegarkan, bukan hanya ketika kredensial telah kedaluwarsa. Output ditangkap secara diam-diam dan tidak ditampilkan kepada pengguna. Perintah harus menampilkan JSON dalam format ini:
aws configure export-credentials --format process juga diterima, dengan kunci yang sama di tingkat atas alih-alih bersarang di bawah Credentials.
Expiration bersifat opsional. Mulai dari Claude Code v2.1.176, ketika perintah mengembalikan Expiration ISO 8601 yang valid, Claude Code menyimpan kredensial dalam cache hingga lima menit sebelum waktu tersebut. Tanpanya, atau pada versi sebelumnya, kredensial disimpan dalam cache selama satu jam.
Ketika Anda mengonfigurasi awsCredentialExport tanpa awsAuthRefresh, Claude Code menggunakan kredensial yang diekspor secara langsung dan tidak menyelesaikan kembali rantai penyedia kredensial default AWS saat startup. Sebelum v2.1.206, startup juga menyelesaikan kembali rantai penyedia default, yang membuat panggilan SSO atau STS langsung di luar konfigurasi proxy Anda dan dapat memblokir prompt pertama selama beberapa menit di jaringan dengan egress terbatas.
- Konfigurasi Claude Code
Atur variabel lingkungan berikut untuk mengaktifkan Amazon Bedrock:
-
Mulai dari v2.1.172, Anda hanya perlu menetapkan
AWS_REGIONuntuk mengganti wilayah profil AWS Anda atau ketika profil Anda tidak memiliki wilayah. Claude Code menyelesaikan wilayah dalam urutan ini:AWS_REGIONAWS_DEFAULT_REGIONregionyang ditetapkan pada profil AWS aktif Anda, dibaca dari file kredensial bersama AWS terlebih dahulu dan kemudian file konfigurasi bersama, sesuai dengan prioritas SDK AWSus-east-1
AWS_PROFILEjika diatur, jika tidakdefault. AturAWS_SHARED_CREDENTIALS_FILEatauAWS_CONFIG_FILEuntuk menunjuk ke jalur file non-default. Jalankan/statusuntuk melihat wilayah yang diselesaikan. Ketika wilayah berasal dari file konfigurasi AWS Anda atau fallback default,/statusjuga mencatat sumbernya. Pada v2.1.171 dan sebelumnya, Claude Code tidak membaca file konfigurasi AWS, jadi aturAWS_REGIONsecara eksplisit. -
Saat menggunakan Amazon Bedrock, perintah
/logouttidak tersedia karena autentikasi ditangani melalui kredensial AWS. - Alat WebSearch tidak tersedia di Amazon Bedrock. Lihat perilaku alat WebSearch.
-
Anda dapat menggunakan file pengaturan untuk variabel lingkungan seperti
AWS_PROFILEyang tidak ingin Anda bocorkan ke proses lain. Lihat Settings untuk informasi lebih lanjut.
- Pin versi model
Atur variabel lingkungan ini ke ID model Amazon Bedrock spesifik.
Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Amazon Bedrock diselesaikan ke Opus 4.8, dan tanpa ANTHROPIC_DEFAULT_SONNET_MODEL, alias sonnet diselesaikan ke Sonnet 4.5. Contoh ini pin setiap alias ke versi spesifik:
us.). Jika Anda menggunakan awalan wilayah berbeda atau profil inferensi aplikasi, sesuaikan sesuai kebutuhan. Di wilayah AWS GovCloud, gunakan awalan us-gov.. Untuk ID model saat ini dan warisan, lihat Models overview. Lihat Model configuration untuk daftar lengkap variabel lingkungan.
Claude Code menggunakan model default ini ketika tidak ada variabel pinning yang diatur:
Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Amazon Bedrock, Claude Code menggunakan model Sonnet default untuk tugas latar belakang karena Haiku mungkin tidak diaktifkan di setiap akun atau wilayah. Dua pilihan mengubah model mana yang membawanya:
- Ketika Anda memilih model utama dengan
--model,ANTHROPIC_MODEL, atau pengaturanmodel, tugas latar belakang menggunakan model tersebut. MenetapkanANTHROPIC_DEFAULT_OPUS_MODELtanpaANTHROPIC_DEFAULT_SONNET_MODELjuga dihitung sebagai pilihan, karena model Sonnet bawaan mungkin tidak diaktifkan di akun yang mengarahkan Opus-nya sendiri. - Untuk menggunakan Haiku untuk tugas latar belakang, atur
ANTHROPIC_DEFAULT_HAIKU_MODELke ID model yang tersedia di akun Anda.
opus diselesaikan ke Opus 4.6, dan tugas latar belakang selalu menggunakan model utama.
Untuk menyesuaikan model lebih lanjut, gunakan salah satu metode berikut:
Prompt caching mungkin tidak tersedia di semua wilayah Amazon Bedrock. Jika hitungan token cache tetap di nol, periksa model, wilayah, dan batas yang didukung dalam dokumentasi Amazon Bedrock.
Petakan setiap versi model ke profil inferensi
Variabel lingkunganANTHROPIC_DEFAULT_*_MODEL mengonfigurasi satu profil inferensi per keluarga model. Jika organisasi Anda perlu mengekspos beberapa versi dari keluarga yang sama di pemilih /model, masing-masing dirutekan ke ARN profil inferensi aplikasi sendiri, gunakan pengaturan modelOverrides di file pengaturan Anda sebagai gantinya.
Contoh ini memetakan empat versi Opus ke ARN yang berbeda sehingga pengguna dapat beralih di antara mereka tanpa melewati profil inferensi organisasi Anda:
/model, Claude Code memanggil Amazon Bedrock dengan ARN yang dipetakan. Pemetaan yang sama berlaku ketika Anda meneruskan ID model Anthropic secara langsung melalui --model atau ANTHROPIC_MODEL. Versi tanpa override kembali ke ID model Amazon Bedrock bawaan atau profil inferensi yang cocok yang ditemukan saat startup. Sebelum v2.1.200, nilai --model dan ANTHROPIC_MODEL mencapai Amazon Bedrock apa adanya tanpa melewati peta override. Lihat Override model IDs per version untuk detail tentang bagaimana override berinteraksi dengan availableModels dan pengaturan model lainnya.
Pemeriksaan model startup
Ketika Claude Code dimulai dengan Amazon Bedrock dikonfigurasi, Claude Code memverifikasi bahwa model yang dimaksudkan untuk digunakan dapat diakses di akun Anda. Jika Anda telah mempin versi model yang lebih lama dari default Claude Code saat ini, dan akun Anda dapat memanggil versi yang lebih baru, Claude Code meminta Anda untuk memperbarui pin. Menerima menulis ID model baru ke file pengaturan pengguna Anda dan memulai ulang Claude Code. Menolak diingat sampai perubahan versi default berikutnya. Pin yang menunjuk ke ARN profil inferensi aplikasi dilewati, karena dikelola oleh administrator Anda. Jika Anda belum mempin model dan default saat ini tidak tersedia di akun Anda, Claude Code kembali untuk sesi saat ini dan menampilkan pemberitahuan. Claude Code mencoba versi sebelumnya dari model default terlebih dahulu dan, ketika default adalah model Opus dan tidak ada versi Opus yang tersedia, kembali ke model Sonnet default. Fallback tidak disimpan. Aktifkan model yang lebih baru di akun Amazon Bedrock Anda atau pin versi untuk membuat pilihan permanen.Konfigurasi IAM
Buat kebijakan IAM dengan izin yang diperlukan untuk Claude Code:bedrock:GetInferenceProfile memungkinkan Claude Code menyelesaikan ARN profil inferensi aplikasi ke model fondasi pendukungnya, yang digunakan untuk memilih bentuk permintaan yang benar untuk model tersebut.
Jika token tidak memiliki izin ini, Claude Code pulih secara otomatis dengan mencoba ulang sekali dengan bentuk alternatif, sehingga permintaan tetap berhasil tetapi setiap model baru menambahkan perjalanan bolak-balik ekstra. Memberikan izin menghindari percobaan ulang. Ini paling sering berlaku untuk penyebaran AWS_BEARER_TOKEN_BEDROCK, di mana kebijakan token biasanya lebih sempit daripada peran IAM penuh.
Untuk detail, lihat dokumentasi IAM Bedrock.
Buat akun AWS khusus untuk Claude Code untuk menyederhanakan pelacakan biaya dan kontrol akses.
Jendela konteks token 1M
Claude Sonnet 5, Opus 4.6 dan yang lebih baru, serta Sonnet 4.6 mendukung jendela konteks token 1M di Amazon Bedrock. Sonnet 5 disajikan melalui endpoint Mantle dan selalu berjalan dengan jendela 1M, tanpa varian[1m] untuk dipilih. Untuk model lainnya, Claude Code secara otomatis mengaktifkan jendela konteks yang diperluas ketika Anda memilih varian model 1M.
Wizard pengaturan menawarkan opsi konteks 1M ketika mempin model. Untuk mengaktifkannya untuk model yang dipinnya secara manual, tambahkan [1m] ke ID model. Lihat Pin models for third-party deployments untuk detail.
Tingkat layanan
Tingkat layanan Amazon Bedrock memungkinkan Anda menukar biaya terhadap latensi. AturANTHROPIC_BEDROCK_SERVICE_TIER ke default, flex, atau priority:
X-Amzn-Bedrock-Service-Tier pada setiap permintaan. Ketersediaan tingkat bervariasi menurut model dan wilayah. Kapasitas yang dicadangkan menggunakan throughput yang disediakan ARN sebagai ID model alih-alih pengaturan ini.
AWS Guardrails
Amazon Bedrock Guardrails memungkinkan Anda menerapkan penyaringan konten untuk Claude Code. Buat Guardrail di konsol Amazon Bedrock, publikasikan versi, kemudian tambahkan header Guardrail ke file pengaturan Anda. Aktifkan inferensi Cross-Region pada Guardrail Anda jika Anda menggunakan profil inferensi lintas wilayah. Contoh konfigurasi:Gunakan endpoint Mantle
Mantle adalah endpoint Amazon Bedrock yang melayani model Claude melalui bentuk API Anthropic asli daripada Amazon Bedrock Invoke API. Ini menggunakan kredensial AWS yang sama, izin IAM, dan konfigurasiawsAuthRefresh yang dijelaskan sebelumnya di halaman ini.
Aktifkan Mantle
Dengan kredensial AWS sudah dikonfigurasi, aturCLAUDE_CODE_USE_MANTLE untuk merutekan permintaan ke endpoint Mantle:
AWS_REGION. Untuk mengganti URL untuk endpoint khusus atau gateway, atur ANTHROPIC_BEDROCK_MANTLE_BASE_URL.
Jalankan /status di dalam Claude Code untuk mengonfirmasi. Baris penyedia menunjukkan Amazon Bedrock (Mantle) ketika Mantle aktif.
Pilih model Mantle
Mantle menggunakan ID model dengan awalananthropic. dan tanpa akhiran versi, misalnya anthropic.claude-sonnet-5 atau anthropic.claude-haiku-4-5. Model yang tersedia untuk akun Anda tergantung pada apa yang telah diberikan organisasi Anda; ID model tambahan tercantum dalam materi onboarding Anda dari AWS. Hubungi tim akun AWS Anda untuk meminta akses ke model yang diizinkan.
Atur model dengan flag --model atau dengan /model di dalam Claude Code:
Jalankan Mantle bersama Invoke API
Model yang tersedia untuk Anda di Mantle mungkin tidak mencakup setiap model yang Anda gunakan hari ini. MenetapkanCLAUDE_CODE_USE_BEDROCK dan CLAUDE_CODE_USE_MANTLE memungkinkan Claude Code memanggil kedua endpoint dari sesi yang sama. ID model yang cocok dengan format Mantle dirutekan ke Mantle, dan semua ID model lainnya pergi ke Amazon Bedrock Invoke API.
/model, daftarkan ID-nya di availableModels di file pengaturan Anda. Pengaturan ini juga membatasi pemilih ke entri yang terdaftar. Mendaftarkan anthropic.claude-haiku-4-5 menghapus alias haiku biasa dari pemilih, jadi juga daftarkan awalan versi atau ID lengkap untuk versi yang ingin Anda tetap dapat dipilih. ID Mantle dan alias haiku diselesaikan ke keluarga model yang sama, jadi penggabungan hanya menyimpan entri yang lebih spesifik. Lihat Merge behavior:
anthropic. ditambahkan sebagai opsi pemilih khusus dan dirutekan ke Mantle. Ganti anthropic.claude-haiku-4-5 dengan ID model yang telah diberikan akun Anda. Lihat Restrict model selection untuk cara availableModels berinteraksi dengan pengaturan model lainnya.
Ketika kedua penyedia aktif, /status menunjukkan Amazon Bedrock + Amazon Bedrock (Mantle).
Rutekan Mantle melalui gateway
Jika organisasi Anda merutekan lalu lintas model melalui LLM gateway terpusat yang menyuntikkan kredensial AWS sisi server, nonaktifkan autentikasi sisi klien sehingga Claude Code mengirim permintaan tanpa tanda tangan SigV4 atau headerx-api-key:
Variabel lingkungan Mantle
Variabel ini khusus untuk endpoint Mantle. Lihat Environment variables untuk daftar lengkap.Pemecahan Masalah
Loop autentikasi dengan SSO dan proxy perusahaan
Jika tab browser muncul berulang kali saat menggunakan AWS SSO, hapus pengaturanawsAuthRefresh dari file pengaturan Anda. Ini dapat terjadi ketika VPN perusahaan atau proxy inspeksi TLS mengganggu alur browser SSO. Claude Code memperlakukan koneksi yang terputus sebagai kegagalan autentikasi, menjalankan kembali awsAuthRefresh, dan loop tanpa batas.
Jika lingkungan jaringan Anda mengganggu alur SSO berbasis browser otomatis, gunakan aws sso login secara manual sebelum memulai Claude Code alih-alih mengandalkan awsAuthRefresh.
Masalah wilayah
Jika Anda mengalami masalah wilayah:- Periksa ketersediaan model:
aws bedrock list-inference-profiles --region your-region - Beralih ke wilayah yang didukung:
export AWS_REGION=us-east-1 - Pertimbangkan menggunakan profil inferensi untuk akses lintas wilayah
- Tentukan model sebagai ID profil inferensi
Kesalahan streaming di belakang gateway atau proxy
Jika permintaan streaming gagal dengan kesalahan yang dimulai denganBedrock streaming response has content-type, gateway atau proxy antara Claude Code dan Amazon Bedrock mengubah respons streaming. Amazon Bedrock melakukan streaming respons dalam format event-stream biner dengan content-type application/vnd.amazon.eventstream, dan Claude Code menolak respons streaming yang berhasil yang melaporkan content-type berbeda alih-alih mendekode badan yang tidak dapat dibacanya. Kesalahan menyebutkan content-type yang diterima, biasanya text/event-stream dari integrasi Amazon API Gateway dan Lambda yang memancarkan kembali aliran sebagai server-sent events.
Sebelum v2.1.208, konfigurasi yang salah yang sama muncul sebagai API Error: Truncated event message received setelah seluruh respons telah di-buffer.
Untuk memperbaikinya, konfigurasikan gateway untuk melewatkan badan respons InvokeModelWithResponseStream dan header Content-Type-nya tanpa diubah. Jika gateway hanya menulis ulang header dan melewatkan badan biner dengan utuh, atur CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 untuk melewati pemeriksaan sampai gateway diperbaiki. Dengan pemeriksaan dimatikan, badan respons yang diubah gagal dengan Truncated event message received lagi.
Penghitungan token nol dalam /context
Perintah/context menghitung token untuk setiap grup alat dengan mengirimkan skema alat ke API count-tokens Amazon Bedrock. Pada versi Claude Code sebelum v2.1.196, Amazon Bedrock menolak permintaan itu karena skema membawa bidang yang tidak diterima API count-tokens-nya, jadi setiap grup alat menunjukkan 0 token. Baris lain dalam rincian, seperti pesan dan file memori, tidak terpengaruh.
Perbarui ke v2.1.196 atau lebih baru.
Kesalahan endpoint Mantle
Jika/status tidak menunjukkan Amazon Bedrock (Mantle) setelah Anda menetapkan CLAUDE_CODE_USE_MANTLE, variabel tidak mencapai proses. Konfirmasi bahwa variabel diekspor di shell tempat Anda meluncurkan claude, atau atur di blok env dari file pengaturan Anda.
A 403 dari endpoint Mantle dengan kredensial yang valid berarti akun AWS Anda belum diberikan akses ke model yang Anda minta. Hubungi tim akun AWS Anda untuk meminta akses.
A 400 yang menyebutkan ID model berarti model itu tidak dilayani di Mantle. Mantle memiliki lineup model sendiri yang terpisah dari katalog Bedrock standar, jadi ID profil inferensi seperti us.anthropic.claude-sonnet-4-6 tidak akan berfungsi. Gunakan ID format Mantle, atau aktifkan kedua endpoint sehingga Claude Code merutekan setiap permintaan ke endpoint tempat model tersedia.