Claude Code di Amazon Bedrock

Pelajari tentang mengonfigurasi Claude Code melalui Amazon Bedrock, termasuk pengaturan, konfigurasi IAM, dan pemecahan masalah.

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

View plans Contact sales

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

Untuk masuk dengan kredensial Amazon Bedrock Anda sendiri, ikuti Masuk dengan Amazon Bedrock di bawah ini. Untuk menerapkan Claude Code di seluruh tim, gunakan langkah pengaturan manual dan pin versi model Anda sebelum melakukan peluncuran.

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 di sisi AWS satu kali per akun; wizard menangani sisi Claude Code.

1. Aktifkan model Anthropic di akun AWS Anda

Di konsol Amazon Bedrock, buka Model catalog, 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 oleh role Anda.

2. Mulai Claude Code dan pilih Amazon Bedrock

Jalankan claude. Pada prompt login, pilih 3rd-party platform, lalu Amazon Bedrock. Jika Anda sudah masuk dan melihat prompt obrolan, jalankan /setup-bedrock untuk membuka wizard. Selama CLAUDE_CODE_USE_BEDROCK=1 belum diatur, Claude Code menyembunyikan perintah tersebut dari menu perintah; ketikkan perintah tersebut secara lengkap.

3. Ikuti prompt wizard

Pilih cara Anda melakukan autentikasi ke AWS: profil AWS yang terdeteksi dari direktori ~/.aws Anda, kunci API Amazon Bedrock, access key dan secret, atau kredensial yang sudah ada di lingkungan Anda. Wizard akan menanyakan region Anda, memverifikasi model Claude mana yang dapat dipanggil oleh akun Anda, dan memungkinkan Anda menyematkan (pin) model tersebut. Wizard menyimpan hasilnya ke blok env di file pengaturan pengguna Anda, sehingga Anda tidak perlu mengekspor environment variable sendiri.

Setelah Anda masuk, jalankan /setup-bedrock kapan saja untuk membuka kembali wizard dan mengubah kredensial, region, atau model yang disematkan. Langkah penyematan model dimulai dari model yang saat ini Anda sematkan. Wizard menulis ke ~/.claude/settings.json, atau ke $CLAUDE_CONFIG_DIR/settings.json ketika CLAUDE_CONFIG_DIR diatur.

Menyiapkan secara manual

Untuk mengonfigurasi Amazon Bedrock melalui environment variable alih-alih wizard, misalnya di CI atau dalam peluncuran enterprise yang menggunakan skrip, ikuti langkah-langkah di bawah ini.

Kirimkan detail kasus penggunaan

Sebelum Anda memanggil model Anthropic untuk pertama kalinya, kirimkan detail kasus penggunaan. Anda melakukan ini satu kali per akun AWS.

1. Pastikan Anda memiliki izin IAM yang tepat seperti dijelaskan di bawah ini
2. Buka konsol Amazon Bedrock
3. Pilih model Anthropic dari Model catalog
4. Lengkapi formulir kasus penggunaan. Akses diberikan segera setelah pengiriman.

Jika Anda menggunakan AWS Organizations, Anda dapat mengirimkan formulir satu kali dari akun manajemen menggunakan API PutUseCaseForModelAccess. Panggilan ini memerlukan izin IAM bedrock:PutUseCaseForModelAccess. Persetujuan diperluas ke akun turunan secara otomatis.

Konfigurasikan kredensial AWS

Claude Code menggunakan rantai kredensial default AWS SDK. Jika mesin sudah menyediakan kredensial ke rantai tersebut, seperti instance profile Amazon EC2 atau kredensial tugas Amazon ECS, lanjutkan ke langkah 3.

AWS memperingatkan agar tidak menggunakan access key pengguna IAM saat Anda mengembangkan perangkat lunak yang dibuat khusus atau bekerja dengan data nyata. Siapkan kredensial Anda dengan salah satu metode berikut:

• aws configure: simpan access key pengguna IAM ke profil di direktori ~/.aws Anda
• Environment variable access key: atur access key, atau kredensial sementara dengan session token, hanya di shell saat ini
• Profil SSO: masuk melalui IAM Identity Center di browser Anda dan dapatkan kredensial sementara. Gunakan metode ini jika Anda mengakses akun AWS Anda melalui IAM Identity Center.
• Kredensial AWS Management Console: masuk melalui browser Anda dengan kredensial AWS Management Console Anda dan dapatkan kredensial sementara. AWS merekomendasikan metode ini jika Anda mengakses akun AWS Anda sebagai pengguna root, sebagai pengguna IAM, atau melalui federasi dengan IAM.
• Kunci API Amazon Bedrock: lakukan autentikasi dengan bearer token yang hanya berfungsi untuk Amazon Bedrock, alih-alih kredensial AWS

Menggunakan aws configure

Jalankan aws configure dan masukkan access key ID, secret access key, dan region default Anda saat diminta:

aws configure

AWS CLI menyimpan kunci tersebut ke profil default di ~/.aws/credentials, tempat rantai kredensial membacanya.

Mengekspor access key

Ekspor access key Anda sebagai environment variable. AWS_SESSION_TOKEN hanya diperlukan dengan kredensial sementara, jadi hilangkan baris tersebut jika access key Anda milik pengguna IAM:

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

