Claude Code di Platform Agen Google Cloud

Pelajari tentang mengonfigurasi Claude Code melalui Platform Agen Google Cloud, yang sebelumnya bernama Vertex AI, 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 Google Cloud's Agent Platform, yang sebelumnya dikenal sebagai Vertex AI, pastikan Anda memiliki:

Akun Google Cloud Platform (GCP) dengan penagihan diaktifkan
Proyek GCP dengan Google Cloud's Agent Platform 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 Google Cloud's Agent Platform Anda sendiri, ikuti Masuk dengan Google Cloud's Agent Platform di bawah. Untuk menerapkan Claude Code di seluruh tim, gunakan langkah pengaturan manual dan pin versi model Anda sebelum melakukan peluncuran.

Masuk dengan Agent Platform

Jika Anda memiliki kredensial Google Cloud dan ingin mulai menggunakan Claude Code melalui Agent Platform Google Cloud, wizard login akan memandu Anda. Anda menyelesaikan prasyarat sisi GCP sekali per proyek; wizard menangani sisi Claude Code.

1. Aktifkan model Claude di proyek GCP Anda

Aktifkan API Agent Platform Google Cloud untuk proyek Anda, kemudian minta akses ke model Claude yang Anda inginkan di Model Garden Agent Platform Google Cloud. Lihat konfigurasi IAM untuk izin yang akun Anda butuhkan.

2. Mulai Claude Code dan pilih Agent Platform Google Cloud

Jalankan claude. Pada prompt login, pilih 3rd-party platform, kemudian Google Vertex AI, label yang masih digunakan prompt login untuk Agent Platform Google Cloud. Jika Anda sudah masuk, jalankan /login untuk membuka menu yang sama.

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. 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.

Konfigurasi wilayah

Claude Code mendukung Google Cloud's Agent Platform 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 Google Cloud's Agent Platform yang benar untuk setiap bentuk, termasuk host aiplatform.eu.rep.googleapis.com dan aiplatform.us.rep.googleapis.com untuk lokasi multi-region.

[!NOTE]

Google Cloud's Agent Platform 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.

Menyiapkan secara manual

Untuk mengonfigurasi Agent Platform milik Google Cloud melalui environment variable alih-alih wizard, misalnya di CI atau peluncuran enterprise berbasis skrip, ikuti langkah-langkah di bawah ini.

Aktifkan Agent Platform API

Aktifkan Agent Platform API milik Google Cloud di proyek GCP Anda. Ganti YOUR-PROJECT-ID dengan ID proyek GCP Anda di sini dan di langkah konfigurasi di bawah:

# Set your project ID
gcloud config set project YOUR-PROJECT-ID

# Enable Agent Platform API
gcloud services enable aiplatform.googleapis.com

Minta akses model

Minta akses ke model Claude di Agent Platform milik Google Cloud:

Buka Model Garden Agent Platform milik Google Cloud
Cari model "Claude"
Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)
Tunggu persetujuan (dapat memakan waktu 24-48 jam)

Konfigurasikan kredensial GCP

Claude Code menggunakan autentikasi Google Cloud standar.

Untuk informasi lebih lanjut, lihat dokumentasi autentikasi Google Cloud.

Claude Code mendukung Workload Identity Federation berbasis sertifikat X.509 melalui rantai Application Default Credentials yang sama. Atur GOOGLE_APPLICATION_CREDENTIALS ke path file konfigurasi kredensial Anda.

[!NOTE]

Claude Code mengarahkan permintaan Agent Platform milik Google Cloud ke proyek di ANTHROPIC_VERTEX_PROJECT_ID, bahkan ketika GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, atau file kredensial yang dirujuk oleh GOOGLE_APPLICATION_CREDENTIALS memuat proyek yang berbeda.

Konfigurasi kredensial lanjutan

Claude Code mendukung penyegaran kredensial otomatis untuk GCP melalui pengaturan gcpAuthRefresh. Tambahkan pengaturan ini ke file pengaturan Claude Code Anda, misalnya ~/.claude/settings.json. Ketika Claude Code mendeteksi bahwa kredensial GCP Anda telah kedaluwarsa atau tidak dapat dimuat, Claude Code menjalankan perintah yang dikonfigurasi untuk memperoleh kredensial baru sebelum mencoba ulang permintaan.

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

Sebelum menjalankan perintah tersebut, Claude Code meminta access token dengan kredensial Anda saat ini untuk memastikan kredensial tersebut benar-benar kedaluwarsa, dan melewati perintah tersebut jika kredensial masih berfungsi.

