Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Prasyarat

Sebelum mengonfigurasi Claude Code dengan Vertex AI, pastikan Anda memiliki:
  • Akun Google Cloud Platform (GCP) dengan penagihan diaktifkan
  • Proyek GCP dengan Vertex AI API diaktifkan
  • Akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)
  • Google Cloud SDK (gcloud) terinstal dan dikonfigurasi
  • Kuota dialokasikan di wilayah GCP yang diinginkan
Untuk masuk dengan kredensial Vertex AI Anda sendiri, ikuti Masuk dengan Vertex AI di bawah. Untuk menerapkan Claude Code di seluruh tim, gunakan langkah pengaturan manual dan pin versi model Anda sebelum melakukan peluncuran.

​
Masuk dengan Vertex AI

Jika Anda memiliki kredensial Google Cloud dan ingin mulai menggunakan Claude Code melalui Vertex AI, wizard login akan memandu Anda. Anda menyelesaikan prasyarat sisi GCP sekali per proyek; wizard menangani sisi Claude Code.
Wizard pengaturan Vertex AI memerlukan Claude Code v2.1.98 atau lebih baru. Jalankan claude --version untuk memeriksa.
1

Aktifkan model Claude di proyek GCP Anda

Aktifkan Vertex AI API untuk proyek Anda, kemudian minta akses ke model Claude yang Anda inginkan di Vertex AI Model Garden. Lihat konfigurasi IAM untuk izin yang akun Anda butuhkan.
2

Mulai Claude Code dan pilih Vertex AI

Jalankan claude. Pada prompt login, pilih 3rd-party platform, kemudian Google Vertex AI.
3

Ikuti prompt wizard

Pilih cara Anda melakukan autentikasi ke Google Cloud: Application Default Credentials dari gcloud, file kunci akun layanan, atau kredensial yang sudah ada di lingkungan Anda. Wizard mendeteksi proyek dan wilayah Anda, memverifikasi model Claude mana yang dapat dijalankan proyek Anda, dan memungkinkan Anda untuk mempinnya. Ini menyimpan hasilnya ke blok env dari file pengaturan pengguna Anda, jadi Anda tidak perlu mengekspor variabel lingkungan sendiri.
Setelah Anda masuk, jalankan /setup-vertex kapan saja untuk membuka kembali wizard dan mengubah kredensial, proyek, wilayah, atau pin model Anda.

​
Konfigurasi wilayah

Claude Code mendukung Vertex AI global, multi-region, dan titik akhir regional. Atur CLOUD_ML_REGION ke global, lokasi multi-region seperti eu atau us, atau wilayah spesifik seperti us-east5. Claude Code memilih nama host Vertex AI yang benar untuk setiap bentuk, termasuk host aiplatform.eu.rep.googleapis.com dan aiplatform.us.rep.googleapis.com untuk lokasi multi-region.
Vertex AI mungkin tidak mendukung model default Claude Code di setiap jenis titik akhir. Ketersediaan model bervariasi di wilayah spesifik, lokasi multi-region, dan titik akhir global. Anda mungkin perlu beralih ke lokasi yang didukung atau menentukan model yang didukung.

​
Pengaturan manual

Untuk mengonfigurasi Vertex AI melalui variabel lingkungan alih-alih wizard, misalnya di CI atau peluncuran perusahaan yang ditulis skrip, ikuti langkah-langkah di bawah.

​
1. Aktifkan Vertex AI API

Aktifkan Vertex AI API di proyek GCP Anda: 
# Atur ID proyek Anda
gcloud config set project YOUR-PROJECT-ID

# Aktifkan Vertex AI API
gcloud services enable aiplatform.googleapis.com

​
2. Minta akses model

Minta akses ke model Claude di Vertex AI:
  1. Navigasikan ke Vertex AI Model Garden
  2. Cari model “Claude”
  3. Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)
  4. Tunggu persetujuan (mungkin memakan waktu 24-48 jam)

​
3. Konfigurasi kredensial GCP