Menggunakan profil SSO

Buat profil dengan aws configure sso jika Anda belum memilikinya. Kemudian masuk ke IAM Identity Center dan atur AWS_PROFILE agar rantai kredensial menggunakan profil tersebut. Ganti your-profile-name dengan nama profil AWS Anda sebelum menjalankan perintah-perintah ini.

aws sso login --profile=your-profile-name

export AWS_PROFILE=your-profile-name

Claude Code meminta kredensial peran dari region IAM Identity Center yang disebutkan oleh sso_region profil, yang tidak harus sama dengan region tempat Anda menjalankan Amazon Bedrock.

Menggunakan kredensial AWS Management Console

Perintah aws login memerlukan AWS CLI 2.32.0 atau yang lebih baru. Untuk kebijakan IAM yang dibutuhkan identitas Anda, lihat instruksi AWS untuk aws login.

Jalankan perintah berikut untuk masuk melalui browser Anda dengan kredensial AWS Management Console Anda:

aws login

Sesi berlaku hingga 12 jam, setelah itu Anda menjalankan aws login lagi.

Menggunakan kunci API Amazon Bedrock

Kunci API Amazon Bedrock adalah bearer token yang mengautentikasi permintaan Anda sebagai pengganti kredensial AWS. AWS menerbitkan dua jenis kunci:

• Kunci jangka pendek: berlaku hingga 12 jam. AWS lebih memilihnya daripada kunci jangka panjang untuk lingkungan produksi.
• Kunci jangka panjang: berlaku hingga tanggal kedaluwarsa yang Anda tetapkan. AWS merekomendasikannya hanya untuk eksplorasi.

Ekspor kunci tersebut sebagai AWS_BEARER_TOKEN_BEDROCK:

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Ketika AWS_BEARER_TOKEN_BEDROCK diatur, Claude Code melakukan autentikasi dengan kunci tersebut dan tidak me-resolve rantai kredensial, bahkan jika kredensial AWS lain tersedia. Pelajari lebih lanjut tentang kunci API Amazon Bedrock.

Caching kredensial dan timeout resolusi

Claude Code me-resolve rantai penyedia kredensial default AWS satu kali dan menyimpan kredensial hasil resolve di memori. Claude Code menggunakannya kembali hingga lima menit sebelum kedaluwarsa, atau selama satu jam jika kredensial tersebut tidak memiliki waktu kedaluwarsa, sehingga profil berbasis SSO meminta kredensial dari IAM Identity Center sekitar satu kali per masa berlaku kredensial. Kesalahan kredensial dari API akan menghapus cache, dan retry akan me-resolve kredensial baru.

Cache mencakup setiap metode kredensial yang tercantum di awal langkah ini kecuali kunci API Amazon Bedrock, yang tidak menggunakan rantai penyedia. Untuk me-resolve rantai pada setiap permintaan, atur CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1.

Proses resolve yang mengisi cache mengalami timeout setelah 60 detik. Jika suatu langkah dalam rantai macet, misalnya helper credential_process yang menunggu input yang tidak dapat diterimanya, permintaan gagal dengan AWS default-chain credential resolve timed out. Jika rantai Anda menjalankan proses masuk interaktif yang memang membutuhkan waktu lebih lama, seperti SSO berbasis browser dengan MFA melalui wrapper seperti aws-vault, naikkan batas waktunya dalam milidetik dengan CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS. Dengan CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1 diatur, setiap permintaan API me-resolve rantai tanpa batas ini.

Kecuali saat Anda melakukan autentikasi dengan kunci API Amazon Bedrock, wizard penyiapan menerapkan batas yang sama pada setiap panggilan AWS yang dilakukannya saat memverifikasi kredensial Anda, dan pada pencarian kredensial sebelum setiap pemeriksaan model. Selama verifikasi kredensial, pemeriksaan yang melampaui batas tersebut gagal dengan Timed out after 60s waiting for AWS.

Konfigurasi kredensial lanjutan

Claude Code mendukung penyegaran kredensial otomatis untuk AWS SSO dan penyedia identitas perusahaan. Tambahkan pengaturan berikut ke file pengaturan Claude Code Anda (lihat Pengaturan untuk lokasi file).

Kedua pengaturan ini memiliki kondisi pemicu yang berbeda:

• awsAuthRefresh: hanya berjalan ketika Claude Code mendeteksi bahwa kredensial AWS Anda telah kedaluwarsa, baik secara lokal berdasarkan timestamp-nya atau ketika API mengembalikan kesalahan kredensial, lalu mencoba ulang permintaan dengan kredensial yang telah disegarkan.
• awsCredentialExport: berjalan saat sesi dimulai dan pada setiap pemuatan ulang kredensial, bahkan ketika kredensial dalam rantai penyedia kredensial default AWS Anda masih valid. Gunakan ini ketika akun Amazon Bedrock Anda memerlukan kredensial lintas akun yang berbeda dari kredensial yang akan di-resolve oleh rantai penyedia default.