Jika pemeriksaan tidak selesai dalam lima detik, Claude Code juga melewati perintah tersebut dan baru menjalankannya setelah sebuah permintaan gagal dengan kesalahan kredensial. Sebelum v2.1.261, pemeriksaan yang mengalami timeout dianggap sebagai kredensial yang kedaluwarsa, sehingga perintah tersebut dapat membuka browser Anda saat startup meskipun kredensial Anda masih valid.

Claude Code menampilkan output perintah tersebut kepada Anda, tetapi tidak dapat mengirimkan input interaktif ke perintah tersebut. Ini berfungsi dengan baik untuk alur autentikasi berbasis browser di mana CLI menampilkan URL dan Anda menyelesaikan autentikasi di browser. Perintah penyegaran akan timeout setelah tiga menit jika autentikasi tidak selesai. Jika Anda mengatur gcpAuthRefresh di pengaturan proyek seperti .claude/settings.json, Claude Code menjalankannya di bawah aturan kepercayaan workspace yang sama seperti hook di file pengaturan, yang mencakup sesi -p di folder yang belum pernah Anda percayai.

Konfigurasikan Claude Code

Atur environment variable berikut:

# Enable Agent Platform integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Override the Agent Platform endpoint URL for custom endpoints or gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# When CLOUD_ML_REGION=global, override region for models that don't support global endpoints
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 Environment variable untuk daftar lengkapnya. Periksa Model Garden Agent Platform milik Google Cloud untuk menentukan model mana yang mendukung endpoint global dibandingkan yang hanya regional.

Jika nilai region tidak berbentuk seperti nama region atau lokasi, Claude Code memperlakukannya sebagai tidak diatur. Misalnya, Claude Code memperlakukan nilai yang mengandung garis miring, titik, atau spasi sebagai tidak diatur. Claude Code beralih ke sumber yang berbeda untuk setiap variabel:

VERTEX_REGION_CLAUDE_*: Claude Code beralih ke CLOUD_ML_REGION.
CLOUD_ML_REGION: Claude Code beralih ke us-east5.

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 lebih tinggi. Untuk mengatur TTL yang berbeda untuk percakapan utama Anda dan untuk permintaan yang dibuat Claude Code di luar percakapan tersebut, pilih TTL sendiri.

Untuk menaikkan rate limit Anda, hubungi dukungan Google Cloud. Saat menggunakan Agent Platform milik Google Cloud, perintah /logout tidak tersedia karena autentikasi ditangani melalui kredensial Google Cloud.

Claude Code memutuskan antara MCP tool search dan pemuatan di awal berdasarkan generasi model:

Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, dan yang lebih baru: Claude Code mengaktifkan pencarian tool secara default.
Model yang lebih lama: Claude Code memuat definisi tool MCP di awal, karena stack penyajian Agent Platform untuk model tersebut menolak beta header yang diperlukan. Mengatur ENABLE_TOOL_SEARCH=true tidak menimpa perilaku ini.

Atur ENABLE_TOOL_SEARCH=false untuk menonaktifkan pencarian tool di setiap model.

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 Agent Platform milik Google Cloud, yang dapat tertinggal dari rilis terbaru dan mungkin belum diaktifkan di proyek Anda. Claude Code beralih ke model yang lebih lama atau tingkatnya lebih rendah saat startup ketika default tidak tersedia, tetapi penyematan memungkinkan Anda mengontrol kapan pengguna Anda berpindah ke model baru.

Atur environment variable ini ke ID model Agent Platform milik Google Cloud yang spesifik.

Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Agent Platform milik Google Cloud 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='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

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

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

Jenis model	Nilai default
Model utama	`claude-opus-5-5`
Model kecil/cepat	`claude-sonnet-4-5@20250929`

Sebelum v2.1.280, model utama di Agent Platform milik Google Cloud 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 Agent Platform milik Google Cloud, Claude Code menggunakan model Sonnet default untuk tugas latar belakang karena Haiku mungkin tidak diaktifkan di setiap proyek 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 proyek yang mengarahkan Opus-nya sendiri.
Untuk menggunakan Haiku untuk tugas latar belakang, atur ANTHROPIC_DEFAULT_HAIKU_MODEL ke ID model yang tersedia di proyek Anda.

[!WARNING]

