Google Cloud 的 Agent Platform 上的 Claude Code

先決條件

• 已啟用計費的 Google Cloud Platform (GCP) 帳戶
• 已啟用 Google Cloud 的 Agent Platform API 的 GCP 專案
• 存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
• 已安裝並設定 Google Cloud SDK (gcloud)
• 在所需的 GCP 區域中分配的配額

使用 Agent Platform 登入

區域設定

手動設定

1. 啟用 Agent Platform API

# 設定您的專案 ID
gcloud config set project YOUR-PROJECT-ID

# 啟用 Agent Platform API
gcloud services enable aiplatform.googleapis.com

2. 要求模型存取權

1. 前往 Google Cloud 的 Agent Platform Model Garden
2. 搜尋「Claude」模型
3. 要求存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
4. 等待核准（可能需要 24-48 小時）

3. 設定 GCP 認證

進階認證設定

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

4. 設定 Claude Code

# 啟用 Agent Platform 整合
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 選用：覆寫 Agent Platform 端點 URL 以用於自訂端點或閘道
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 當 CLOUD_ML_REGION=global 時，覆寫不支援全域端點的模型的區域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

• VERTEX_REGION_CLAUDE_*：Claude Code 回退到 CLOUD_ML_REGION。
• CLOUD_ML_REGION：Claude Code 回退到 us-east5。

• Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新版本：Claude Code 預設啟用工具搜尋。
• 較早的模型：Claude Code 預先載入 MCP 工具定義，因為其 Agent Platform 服務堆疊拒絕所需的 beta 標頭。設定 ENABLE_TOOL_SEARCH=true 不會覆寫此設定。

5. 釘選模型版本

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'

• 當您使用 --model、ANTHROPIC_MODEL 或 model 設定選擇主要模型時，背景工作會使用該模型。當 Claude Code 在您使用 ANTHROPIC_DEFAULT_MODEL 設定的模型上啟動工作階段時，背景工作也會使用該模型。設定 ANTHROPIC_DEFAULT_OPUS_MODEL 而不設定 ANTHROPIC_DEFAULT_SONNET_MODEL 也會計為選擇，因為內建 Sonnet 模型可能未在引導其自身 Opus 的專案中啟用。
• 若要針對背景工作使用 Haiku，請將 ANTHROPIC_DEFAULT_HAIKU_MODEL 設定為您的專案中可用的模型 ID。

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

6. 驗證您的設定

啟動模型檢查

• 如果您接受：Claude Code 會將新模型 ID 寫入您的使用者設定檔並重新啟動
• 如果您拒絕：Claude Code 會記住您的選擇，直到下一次預設版本變更

在特定模型上啟動工作階段

記住的模型拒絕

當您的組織強制執行模型允許清單時

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

當模型在工作階段中被停用時

• 您的工作階段使用的是固定模型或您選擇的特定版本
• Claude Code 嘗試的模型都無法使用。在自動模式中，Claude Code 只會切換到 Agent Platform 上自動模式支援的模型。

IAM 設定

• aiplatform.endpoints.predict - 模型呼叫和權杖計數所需

1M token context window

故障排除

• 執行 gcloud auth application-default login 以設定應用程式預設認證
• 將 GOOGLE_APPLICATION_CREDENTIALS 設定為服務帳戶金鑰檔案路徑
• 請參閱 設定 GCP 認證 以了解所有選項

• 透過 Cloud Console 檢查目前配額或要求增加配額

• 確認模型在 Model Garden 中已啟用
• 驗證模型在您指定的位置中可用。某些模型僅在 global 或多區域位置（例如 eu 和 us）上提供，不在特定區域中
• 如果使用 CLOUD_ML_REGION=global，請檢查您的模型是否在 Model Garden 中的「支援的功能」下支援全球端點。對於不支援全球端點的模型，請執行下列其中一項：
  • 透過 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定支援的模型，或
  • 使用該模型的 VERTEX_REGION_CLAUDE_* 變數設定區域或多區域位置，這些變數列於環境變數參考中

• 對於區域端點，請確保主要模型和小型/快速模型在您選擇的區域中受支援
• 考慮切換到 CLOUD_ML_REGION=global 以獲得更好的可用性

其他資源

• Google Cloud 的 Agent Platform 文件
• Google Cloud 的 Agent Platform 定價
• Google Cloud 的 Agent Platform 配額和限制