Sebelum menjalankan perintah awsAuthRefresh, Claude Code melakukan panggilan STS GetCallerIdentity untuk memastikan bahwa kredensial Anda benar-benar kedaluwarsa, dan melewati perintah tersebut jika kredensial masih berfungsi. Claude Code mengirimkan pemeriksaan ini melalui konfigurasi proxy Anda, dengan mematuhi HTTPS_PROXY dan NO_PROXY. Sebelum v2.1.239, Claude Code mengirimkan pemeriksaan ini secara langsung dan macet saat startup pada jaringan yang hanya mengizinkan egress melalui proxy.

Contoh konfigurasi

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

Penjelasan pengaturan konfigurasi

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 berfungsi dengan baik untuk alur SSO berbasis browser di mana CLI menampilkan URL atau kode dan Anda menyelesaikan autentikasi di browser.

awsCredentialExport: Gunakan ini hanya jika Anda tidak dapat memodifikasi .aws dan harus mengembalikan kredensial secara langsung. Output ditangkap secara diam-diam dan tidak ditampilkan kepada pengguna. Perintah harus menghasilkan output JSON dalam format ini:

{
  "Credentials": {
    "AccessKeyId": "value",
    "SecretAccessKey": "value",
    "SessionToken": "value",
    "Expiration": "2026-01-01T00:00:00Z"
  }
}

Output datar dari aws configure export-credentials --format process juga diterima, dengan kunci yang sama di tingkat atas alih-alih bersarang di bawah Credentials.

Expiration bersifat opsional. Ketika perintah mengembalikan Expiration ISO 8601 yang valid, Claude Code menyimpan kredensial di cache hingga lima menit sebelum waktu tersebut. Tanpanya, kredensial disimpan di cache selama satu jam.

Ketika Anda mengonfigurasi awsCredentialExport tanpa awsAuthRefresh, Claude Code menggunakan kredensial yang diekspor secara langsung dan tidak me-resolve ulang rantai penyedia kredensial default AWS saat startup.

Konfigurasikan Claude Code

Atur environment variable berikut untuk mengaktifkan Amazon Bedrock:

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # optional if your AWS profile already sets a region

# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).
# On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL
# or the deprecated ANTHROPIC_SMALL_FAST_MODEL set.
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways
# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

Saat mengaktifkan Amazon Bedrock untuk Claude Code, perhatikan hal-hal berikut:

• Anda hanya perlu mengatur AWS_REGION untuk menimpa region profil AWS Anda atau ketika profil Anda tidak memiliki region. Claude Code me-resolve region dengan urutan berikut:

  • AWS_REGION
  • AWS_DEFAULT_REGION
  • region yang diatur pada profil AWS aktif Anda, dibaca dari file shared credentials AWS terlebih dahulu lalu dari file shared config, sesuai dengan prioritas AWS SDK
  • us-east-1

  Jika nilai dari salah satu sumber ini tidak berbentuk seperti nama region, Claude Code memperlakukannya sebagai tidak diatur dan melanjutkan ke urutan berikutnya. Misalnya, Claude Code memperlakukan nilai yang mengandung garis miring, titik, atau spasi sebagai tidak diatur.

  Profil aktif adalah AWS_PROFILE jika diatur, jika tidak maka default. Atur AWS_SHARED_CREDENTIALS_FILE atau AWS_CONFIG_FILE untuk menunjuk ke path file non-default.

  Jalankan /status untuk melihat region hasil resolve. Ketika region berasal dari file konfigurasi AWS Anda atau fallback default, Claude Code juga mencatat sumbernya di output /status.

• Saat menggunakan Amazon Bedrock, perintah /logout tidak tersedia karena autentikasi ditangani melalui kredensial AWS.

• Tool WebSearch tidak tersedia di Amazon Bedrock. Lihat Perilaku tool WebSearch.

• Anda dapat menggunakan file pengaturan untuk environment variable seperti AWS_PROFILE yang tidak ingin Anda bocorkan ke proses lain. Lihat Pengaturan untuk informasi lebih lanjut.

Sematkan versi model

[!WARNING]

Sematkan versi model tertentu saat melakukan deployment ke banyak pengguna. Tanpa penyematan, alias model seperti sonnet dan opus di-resolve ke default bawaan Claude Code untuk Amazon Bedrock, yang bisa tertinggal dari rilis terbaru dan mungkin belum tersedia di akun Anda. Claude Code melakukan fallback ke model yang lebih lama atau tingkat lebih rendah saat startup ketika default tidak tersedia, tetapi penyematan memungkinkan Anda mengontrol kapan pengguna Anda beralih ke model baru.

Atur environment variable berikut ke ID model Amazon Bedrock tertentu.

Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Amazon Bedrock di-resolve ke Opus 5.5, dan tanpa ANTHROPIC_DEFAULT_SONNET_MODEL, alias sonnet di-resolve ke Sonnet 4.5. Contoh ini menyematkan setiap alias ke versi tertentu:

export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

ID ini menggunakan prefiks inference profile lintas region us.. Jika Anda menggunakan prefiks region yang berbeda atau application inference profile, sesuaikan. Di region AWS GovCloud, gunakan prefiks us-gov..

Untuk mempertahankan model default bawaan dan hanya mengubah prefiks pilihannya, atur ANTHROPIC_BEDROCK_REGION_PREFIX alih-alih melakukan penyematan. Perbedaannya terlihat pada hasil resolve alias opus:

Untuk ID model saat ini dan lama, lihat Ikhtisar model. Untuk daftar lengkap environment variable penyematan, lihat Konfigurasi model.

Claude Code menggunakan model default berikut ketika tidak ada variabel penyematan yang diatur:

Sebelum v2.1.280, model utama di Amazon Bedrock secara default adalah Opus 5 dan alias opus di-resolve ke Opus 5 sejak v2.1.219.

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 region. Dua pilihan mengubah model mana yang menjalankannya:

• Ketika Anda memilih model utama dengan --model, ANTHROPIC_MODEL, atau pengaturan model, tugas latar belakang menggunakan model tersebut. Ketika Claude Code memulai sesi pada model yang Anda atur dengan ANTHROPIC_DEFAULT_MODEL, tugas latar belakang juga menggunakan model tersebut. Mengatur ANTHROPIC_DEFAULT_OPUS_MODEL tanpa ANTHROPIC_DEFAULT_SONNET_MODEL juga 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_MODEL ke ID model yang tersedia di akun Anda.

[!WARNING]

Model Opus memiliki harga per token yang lebih tinggi daripada model Sonnet, jadi jika Anda tidak menyematkan model utama, Anda ditagih dengan tarif Opus. Untuk menggunakan Sonnet 4.5 sebagai model utama, atur ANTHROPIC_MODEL ke ID model lengkapnya. Deployment yang mengarahkan default dengan ANTHROPIC_DEFAULT_SONNET_MODEL dan tidak mengatur ANTHROPIC_DEFAULT_OPUS_MODEL tetap menggunakan model Sonnet yang diarahkannya sebagai default.

Untuk menyesuaikan model lebih lanjut, gunakan salah satu metode berikut:

# Using inference profile ID
export ANTHROPIC_MODEL='us.anthropic.claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

# Using application inference profile ARN
export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

# Optional: Disable prompt caching if needed
# export DISABLE_PROMPT_CACHING=1

# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default
# export ENABLE_PROMPT_CACHING_1H=1

TTL cache 1 jam ditagih dengan tarif lebih tinggi daripada default 5 menit. Lihat masa berlaku cache. Untuk mengatur TTL yang berbeda untuk percakapan utama Anda dan untuk permintaan yang dibuat Claude Code di luarnya, pilih TTL sendiri.

[!NOTE]

Prompt caching mungkin tidak tersedia di semua region Amazon Bedrock. Jika jumlah token cache tetap nol, periksa model, region, dan batas yang didukung di dokumentasi Amazon Bedrock.

Memetakan setiap versi model ke inference profile

Environment variable ANTHROPIC_DEFAULT_*_MODEL mengonfigurasi satu inference profile per keluarga model. Jika organisasi Anda perlu menampilkan beberapa versi dari keluarga yang sama di pemilih /model, masing-masing dirutekan ke ARN application inference profile-nya sendiri, gunakan pengaturan modelOverrides di file pengaturan Anda.

Contoh ini memetakan empat versi Opus ke ARN yang berbeda sehingga pengguna dapat beralih di antara versi-versi tersebut tanpa melewati inference profile organisasi Anda:

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod",
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",
    "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"
  }
}

Ketika pengguna memilih salah satu versi ini di /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 akan melakukan fallback ke ID model Amazon Bedrock bawaan atau inference profile yang cocok yang ditemukan saat startup. Sebelum v2.1.200, nilai --model dan ANTHROPIC_MODEL diteruskan ke Amazon Bedrock apa adanya tanpa melalui peta override. Lihat Menimpa ID model per versi untuk detail tentang bagaimana override berinteraksi dengan availableModels dan pengaturan model lainnya.

Pemeriksaan model startup

Ketika Claude Code dimulai dengan Amazon Bedrock yang dikonfigurasi, Claude Code memverifikasi bahwa model yang dimaksudkan untuk digunakan dapat diakses di akun Anda.

Anda mungkin telah menyematkan versi model yang lebih lama dari default Claude Code saat ini. Jika akun Anda dapat memanggil versi yang lebih baru, Claude Code akan meminta Anda untuk memperbarui pin. Menerima akan menulis ID model baru ke file pengaturan pengguna Anda dan memulai ulang Claude Code. Menolak akan diingat hingga perubahan versi default berikutnya.

Claude Code tidak memeriksa atau meminta pembaruan untuk pin berikut:

• Pin dalam blok env dari pengaturan terkelola
• Pin yang menunjuk ke profil inferensi aplikasi ARN, karena dikelola oleh administrator Anda

Jika dialog pembaruan masih muncul untuk pin dalam pengaturan terkelola, perbarui Claude Code ke v2.1.314 atau yang lebih baru. Sebelum v2.1.314, pin terkelola tetap berlaku setelah Anda menerima, sehingga dialog tersebut muncul kembali pada startup berikutnya.

Jika Anda belum menyematkan model dan default saat ini tidak tersedia di akun Anda, Claude Code akan melakukan fallback 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, melakukan fallback ke model Sonnet default. Fallback tidak disimpan. Aktifkan model yang lebih baru di akun Amazon Bedrock Anda atau sematkan versi untuk membuat pilihan permanen.

Memulai sesi pada model tertentu