Model Opus memiliki harga per token yang lebih tinggi daripada model Sonnet, sehingga 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:

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Verifikasi konfigurasi Anda

Jalankan Claude Code dan jalankan /status untuk mengonfirmasi penyiapan. Baris API provider menampilkan Google Vertex AI, dan baris GCP project, Default region, dan Model menampilkan ID proyek, region, dan model yang telah di-resolve. Jika baris provider tidak ada, environment variable tidak mencapai proses tersebut. Pastikan variabel tersebut di-export di shell tempat Anda menjalankan claude, atau atur variabel tersebut di blok env pada file pengaturan Anda.

Pemeriksaan model startup

Ketika Claude Code dimulai dengan Google Cloud's Agent Platform dikonfigurasi, ia memverifikasi bahwa model yang dimaksudkan untuk digunakan dapat diakses di proyek Anda.

Anda mungkin telah mempinkan versi model yang lebih lama dari default Claude Code saat ini. Jika proyek Anda dapat memanggil versi yang lebih baru, Claude Code meminta Anda untuk memperbarui pin:

Jika Anda menerima: Claude Code menulis ID model baru ke file pengaturan pengguna Anda dan memulai ulang
Jika Anda menolak: Claude Code mengingat pilihan Anda sampai perubahan versi default berikutnya

Untuk pin di blok env dari pengaturan terkelola, Claude Code tidak menjalankan pemeriksaan dan tidak menampilkan dialog apa pun. Jika dialog pembaruan masih muncul untuk pin ini, perbarui Claude Code ke v2.1.314 atau yang lebih baru. Sebelum v2.1.314, pin terkelola tetap berlaku setelah Anda menerima, sehingga dialog muncul kembali pada startup berikutnya.

Jika Anda belum mempinkan model dan default saat ini tidak tersedia di proyek Anda, Claude Code kembali untuk sesi saat ini dan menampilkan pemberitahuan. Ia 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 Model Garden atau pin 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 dipinkan untuk sesi yang cocok dengan alias sonnet atau opus. Claude Code melewati pemeriksaan ketersediaan untuk default bawaan yang diganti model Anda dan dimulai pada model yang Anda konfigurasi, tanpa pemberitahuan fallback.

Ketika Anda memulai sesi pada alias model seperti opus atau pada ID model yang tidak dikenali Claude Code, nilai tersebut tidak bertindak sebagai pin.

Penolakan model yang diingat

Ketika pemeriksaan model startup menemukan model yang tidak dapat dipanggil proyek 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 dari model default saat ini saat peluncuran. Default yang diaktifkan kembali oleh administrator Anda kemudian akan kembali. Untuk mematikan memori, atur CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1.

Ketika organisasi Anda memberlakukan allowlist model

Jika Anda mengatur enforceAvailableModels di pengaturan terkelola, pemeriksaan model startup hanya menggunakan model yang diizinkan oleh daftar availableModels Anda. Ini memerlukan Claude Code v2.1.287 atau yang lebih baru. Daftar tanpa enforceAvailableModels tidak membatasi pemeriksaan ini.

Pemeriksaan membandingkan setiap entri dengan ID model yang akan dikirimkan ke Agent Platform, jadi tulis daftar tersebut menggunakan ID tersebut. Contoh ini mengizinkan Opus 4.8 dan Sonnet 4.5:

{
  "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],
  "enforceAvailableModels": true
}

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

Ketika model dinonaktifkan di tengah sesi

Jika proyek Anda kehilangan akses ke model yang sesi Anda jalankan, misalnya karena administrator menonaktifkannya di Model Garden, Claude Code beralih sesi ke model lain alih-alih gagal pada setiap permintaan, dan menampilkan Switched to <fallback> because <model> is not available. Ia 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 pinkan, kondisi yang sama seperti fallback startup. Sesi pada versi spesifik yang Anda pilih mempertahankan modelnya dan, tanpa rantai model fallback, permintaan gagal sebagai gantinya. Dalam mode auto, Claude Code hanya beralih ke model yang didukung mode auto di Agent Platform. Jika tidak ada model tersebut yang tersedia, permintaan gagal.

Rantai model fallback 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.

Konfigurasi IAM

Tetapkan peran roles/aiplatform.user, yang 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 IAM Agent Platform Google Cloud.

[!NOTE]