Claude Code menggunakan autentikasi Google Cloud standar. Untuk informasi lebih lanjut, lihat dokumentasi autentikasi Google Cloud. Claude Code v2.1.121 atau lebih baru mendukung Workload Identity Federation berbasis sertifikat X.509 melalui rantai Application Default Credentials yang sama. Atur GOOGLE_APPLICATION_CREDENTIALS ke jalur file konfigurasi kredensial Anda.
Claude Code menggunakan ANTHROPIC_VERTEX_PROJECT_ID sebagai ID proyek untuk permintaan Vertex AI. Variabel lingkungan GCLOUD_PROJECT dan GOOGLE_CLOUD_PROJECT serta file kredensial yang dirujuk oleh GOOGLE_APPLICATION_CREDENTIALS memiliki prioritas lebih tinggi daripada itu. Jika tidak ada yang diatur, ID proyek diselesaikan dari konfigurasi gcloud Anda atau akun layanan yang terlampir.

​
Konfigurasi kredensial lanjutan

Claude Code mendukung penyegaran kredensial otomatis untuk GCP melalui pengaturan gcpAuthRefresh. Ketika Claude Code mendeteksi bahwa kredensial GCP Anda telah kedaluwarsa atau tidak dapat dimuat, Claude Code menjalankan perintah yang dikonfigurasi untuk mendapatkan kredensial baru sebelum mencoba ulang permintaan. 
{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}
Output perintah ditampilkan kepada pengguna, tetapi input interaktif tidak didukung. Ini berfungsi dengan baik untuk alur autentikasi berbasis browser di mana CLI menampilkan URL dan Anda menyelesaikan autentikasi di browser. Perintah penyegaran habis waktu setelah tiga menit jika autentikasi tidak selesai. Jika Anda mengatur gcpAuthRefresh dalam pengaturan proyek seperti .claude/settings.json, perintah hanya berjalan setelah Anda menerima prompt kepercayaan ruang kerja.

​
4. Konfigurasi Claude Code

Atur variabel lingkungan berikut: 
# Aktifkan integrasi Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opsional: Timpa URL titik akhir Vertex untuk titik akhir kustom atau gateway
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Opsional: Nonaktifkan prompt caching jika diperlukan
export DISABLE_PROMPT_CACHING=1

# Opsional: Minta TTL cache prompt 1 jam alih-alih default 5 menit
export ENABLE_PROMPT_CACHING_1H=1

# Ketika CLOUD_ML_REGION=global, timpa wilayah untuk model yang tidak mendukung titik akhir global
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
Sebagian besar versi model memiliki variabel VERTEX_REGION_CLAUDE_* yang sesuai. Lihat referensi variabel lingkungan untuk daftar lengkap. Periksa Vertex Model Garden untuk menentukan model mana yang mendukung titik akhir global versus regional saja. Prompt caching diaktifkan secara otomatis. Untuk menonaktifkannya, atur DISABLE_PROMPT_CACHING=1. Untuk meminta TTL cache 1 jam alih-alih default 5 menit, atur ENABLE_PROMPT_CACHING_1H=1; penulisan cache dengan TTL 1 jam ditagih dengan tarif yang lebih tinggi. Untuk batas laju yang lebih tinggi, hubungi dukungan Google Cloud. Saat menggunakan Vertex AI, perintah /login dan /logout dinonaktifkan karena autentikasi ditangani melalui kredensial Google Cloud. Claude Code menonaktifkan pencarian alat MCP secara default di Vertex AI, sehingga definisi alat MCP dimuat di muka. Vertex AI mendukung pencarian alat untuk Claude Sonnet 4.5 dan lebih baru serta Claude Opus 4.5 dan lebih baru. Atur ENABLE_TOOL_SEARCH=true untuk mengaktifkannya pada model tersebut. Model sebelumnya di Vertex AI tidak menerima header beta yang diperlukan, dan permintaan gagal jika Anda mengaktifkan pencarian alat dengan model tersebut.

​
5. Pin versi model