Ketika Anda memulai sesi pada versi Sonnet atau Opus tertentu, misalnya dengan --model, ANTHROPIC_MODEL, atau pengaturan model, versi tersebut bertindak sebagai default yang disematkan sesi untuk alias sonnet atau opus yang cocok. Claude Code melewati pemeriksaan ketersediaan untuk default bawaan yang diganti model Anda dan dimulai pada model yang Anda konfigurasi, tanpa pemberitahuan fallback.

Hal berikut tidak bertindak sebagai pin ketika Anda memulai sesi dengannya:

• Alias model seperti opus
• ID model yang tidak dikenali Claude Code, seperti profil inferensi aplikasi ARN

Penolakan model yang diingat

Ketika pemeriksaan model startup menemukan model yang tidak dapat dipanggil oleh akun Anda, Claude Code dapat mengingat penolakan tersebut di mesin ini hingga satu hari. Setelah sepuluh menit berlalu sejak pemeriksaan terakhir, Claude Code memeriksa kembali penolakan yang diingat untuk model default saat ini saat peluncuran. Default yang diaktifkan kembali oleh administrator Anda kemudian akan tersedia lagi. Untuk mematikan memori ini, atur CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1.

Ketika organisasi Anda memberlakukan allowlist model

Jika Anda mengatur enforceAvailableModels dalam pengaturan terkelola, pemeriksaan model startup hanya menggunakan model yang diizinkan oleh daftar availableModels Anda. Hal ini berlaku pada Amazon Bedrock Invoke API dan memerlukan Claude Code v2.1.287 atau yang lebih baru. Daftar tanpa enforceAvailableModels tidak membatasi pemeriksaan ini.

Pemeriksaan ini membandingkan setiap entri dengan ID profil inferensi yang akan dikirimnya, termasuk prefiks region-nya, jadi tulis daftar tersebut menggunakan ID tersebut. Contoh ini mengizinkan Opus 4.8 dan Sonnet 4.5 untuk deployment yang modelnya di-resolve ke profil us.:

{
  "availableModels": ["us.anthropic.claude-opus-4-8", "us.anthropic.claude-sonnet-4-5-20250929-v1:0"],
  "enforceAvailableModels": true
}

Untuk alias, prefiks versi, dan entri modelOverrides, lihat Menyematkan model untuk deployment pihak ketiga.

Ketika model dinonaktifkan di tengah sesi

Jika akun Anda kehilangan akses ke model yang sesi Anda jalankan, misalnya karena administrator menonaktifkannya di akun Amazon Bedrock Anda, Claude Code beralih sesi ke model lain alih-alih gagal pada setiap permintaan, dan menampilkan Switched to <fallback> because <model> is not available. Claude Code mencoba model yang sama seperti fallback startup: versi sebelumnya dari tier yang sama terlebih dahulu dan, untuk sesi Opus tanpa versi Opus yang tersedia, model Sonnet default.

Pengalihan hanya berlaku untuk tier yang belum Anda sematkan, kondisi yang sama seperti fallback startup. Sesi pada versi spesifik yang Anda pilih, atau pada profil inferensi aplikasi ARN, mempertahankan modelnya dan, tanpa rantai fallback model, permintaan gagal sebagai gantinya. Dalam auto mode, Claude Code hanya beralih ke model yang didukung auto mode di Amazon Bedrock. Jika tidak ada model tersebut yang tersedia, permintaan gagal dengan AWS authentication failed dan petunjuk untuk mengaktifkan model.

Rantai fallback model yang Anda konfigurasi menggantikan pengalihan tier: pada penolakan ini Claude Code beralih ke fallback yang Anda konfigurasi sebagai gantinya. Untuk membuat permintaan yang ditolak gagal daripada beralih, atur CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1. Rantai fallback yang Anda konfigurasi masih beralih pada penolakan ini; hapus rantai juga jika Anda ingin setiap permintaan yang ditolak gagal.

Prefiks profil inferensi lintas wilayah

Pada Amazon Bedrock Invoke API, Claude Code menyelesaikan model default bawaan ke ID profil inferensi lintas wilayah; untuk merutekan versi model melalui profil inferensi Anda sendiri, lihat Petakan setiap versi model ke profil inferensi. Tabel ini menunjukkan prefiks yang disukai Claude Code untuk setiap wilayah AWS yang diselesaikan:

Atur ANTHROPIC_BEDROCK_REGION_PREFIX untuk memilih prefiks yang dicoba Claude Code terlebih dahulu. Nilai yang valid adalah us, eu, apac, jp, au, dan global. Misalnya, atur ke global ketika akun Anda memiliki profil global. diaktifkan tetapi Claude Code akan menurunkan satu yang spesifik geografis dari wilayah AWS Anda.

Contoh ini merutekan model default melalui profil global.:

export ANTHROPIC_BEDROCK_REGION_PREFIX=global
# Di wilayah us-*, model utama sekarang diselesaikan ke
# global.anthropic.claude-opus-5-5 bukan us.anthropic.claude-opus-5-5

Prefiks yang disukai adalah preferensi, bukan jaminan, baik itu berasal dari wilayah Anda atau dari variabel. Bagaimana Claude Code menerapkannya tergantung pada apakah Claude Code dapat memeriksa ketersediaan profil di akun Anda:

• Ketika Claude Code dapat mencantumkan profil inferensi di akun Anda, Claude Code menyelesaikan setiap model dalam urutan ini:
  1. Profil dengan prefiks pilihan Anda.
  2. Profil yang cocok, untuk model yang tidak memiliki profil dengan prefiks tersebut.
  3. ID model bawaan dengan prefiks pilihan Anda, untuk model yang tidak memiliki profil yang cocok sama sekali. Claude Code menerapkan ID ini tanpa memeriksa ketersediaan pada langkah ini; pemeriksaan model startup masih mencakup model default sesi.
• Ketika penemuan profil tidak tersedia, Claude Code menerapkan prefiks tanpa memeriksa ketersediaan. Jika akun Anda tidak memiliki profil inferensi dengan prefiks tersebut diaktifkan, permintaan gagal dengan kesalahan 400.

Claude Code tidak menulis ulang ID profil inferensi Amazon Bedrock atau ARN yang Anda konfigurasi sendiri, atau nilai modelOverrides; ID model format Anthropic diselesaikan melalui pemetaan yang sama seperti pemilih /model. Claude Code juga mengabaikan variabel dalam dua kasus:

• Di wilayah AWS GovCloud, Claude Code selalu menggunakan us-gov., satu-satunya prefiks yang merutekan dalam partisi GovCloud.
• Ketika Anda menetapkan nilai yang bukan salah satu dari nilai yang valid, Claude Code kembali ke prefiks pilihan yang diturunkan dari wilayah.

Konfigurasi IAM