Buat proyek GCP 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 Platform Agent Google Cloud, tanpa perlu sufiks [1m]. Untuk tetap menggunakan window 200K, atur CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Opus 4.6 dan Sonnet 4.6 mencapai window 1M ketika Anda memilih varian [1m] mereka. Wizard pengaturan menawarkan opsi konteks 1M ketika mempinkan model. Untuk mengaktifkannya pada model yang dipinkan secara manual, tambahkan [1m] ke ID model. Lihat Pin models for third-party deployments untuk detail, termasuk cara menggunakan window 1M tanpa mengubah pin.

Sebelum v2.1.287, model Fable serta Opus 4.7 dan yang lebih baru berjalan dengan window 200K secara default di Platform Agent Google Cloud dan mencapai window 1M melalui sufiks [1m].

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 endpoint global di Model Garden di bawah "Supported features". Untuk model yang tidak mendukung endpoint global, baik:
- Tentukan model yang didukung melalui ANTHROPIC_MODEL atau ANTHROPIC_DEFAULT_HAIKU_MODEL, atau
- Atur wilayah atau lokasi multi-region menggunakan variabel VERTEX_REGION_CLAUDE_* milik model tersebut, yang tercantum dalam referensi environment variable

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

google-vertex-ai.md +41 −41

49>49>

50> Google Cloud's Agent Platform mungkin tidak mendukung model default Claude Code di setiap jenis titik akhir. Ketersediaan model bervariasi di [wilayah spesifik](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), lokasi multi-region, dan [titik akhir global](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). Anda mungkin perlu beralih ke lokasi yang didukung atau menentukan model yang didukung.50> Google Cloud's Agent Platform mungkin tidak mendukung model default Claude Code di setiap jenis titik akhir. Ketersediaan model bervariasi di [wilayah spesifik](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), lokasi multi-region, dan [titik akhir global](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). Anda mungkin perlu beralih ke lokasi yang didukung atau menentukan model yang didukung.

51 51

~~52## Pengaturan manual~~52## Menyiapkan secara manual

53 53

~~54Untuk mengonfigurasi Google Cloud's Agent Platform melalui variabel lingkungan alih-alih wizard, misalnya di CI atau peluncuran perusahaan yang ditulis skrip, ikuti langkah-langkah di bawah.~~54Untuk mengonfigurasi Agent Platform milik Google Cloud melalui environment variable alih-alih wizard, misalnya di CI atau peluncuran enterprise berbasis skrip, ikuti langkah-langkah di bawah ini.

55 55

56### Aktifkan Agent Platform API56### Aktifkan Agent Platform API

57 57

~~58Aktifkan Google Cloud's Agent Platform API di proyek GCP Anda. Ganti `YOUR-PROJECT-ID` dengan ID proyek GCP Anda di sini dan di langkah konfigurasi di bawah:~~58Aktifkan Agent Platform API milik Google Cloud di proyek GCP Anda. Ganti `YOUR-PROJECT-ID` dengan ID proyek GCP Anda di sini dan di langkah konfigurasi di bawah:

59 59

60```bash theme={null}60```bash theme={null}

~~61# Atur ID proyek Anda~~61# Set your project ID

62gcloud config set project YOUR-PROJECT-ID62gcloud config set project YOUR-PROJECT-ID

63 63

~~64# Aktifkan Agent Platform API~~64# Enable Agent Platform API

65gcloud services enable aiplatform.googleapis.com65gcloud services enable aiplatform.googleapis.com

66```66```

67 67

68### Minta akses model68### Minta akses model

69 69

~~70Minta akses ke model Claude di Google Cloud's Agent Platform:~~70Minta akses ke model Claude di Agent Platform milik Google Cloud:

71 71

~~721. Navigasikan ke [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)~~721. Buka [Model Garden Agent Platform milik Google Cloud](https://console.cloud.google.com/vertex-ai/model-garden)

732. Cari model "Claude"732. Cari model "Claude"

743. Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)743. Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)

~~754. Tunggu persetujuan (mungkin memakan waktu 24-48 jam)~~754. Tunggu persetujuan (dapat memakan waktu 24-48 jam)

76 76

~~77### Konfigurasi kredensial GCP~~77### Konfigurasikan kredensial GCP

78 78

79Claude Code menggunakan autentikasi Google Cloud standar.79Claude Code menggunakan autentikasi Google Cloud standar.

80 80