Pin versi model spesifik saat menerapkan ke beberapa pengguna. Tanpa pinning, alias model seperti sonnet dan opus diselesaikan ke versi terbaru, yang mungkin belum diaktifkan di proyek Vertex AI Anda ketika Anthropic merilis pembaruan. Claude Code kembali ke versi sebelumnya saat startup ketika versi terbaru tidak tersedia, tetapi pinning memungkinkan Anda mengontrol kapan pengguna Anda pindah ke model baru.
Atur variabel lingkungan ini ke ID model Vertex AI spesifik. Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Vertex diselesaikan ke Opus 4.6. Aturnya ke ID Opus 4.7 untuk menggunakan model terbaru: 
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
Untuk ID model saat ini dan warisan, lihat Ikhtisar Model. Lihat Konfigurasi Model untuk daftar lengkap variabel lingkungan. Claude Code menggunakan model default ini ketika tidak ada variabel pinning yang diatur:
Jenis modelNilai default
Model utamaclaude-sonnet-4-5@20250929
Model kecil/cepatSama dengan model utama
Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Vertex AI, Claude Code menganggap default ini ke model utama karena Haiku mungkin tidak diaktifkan di setiap proyek atau wilayah. Untuk menggunakan Haiku untuk tugas latar belakang, atur ANTHROPIC_DEFAULT_HAIKU_MODEL ke ID model yang tersedia di proyek Anda. Untuk menyesuaikan model lebih lanjut: 
export ANTHROPIC_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

​
Pemeriksaan model startup

Ketika Claude Code dimulai dengan Vertex AI dikonfigurasi, ia memverifikasi bahwa model yang dimaksudkan untuk digunakan dapat diakses di proyek Anda. Pemeriksaan ini memerlukan Claude Code v2.1.98 atau lebih baru. Jika Anda telah mempinkan versi model yang lebih lama dari default Claude Code saat ini, dan proyek Anda dapat memanggil versi yang lebih baru, Claude Code akan 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. Jika Anda belum mempinkan model dan default saat ini tidak tersedia di proyek Anda, Claude Code kembali ke versi sebelumnya untuk sesi saat ini dan menampilkan pemberitahuan. Fallback tidak disimpan. Aktifkan model yang lebih baru di Model Garden atau pin versi untuk membuat pilihan permanen.

​
Konfigurasi IAM

Tetapkan izin IAM yang diperlukan: Peran roles/aiplatform.user mencakup izin yang diperlukan:
  • aiplatform.endpoints.predict - Diperlukan untuk invokasi model dan penghitungan token
Untuk izin yang lebih ketat, buat peran kustom dengan hanya izin di atas. Untuk detail, lihat dokumentasi Vertex IAM.
Buat proyek GCP khusus untuk Claude Code untuk menyederhanakan pelacakan biaya dan kontrol akses.

​
Jendela konteks token 1M

Claude Opus 4.7, Opus 4.6, dan Sonnet 4.6 mendukung jendela konteks token 1M di Vertex AI. Claude Code secara otomatis mengaktifkan jendela konteks yang diperluas ketika Anda memilih varian model 1M. Wizard pengaturan menawarkan opsi konteks 1M ketika mempinkan model. Untuk mengaktifkannya untuk model yang dipinkan secara manual, tambahkan [1m] ke ID model. Lihat Pin models for third-party deployments untuk detail.

​
Pemecahan masalah

Jika Anda mengalami kesalahan “Could not load the default credentials”:
  • Jalankan gcloud auth application-default login untuk menyiapkan Application Default Credentials
  • Atur GOOGLE_APPLICATION_CREDENTIALS ke jalur file kunci akun layanan
  • Lihat Configure GCP credentials untuk semua opsi
Jika Anda mengalami masalah kuota:
  • Periksa kuota saat ini atau minta peningkatan kuota melalui Cloud Console
Jika Anda mengalami kesalahan “model not found” 404:
  • Konfirmasi model diaktifkan di Model Garden
  • Verifikasi model tersedia di lokasi yang Anda tentukan. Beberapa model hanya ditawarkan di lokasi global atau multi-region seperti eu dan us, bukan di wilayah spesifik
  • Jika menggunakan CLOUD_ML_REGION=global, periksa bahwa model Anda mendukung titik akhir global di Model Garden di bawah “Supported features”. Untuk model yang tidak mendukung titik akhir global, baik:
    • Tentukan model yang didukung melalui ANTHROPIC_MODEL atau ANTHROPIC_DEFAULT_HAIKU_MODEL, atau
    • Atur wilayah atau lokasi multi-region menggunakan variabel lingkungan VERTEX_REGION_<MODEL_NAME>
Jika Anda mengalami kesalahan 429:
  • Untuk titik akhir regional, pastikan model utama dan model kecil/cepat didukung di wilayah yang Anda pilih
  • Pertimbangkan untuk beralih ke CLOUD_ML_REGION=global untuk ketersediaan yang lebih baik

​
Sumber daya tambahan