Buat kebijakan IAM dengan izin yang diperlukan untuk Claude Code:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowModelAndInferenceProfileAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream",
        "bedrock:ListInferenceProfiles",
        "bedrock:GetInferenceProfile"
      ],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*:*:application-inference-profile/*",
        "arn:aws:bedrock:*:*:foundation-model/*"
      ]
    },
    {
      "Sid": "AllowMarketplaceSubscription",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ViewSubscriptions",
        "aws-marketplace:Subscribe"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:CalledViaLast": "bedrock.amazonaws.com"
        }
      }
    }
  ]
}

Untuk izin yang lebih ketat, Anda dapat membatasi Resource ke ARN profil inferensi spesifik.

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.

[!NOTE]

Buat akun AWS khusus untuk Claude Code untuk menyederhanakan pelacakan biaya dan kontrol akses.

Jendela konteks token 1M

Model Fable, Sonnet 5 dan yang lebih baru, serta Opus 4.7 dan yang lebih baru berjalan dengan context window token 1M secara default di Amazon Bedrock, baik di API Invoke maupun endpoint Mantle, tanpa memerlukan sufiks [1m]. ARN profil inferensi aplikasi mendapatkan jendela 1M ketika entri modelOverrides memetakan modelnya ke profil tersebut. Untuk tetap menggunakan jendela 200K, atur CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Opus 4.6 dan Sonnet 4.6 di API Invoke mencapai jendela 1M ketika Anda memilih varian [1m] mereka. Wizard pengaturan menawarkan opsi konteks 1M ketika mempin model. Sebagai gantinya, untuk mengaktifkannya pada model yang dipin secara manual, tambahkan [1m] ke ID model. Lihat Pin models for third-party deployments untuk detail, termasuk cara menggunakan jendela 1M tanpa mengubah pin.

Sebelum v2.1.287, model Fable serta Opus 4.7 dan yang lebih baru berjalan dengan jendela 200K secara default di API Invoke dan mencapai jendela 1M di sana melalui sufiks [1m].

Tingkat layanan

Tingkat layanan Amazon Bedrock memungkinkan Anda menukar biaya terhadap latensi. Atur ANTHROPIC_BEDROCK_SERVICE_TIER ke default, flex, atau priority:

export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

Claude Code mengirimkan ini sebagai header X-Amzn-Bedrock-Service-Tier pada setiap permintaan Invoke API dari sesi yang memiliki variabel tersebut, kecuali pemeriksaan akses model-nya. Mengaturnya tidak berpengaruh pada permintaan ke endpoint Mantle atau melalui gateway aplikasi Claude. Ketersediaan tingkat bervariasi menurut model dan wilayah. Kapasitas yang dicadangkan menggunakan throughput yang disediakan ARN sebagai ID model alih-alih pengaturan ini.

Untuk mencakup sesi latar belakang yang Anda mulai dari terminal, atur ANTHROPIC_BEDROCK_SERVICE_TIER di blok env pada pengaturan Anda. Sesi tersebut mendapatkan nilai yang Anda ekspor hanya jika shell yang memulai supervisor telah mengekspornya.

AWS Guardrails

Amazon Bedrock Guardrails memungkinkan Anda menerapkan penyaringan konten untuk Claude Code. Buat Guardrail di konsol Amazon Bedrock dan publikasikan versi. Aktifkan inferensi Cross-Region pada Guardrail Anda jika Anda menggunakan profil inferensi lintas wilayah.

Untuk menerapkan Guardrail melalui gateway aplikasi Claude, ikuti Menerapkan guardrail Amazon Bedrock. Tanpa gateway aplikasi Claude, tambahkan header Guardrail ke file pengaturan Anda.

Contoh konfigurasi file pengaturan:

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"
  }
}

Ketika guardrail memblokir respons di tengah jalan, teks yang telah di-streaming sejauh ini tetap ada dan balasan diakhiri dengan pesan yang dikonfigurasi pada guardrail untuk respons yang diblokir.

Menggunakan endpoint Mantle

Mantle adalah endpoint Amazon Bedrock yang menyajikan model Claude melalui bentuk API Anthropic native, bukan melalui Amazon Bedrock Invoke API. Endpoint ini menggunakan kredensial AWS dan konfigurasi awsAuthRefresh yang sama.

Mantle memiliki tindakan IAM tersendiri dengan awalan bedrock-mantle:, sehingga tindakan bedrock: dalam konfigurasi IAM tidak mencakupnya. Berikan identitas IAM Anda bedrock-mantle:CreateInference untuk inferensi dan bedrock-mantle:CountTokens untuk penghitungan token. Lihat Making inference requests dan Counting tokens dalam dokumentasi AWS, serta referensi otorisasi layanan untuk setiap tindakan Mantle.

Mengaktifkan Mantle

Dengan kredensial AWS yang sudah dikonfigurasi, atur CLAUDE_CODE_USE_MANTLE dan region AWS Anda:

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION=us-east-1

Claude Code menyusun URL endpoint dari region AWS, yang di-resolve dengan urutan prioritas yang sama seperti Amazon Bedrock di atas. Untuk menimpa URL untuk endpoint atau gateway kustom, atur ANTHROPIC_BEDROCK_MANTLE_BASE_URL.

Jalankan /status di dalam Claude Code untuk mengonfirmasi. Baris penyedia menampilkan Amazon Bedrock (Mantle) saat Mantle aktif.

Memilih model Mantle

Mantle menggunakan ID model dengan awalan anthropic. dan tanpa akhiran versi, misalnya anthropic.claude-sonnet-5 atau anthropic.claude-haiku-4-5. Model yang tersedia untuk akun Anda bergantung pada apa yang telah diberikan kepada organisasi Anda; ID model tambahan tercantum dalam materi onboarding Anda dari AWS. Hubungi tim akun AWS Anda untuk meminta akses ke model yang masuk dalam allowlist.

Atur model dengan flag --model atau dengan /model di dalam Claude Code:

claude --model anthropic.claude-haiku-4-5

Menjalankan Mantle bersama Invoke API

Model yang tersedia untuk Anda di Mantle mungkin tidak mencakup setiap model yang Anda gunakan saat ini. Mengatur CLAUDE_CODE_USE_BEDROCK dan CLAUDE_CODE_USE_MANTLE sekaligus 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 dikirim ke Amazon Bedrock Invoke API.

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

Untuk menampilkan model Mantle di pemilih /model, cantumkan ID-nya di availableModels dalam file pengaturan Anda. Pengaturan ini juga membatasi pemilih hanya pada entri yang dicantumkan. Mencantumkan anthropic.claude-haiku-4-5 akan menghapus alias haiku polos dari pemilih, jadi cantumkan juga awalan versi atau ID lengkap untuk versi yang ingin tetap dapat dipilih. ID Mantle dan alias haiku di-resolve ke keluarga model yang sama, sehingga penggabungan hanya mempertahankan entri yang lebih spesifik. Lihat Perilaku penggabungan:

{
  "availableModels": ["opus", "sonnet", "claude-haiku-4-5", "anthropic.claude-haiku-4-5"]
}

Entri dengan awalan anthropic. ditambahkan sebagai opsi pemilih kustom, dan entri yang cocok dengan format Mantle dirutekan ke Mantle. Ganti anthropic.claude-haiku-4-5 dengan ID model yang telah diberikan kepada akun Anda. Lihat Membatasi pemilihan model untuk mengetahui bagaimana availableModels berinteraksi dengan pengaturan model lainnya.

Saat kedua penyedia aktif, /status menampilkan Amazon Bedrock + Amazon Bedrock (Mantle).

Merutekan Mantle melalui gateway

Jika organisasi Anda merutekan lalu lintas model melalui LLM gateway terpusat yang menyisipkan kredensial AWS di sisi server, nonaktifkan autentikasi sisi klien agar Claude Code mengirim permintaan tanpa tanda tangan SigV4 atau header x-api-key:

export CLAUDE_CODE_USE_MANTLE=1
export CLAUDE_CODE_SKIP_MANTLE_AUTH=1
export ANTHROPIC_BEDROCK_MANTLE_BASE_URL=https://your-gateway.example.com

Environment variable Mantle

Variabel-variabel ini khusus untuk endpoint Mantle. Lihat Environment variable untuk daftar lengkapnya.

Pemecahan Masalah

Loop autentikasi dengan SSO dan proxy perusahaan

Jika tab masuk browser terus terbuka saat Anda menggunakan AWS SSO, hapus pengaturan awsAuthRefresh dari file pengaturan Anda.

Loop ini dapat terjadi ketika VPN perusahaan atau proxy inspeksi TLS mengganggu alur browser SSO. Claude Code memperlakukan koneksi yang terputus sebagai kegagalan autentikasi. Ketika permintaan berikutnya mendapati kredensial masih kedaluwarsa, Claude Code menjalankan kembali awsAuthRefresh, yang membuka tab lain.

Jika lingkungan jaringan Anda mengganggu alur SSO berbasis browser otomatis, gunakan aws sso login secara manual sebelum memulai Claude Code alih-alih mengandalkan awsAuthRefresh.

Kesalahan sertifikat di belakang proxy yang melakukan inspeksi TLS

Claude Code menerapkan konfigurasi penyimpanan sertifikat CA Anda ke permintaannya ke AWS, termasuk:

• Penemuan model
• Penghitungan token
• Panggilan kredensial peran STS dan SSO yang menyelesaikan kredensial AWS Anda
• Verifikasi kredensial dan pemeriksaan model wizard penyiapan

Untuk permintaan ini, sertifikat akar perusahaan di penyimpanan kepercayaan OS Anda atau bundel NODE_EXTRA_CA_CERTS tidak memerlukan penyiapan khusus Amazon Bedrock.

Sebelum v2.1.260, Claude Code menerapkan konfigurasi CA Anda ke permintaan ini hanya ketika mereka melewati proxy yang dikonfigurasi, dan pada koneksi langsung mereka hanya mempercayai penyimpanan sertifikat default runtime.

Sebelum v2.1.261, pencarian kredensial di belakang pemeriksaan model wizard penyiapan dengan opsi Use credentials already in my environment masih hanya mempercayai penyimpanan sertifikat default runtime. Di belakang proxy yang melakukan inspeksi TLS yang sertifikat akarnya hanya ada di penyimpanan OS, permintaan yang terpengaruh gagal dengan unable to get local issuer certificate, atau wizard menunjukkan model sebagai unreachable, sementara permintaan inferensi berhasil. Perbarui ke v2.1.261 atau lebih baru.

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

Jika Anda menerima kesalahan "on-demand throughput isn't supported":

• Tentukan model sebagai ID profil inferensi

Kesalahan streaming di belakang gateway atau proxy

Amazon Bedrock melakukan streaming respons InvokeModelWithResponseStream dalam format event-stream biner dengan header Content-Type: application/vnd.amazon.eventstream. Gateway atau proxy antara Claude Code dan Amazon Bedrock harus meneruskan badan respons dan headernya, termasuk Content-Type, seperti yang dikirim Amazon Bedrock.

Jika gateway menulis ulang Content-Type ke nilai lain, Claude Code menolak respons dengan kesalahan yang dimulai dengan Bedrock streaming response has content-type, menyebutkan nilai yang diterima. Penulisan ulang umum adalah text/event-stream, dari integrasi yang memancarkan kembali aliran sebagai server-sent events. Untuk variabel CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD yang disebutkan dalam pesan kesalahan, lihat Bedrock streaming response has an unexpected content-type.

Jika gateway menghapus atau mengosongkan header sebagai gantinya, Claude Code mengasumsikan badan adalah event stream Amazon Bedrock dan mendekodenya, jadi badan yang gateway teruskan tanpa diubah terus melakukan streaming.

Jika gateway yang menghapus header juga memancarkan kembali aliran sebagai server-sent events, Claude Code tidak dapat mendekode badan dan kembali ke jalur non-streaming yang lebih lambat pada setiap giliran: setiap respons muncul hanya setelah selesai alih-alih melakukan streaming. Dalam hal itu, atur CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT=1 sehingga Claude Code membaca badan sebagai server-sent events sebagai gantinya.

Untuk memperbaiki kesalahan atau fallback, konfigurasikan gateway untuk meneruskan badan respons InvokeModelWithResponseStream dan header Content-Type-nya tanpa diubah.

Gateway yang mengonversi aliran ke server-sent events tidak lagi melayani Amazon Bedrock API. Jika juga menerima permintaan Anthropic Messages API, hubungkan sebagai gateway LLM dengan ANTHROPIC_BASE_URL alih-alih CLAUDE_CODE_USE_BEDROCK.

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.

Apa yang berarti 403 dari endpoint Mantle tergantung pada apakah kesalahan menyebutkan tindakan IAM:

• Jika kesalahan menyebutkan tindakan bedrock-mantle:, berikan identitas IAM Anda tindakan itu.
• Jika kesalahan tidak menyebutkan tindakan dan kredensial Anda valid, akun AWS Anda belum diberikan akses ke model yang Anda minta. Hubungi tim akun AWS Anda untuk meminta akses.

400 yang menyebutkan ID model berarti model itu tidak dilayani di Mantle. Mantle memiliki lineup model sendiri yang terpisah dari katalog Amazon Bedrock standar, jadi ID profil inferensi seperti us.anthropic.claude-sonnet-4-6 tidak berfungsi. Gunakan ID format Mantle, atau aktifkan kedua endpoint sehingga Claude Code mengirimkan ID profil inferensi ke Invoke API.

Sumber daya tambahan

• Dokumentasi Amazon Bedrock
• Harga Amazon Bedrock
• Profil inferensi Amazon Bedrock
• Burndown token Amazon Bedrock dan kuota
• Claude Code di Amazon Bedrock: Panduan Pengaturan Cepat
• Implementasi Pemantauan Claude Code (Amazon Bedrock)