81Untuk informasi lebih lanjut, lihat [dokumentasi autentikasi Google Cloud](https://cloud.google.com/docs/authentication).81Untuk informasi lebih lanjut, lihat [dokumentasi autentikasi Google Cloud](https://cloud.google.com/docs/authentication).

82 82

83Claude Code mendukung [Workload Identity Federation berbasis sertifikat X.509](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) melalui rantai Application Default Credentials yang sama. Atur `GOOGLE_APPLICATION_CREDENTIALS` ke jalur file konfigurasi kredensial Anda.83Claude Code mendukung [Workload Identity Federation berbasis sertifikat X.509](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) melalui rantai Application Default Credentials yang sama. Atur `GOOGLE_APPLICATION_CREDENTIALS` ke path file konfigurasi kredensial Anda.

84 84

85> [!NOTE]85> [!NOTE]

86>86>

87> Claude Code mengarahkan permintaan Google Cloud's Agent Platform ke proyek di `ANTHROPIC_VERTEX_PROJECT_ID`, bahkan ketika `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, atau file kredensial yang dirujuk oleh `GOOGLE_APPLICATION_CREDENTIALS` membawa proyek yang berbeda.87> Claude Code mengarahkan permintaan Agent Platform milik Google Cloud ke proyek di `ANTHROPIC_VERTEX_PROJECT_ID`, bahkan ketika `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, atau file kredensial yang dirujuk oleh `GOOGLE_APPLICATION_CREDENTIALS` memuat proyek yang berbeda.

88 88

89#### Konfigurasi kredensial lanjutan89#### Konfigurasi kredensial lanjutan

90 90

91Claude Code mendukung penyegaran kredensial otomatis untuk GCP melalui pengaturan `gcpAuthRefresh`. Tambahkan ke [file pengaturan](https://code.claude.com/docs/id/settings.md) Claude Code Anda, misalnya `~/.claude/settings.json`. 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.91Claude Code mendukung penyegaran kredensial otomatis untuk GCP melalui pengaturan `gcpAuthRefresh`. Tambahkan pengaturan ini ke [file pengaturan](https://code.claude.com/docs/id/settings.md) Claude Code Anda, misalnya `~/.claude/settings.json`. Ketika Claude Code mendeteksi bahwa kredensial GCP Anda telah kedaluwarsa atau tidak dapat dimuat, Claude Code menjalankan perintah yang dikonfigurasi untuk memperoleh kredensial baru sebelum mencoba ulang permintaan.

92 92

93```json theme={null}93```json theme={null}

94{94{

99}99}

100```100```

101 101

102Sebelum menjalankan perintah, Claude Code meminta token akses dengan kredensial Anda saat ini untuk mengonfirmasi bahwa kredensial tersebut benar-benar kedaluwarsa, dan melewati perintah ketika kredensial masih berfungsi.102Sebelum menjalankan perintah tersebut, Claude Code meminta access token dengan kredensial Anda saat ini untuk memastikan kredensial tersebut benar-benar kedaluwarsa, dan melewati perintah tersebut jika kredensial masih berfungsi.

103 103

104Jika pemeriksaan tidak selesai dalam lima detik, Claude Code juga melewati perintah dan menjalankannya hanya setelah permintaan gagal dengan kesalahan kredensial. Sebelum v2.1.261, pemeriksaan yang habis waktu dihitung sebagai kredensial yang kedaluwarsa, jadi perintah dapat membuka browser Anda saat startup meskipun kredensial Anda masih valid.104Jika pemeriksaan tidak selesai dalam lima detik, Claude Code juga melewati perintah tersebut dan baru menjalankannya setelah sebuah permintaan gagal dengan kesalahan kredensial. Sebelum v2.1.261, pemeriksaan yang mengalami timeout dianggap sebagai kredensial yang kedaluwarsa, sehingga perintah tersebut dapat membuka browser Anda saat startup meskipun kredensial Anda masih valid.

105 105

106Claude Code menampilkan output perintah kepada Anda, tetapi tidak dapat mengirim input interaktif perintah. 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`, Claude Code menjalankannya di bawah [aturan kepercayaan ruang kerja yang sama dengan hooks dalam file pengaturan](https://code.claude.com/docs/id/permissions.md#what-runs-before-you-trust-a-folder), yang mencakup sesi `-p` di folder yang belum pernah Anda percayai.106Claude Code menampilkan output perintah tersebut kepada Anda, tetapi tidak dapat mengirimkan input interaktif ke perintah tersebut. Ini berfungsi dengan baik untuk alur autentikasi berbasis browser di mana CLI menampilkan URL dan Anda menyelesaikan autentikasi di browser. Perintah penyegaran akan timeout setelah tiga menit jika autentikasi tidak selesai. Jika Anda mengatur `gcpAuthRefresh` di pengaturan proyek seperti `.claude/settings.json`, Claude Code menjalankannya di bawah [aturan kepercayaan workspace yang sama seperti hook di file pengaturan](https://code.claude.com/docs/id/permissions.md#what-runs-before-you-trust-a-folder), yang mencakup sesi `-p` di folder yang belum pernah Anda percayai.

107 107

108### Konfigurasi Claude Code108### Konfigurasikan Claude Code

109 109

110Atur variabel lingkungan berikut:110Atur environment variable berikut:

111 111

112```bash theme={null}112```bash theme={null}

113# Aktifkan integrasi Agent Platform113# Enable Agent Platform integration

114export CLAUDE_CODE_USE_VERTEX=1114export CLAUDE_CODE_USE_VERTEX=1

115export CLOUD_ML_REGION=global115export CLOUD_ML_REGION=global

116export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID116export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

117 117

118# Opsional: Timpa URL titik akhir Agent Platform untuk titik akhir kustom atau gateway118# Optional: Override the Agent Platform endpoint URL for custom endpoints or gateways

119# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com119# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

120 120

121# Ketika CLOUD_ML_REGION=global, timpa wilayah untuk model yang tidak mendukung titik akhir global121# When CLOUD_ML_REGION=global, override region for models that don't support global endpoints

122export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5122export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5

123export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1123export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

124```124```

125 125

126Sebagian besar versi model memiliki variabel `VERTEX_REGION_CLAUDE_*` yang sesuai. Lihat [referensi environment variable](https://code.claude.com/docs/id/env-vars.md#variables) untuk daftar lengkap. Periksa [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) untuk menentukan model mana yang mendukung endpoint global versus regional saja.126Sebagian besar versi model memiliki variabel `VERTEX_REGION_CLAUDE_*` yang sesuai. Lihat [referensi Environment variable](https://code.claude.com/docs/id/env-vars.md#variables) untuk daftar lengkapnya. Periksa [Model Garden Agent Platform milik Google Cloud](https://console.cloud.google.com/vertex-ai/model-garden) untuk menentukan model mana yang mendukung endpoint global dibandingkan yang hanya regional.

127 127

128Jika nilai wilayah tidak berbentuk seperti nama wilayah atau lokasi, Claude Code memperlakukannya sebagai tidak diatur. Misalnya, Claude Code memperlakukan nilai yang berisi garis miring, titik, atau spasi sebagai tidak diatur. Claude Code kembali ke sumber yang berbeda untuk setiap variabel:128Jika nilai region tidak berbentuk seperti nama region atau lokasi, Claude Code memperlakukannya sebagai tidak diatur. Misalnya, Claude Code memperlakukan nilai yang mengandung garis miring, titik, atau spasi sebagai tidak diatur. Claude Code beralih ke sumber yang berbeda untuk setiap variabel:

129 129

130* `VERTEX_REGION_CLAUDE_*`: Claude Code kembali ke `CLOUD_ML_REGION`.130* `VERTEX_REGION_CLAUDE_*`: Claude Code beralih ke `CLOUD_ML_REGION`.

131* `CLOUD_ML_REGION`: Claude Code kembali ke `us-east5`.131* `CLOUD_ML_REGION`: Claude Code beralih ke `us-east5`.

132 132

133[Prompt caching](https://code.claude.com/docs/id/prompt-caching.md) 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 menetapkan TTL yang berbeda untuk percakapan utama Anda dan untuk permintaan yang Claude Code buat di luar itu, [pilih TTL sendiri](https://code.claude.com/docs/id/prompt-caching.md#choose-the-ttl-yourself).133[Prompt caching](https://code.claude.com/docs/id/prompt-caching.md) 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 lebih tinggi. Untuk mengatur TTL yang berbeda untuk percakapan utama Anda dan untuk permintaan yang dibuat Claude Code di luar percakapan tersebut, [pilih TTL sendiri](https://code.claude.com/docs/id/prompt-caching.md#choose-the-ttl-yourself).

134 134

135Untuk menaikkan batas laju Anda, hubungi dukungan Google Cloud. Saat menggunakan Google Cloud's Agent Platform, perintah `/logout` tidak tersedia karena autentikasi ditangani melalui kredensial Google Cloud.135Untuk menaikkan rate limit Anda, hubungi dukungan Google Cloud. Saat menggunakan Agent Platform milik Google Cloud, perintah `/logout` tidak tersedia karena autentikasi ditangani melalui kredensial Google Cloud.

136 136

137Claude Code memutuskan antara [pencarian tool MCP](https://code.claude.com/docs/id/mcp.md#scale-with-mcp-tool-search) dan pemuatan di muka berdasarkan generasi model:137Claude Code memutuskan antara [MCP tool search](https://code.claude.com/docs/id/mcp.md#scale-with-mcp-tool-search) dan pemuatan di awal berdasarkan generasi model:

138 138

139* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, dan yang lebih baru**: Claude Code mengaktifkan pencarian alat secara default.139* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, dan yang lebih baru**: Claude Code mengaktifkan pencarian tool secara default.

140* **Model sebelumnya**: Claude Code memuat definisi tool MCP di muka, karena tumpukan penyajian Agent Platform mereka menolak header beta yang diperlukan. Mengatur `ENABLE_TOOL_SEARCH=true` tidak menimpa ini.140* **Model yang lebih lama**: Claude Code memuat definisi tool MCP di awal, karena stack penyajian Agent Platform untuk model tersebut menolak beta header yang diperlukan. Mengatur `ENABLE_TOOL_SEARCH=true` tidak menimpa perilaku ini.

141 141

142Atur `ENABLE_TOOL_SEARCH=false` untuk menonaktifkan pencarian tool pada setiap model.142Atur `ENABLE_TOOL_SEARCH=false` untuk menonaktifkan pencarian tool di setiap model.

143 143

144### Pin versi model144### Sematkan versi model

145 145

146> [!WARNING]146> [!WARNING]

147>147>

148> Pin versi model spesifik saat menerapkan ke beberapa pengguna. Tanpa pinning, alias model seperti `sonnet` dan `opus` diselesaikan ke default bawaan Claude Code untuk Google Cloud's Agent Platform, yang dapat tertinggal dari rilis terbaru dan mungkin belum diaktifkan di proyek Anda. Claude Code [kembali](#startup-model-checks) ke versi sebelumnya atau model tingkat lebih rendah saat startup ketika default tidak tersedia, tetapi pinning memungkinkan Anda mengontrol kapan pengguna Anda pindah ke model baru.148> 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 Agent Platform milik Google Cloud, yang dapat tertinggal dari rilis terbaru dan mungkin belum diaktifkan di proyek Anda. Claude Code [beralih](#startup-model-checks) ke model yang lebih lama atau tingkatnya lebih rendah saat startup ketika default tidak tersedia, tetapi penyematan memungkinkan Anda mengontrol kapan pengguna Anda berpindah ke model baru.

149 149

150Atur variabel lingkungan ini ke ID model Google Cloud's Agent Platform spesifik.150Atur environment variable ini ke ID model Agent Platform milik Google Cloud yang spesifik.

151 151

152Tanpa `ANTHROPIC_DEFAULT_OPUS_MODEL`, alias `opus` di Google Cloud's Agent Platform diselesaikan ke Opus 5.5, dan tanpa `ANTHROPIC_DEFAULT_SONNET_MODEL`, alias `sonnet` diselesaikan ke Sonnet 4.5. Contoh ini pin setiap alias ke versi spesifik:152Tanpa `ANTHROPIC_DEFAULT_OPUS_MODEL`, alias `opus` di Agent Platform milik Google Cloud 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:

153 153

154```bash theme={null}154```bash theme={null}

155export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'155export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

157export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'157export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

158```158```

159 159

160Untuk ID model saat ini dan warisan, lihat [Ikhtisar Model](https://platform.claude.com/docs/en/about-claude/models/overview). Lihat [Konfigurasi Model](https://code.claude.com/docs/id/model-config.md#pin-models-for-third-party-deployments) untuk daftar lengkap variabel lingkungan.160Untuk ID model saat ini dan lama, lihat [Ikhtisar model](https://platform.claude.com/docs/en/about-claude/models/overview). Lihat [Konfigurasi model](https://code.claude.com/docs/id/model-config.md#pin-models-for-third-party-deployments) untuk daftar lengkap environment variable.

161 161

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

163 163

164| Jenis model | Nilai default |164| Jenis model | Nilai default |

165| :- | :- |165| :- | :- |

168 168

169Sebelum v2.1.280, model utama di Google Cloud's Agent Platform default ke Opus 5 dan alias `opus` diselesaikan ke Opus 5 dari v2.1.219.169Sebelum v2.1.280, model utama di Agent Platform milik Google Cloud secara default adalah Opus 5 dan alias `opus` di-resolve ke Opus 5 sejak v2.1.219.

170 170

171Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Google Cloud's Agent Platform, Claude Code menggunakan model Sonnet default untuk tugas latar belakang karena Haiku mungkin tidak diaktifkan di setiap proyek atau wilayah. Dua pilihan mengubah model mana yang membawanya:171Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Agent Platform milik Google Cloud, Claude Code menggunakan model Sonnet default untuk tugas latar belakang karena Haiku mungkin tidak diaktifkan di setiap proyek atau region. Dua pilihan mengubah model mana yang menjalankannya:

172 172

173* 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`](https://code.claude.com/docs/id/model-config#set-a-default-model-for-new-sessions), tugas latar belakang menggunakan model tersebut juga. Mengatur `ANTHROPIC_DEFAULT_OPUS_MODEL` tanpa `ANTHROPIC_DEFAULT_SONNET_MODEL` juga dihitung sebagai pilihan, karena model Sonnet bawaan mungkin tidak diaktifkan dalam proyek yang mengarahkan Opus-nya sendiri.173* 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`](https://code.claude.com/docs/id/model-config#set-a-default-model-for-new-sessions), 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 proyek yang mengarahkan Opus-nya sendiri.

174* Untuk menggunakan Haiku untuk tugas latar belakang, atur `ANTHROPIC_DEFAULT_HAIKU_MODEL` ke ID model yang tersedia di proyek Anda.174* Untuk menggunakan Haiku untuk tugas latar belakang, atur `ANTHROPIC_DEFAULT_HAIKU_MODEL` ke ID model yang tersedia di proyek Anda.

175 175

176> [!WARNING]176> [!WARNING]

177>177>

178> Model Opus memiliki harga per-token yang lebih tinggi daripada model Sonnet, jadi jika Anda tidak melakukan pin 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` menjaga model Sonnet yang diarahkan sebagai default.178> Model Opus memiliki harga per token yang lebih tinggi daripada model Sonnet, sehingga 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.

179 179

180Untuk menyesuaikan model lebih lanjut:180Untuk menyesuaikan model lebih lanjut:

181 181

186 186

187### Verifikasi konfigurasi Anda187### Verifikasi konfigurasi Anda

188 188

189Mulai Claude Code dan jalankan `/status` untuk mengonfirmasi pengaturan. Baris `API provider` menampilkan `Google Vertex AI`, dan baris `GCP project`, `Default region`, dan `Model` menampilkan ID proyek, wilayah, dan model yang diselesaikan Anda. Jika baris penyedia hilang, variabel lingkungan tidak mencapai proses. Konfirmasi bahwa variabel tersebut diekspor di shell tempat Anda meluncurkan `claude`, atau atur di blok `env` dari [file pengaturan](https://code.claude.com/docs/id/settings.md) Anda.189Jalankan Claude Code dan jalankan `/status` untuk mengonfirmasi penyiapan. Baris `API provider` menampilkan `Google Vertex AI`, dan baris `GCP project`, `Default region`, dan `Model` menampilkan ID proyek, region, dan model yang telah di-resolve. Jika baris provider tidak ada, environment variable tidak mencapai proses tersebut. Pastikan variabel tersebut di-export di shell tempat Anda menjalankan `claude`, atau atur variabel tersebut di blok `env` pada [file pengaturan](https://code.claude.com/docs/id/settings.md) Anda.

190 190

191## Pemeriksaan model startup191## Pemeriksaan model startup

192 192

google-vertex-ai.md 2026-11-10 21:57 UTC to 2026-11-11 22:59 UTC

Claude Code di Platform Agen Google Cloud

Prasyarat

Masuk dengan Agent Platform

Konfigurasi wilayah

Menyiapkan secara manual

Aktifkan Agent Platform API

Minta akses model

Konfigurasikan kredensial GCP

Konfigurasi kredensial lanjutan

Konfigurasikan Claude Code

Sematkan versi model

Verifikasi konfigurasi Anda

Pemeriksaan model startup

Memulai sesi pada model tertentu

Penolakan model yang diingat

Ketika organisasi Anda memberlakukan allowlist model

Ketika model dinonaktifkan di tengah sesi

Konfigurasi IAM

Jendela konteks token 1M

Pemecahan masalah

Sumber daya tambahan