Claude Code trên Google Cloud's Agent Platform (Vertex AI)

Google Cloud’s Agent Platform (tên cũ là Vertex AI) là một trong các provider bên thứ ba mà Claude Code hỗ trợ. Trang này hướng dẫn thiết lập, cấu hình IAM, và các lỗi thường gặp.

Yêu cầu trước khi bắt đầu

• Tài khoản Google Cloud Platform (GCP) đã bật billing.
• Project GCP đã bật Agent Platform API.
• Quyền truy cập vào các model Claude mong muốn (ví dụ Claude Sonnet 4.6).
• Google Cloud SDK (gcloud) đã cài đặt và cấu hình.
• Quota đủ dùng ở region GCP mong muốn.

Nếu bạn dùng credentials Google Cloud cá nhân, làm theo mục Đăng nhập với Agent Platform bên dưới. Khi triển khai cho cả team, dùng thiết lập thủ công và pin phiên bản model trước khi rollout.

Đăng nhập với Agent Platform

Nếu bạn đã có credentials Google Cloud, wizard đăng nhập sẽ dẫn bạn qua toàn bộ quá trình:

1. Bật Claude models trong project GCP: bật Agent Platform API, sau đó yêu cầu quyền truy cập các model Claude bạn muốn trong Model Garden. Xem cấu hình IAM cho quyền cần thiết.
2. Chạy Claude Code và chọn Google Cloud’s Agent Platform: chạy claude, ở màn hình đăng nhập chọn 3rd-party platform → Google Vertex AI (label này vẫn giữ tên cũ). Nếu đã đăng nhập, chạy /login để mở lại menu này.
3. Làm theo wizard: chọn cách xác thực với Google Cloud (Application Default Credentials từ gcloud, file service account key, hoặc credentials có sẵn trong môi trường). Wizard tự phát hiện project và region, kiểm tra model nào project bạn gọi được, và cho phép pin chúng. Kết quả được lưu vào block env trong user settings file, nên bạn không cần tự export biến môi trường.

Sau khi đăng nhập, chạy /setup-vertex bất kỳ lúc nào để mở lại wizard và đổi credentials, project, region, hoặc model pin. Wizard ghi vào ~/.claude/settings.json, hoặc $CLAUDE_CONFIG_DIR/settings.json nếu bạn đặt CLAUDE_CONFIG_DIR.

Cấu hình region

Claude Code hỗ trợ endpoint dạng global, multi-region, và regional của Agent Platform. Đặt CLOUD_ML_REGION thành global, một multi-region location như eu/us, hoặc một region cụ thể như us-east5. Claude Code tự chọn hostname phù hợp cho từng dạng.

Ghi chú

Không phải model nào cũng khả dụng trên mọi loại endpoint - kiểm tra danh sách region hỗ trợ trước khi chọn.

Thiết lập thủ công

Dùng cho CI hoặc rollout theo script, thay vì wizard.

1. Bật Agent Platform API

gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com

2. Yêu cầu quyền truy cập model

Vào Model Garden, tìm “Claude”, yêu cầu quyền truy cập model mong muốn, và chờ duyệt (có thể mất 24-48 giờ).

3. Cấu hình credentials GCP

Claude Code dùng xác thực Google Cloud tiêu chuẩn. Từ v2.1.121, Claude Code hỗ trợ Workload Identity Federation bằng chứng chỉ X.509 qua cùng chuỗi Application Default Credentials - đặt GOOGLE_APPLICATION_CREDENTIALS trỏ tới file cấu hình credential.

Ghi chú

Claude Code dùng ANTHROPIC_VERTEX_PROJECT_ID làm project ID cho request tới Agent Platform. Biến GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, hoặc file credential trỏ bởi GOOGLE_APPLICATION_CREDENTIALS có độ ưu tiên cao hơn. Nếu không đặt gì, project ID được suy ra từ cấu hình gcloud hoặc service account đính kèm.

Advanced credential configuration: Claude Code hỗ trợ tự động refresh credential GCP qua setting gcpAuthRefresh trong file settings. Khi Claude Code phát hiện credential hết hạn, nó chạy lệnh cấu hình để lấy credential mới trước khi thử lại:

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

Claude Code hiển thị output của lệnh nhưng không thể gửi input tương tác - phù hợp với flow xác thực qua trình duyệt (hiện URL, bạn hoàn tất trong trình duyệt). Lệnh refresh timeout sau 3 phút nếu chưa xác thực xong.

4. Cấu hình Claude Code

# Bật tích hợp Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Tùy chọn: override endpoint URL cho custom endpoint hoặc gateway
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Tùy chọn: tắt prompt caching
# export DISABLE_PROMPT_CACHING=1

# Tùy chọn: yêu cầu TTL cache 1 giờ thay vì mặc định 5 phút
# export ENABLE_PROMPT_CACHING_1H=1

# Khi CLOUD_ML_REGION=global, override region cho model không hỗ trợ global endpoint
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

Prompt caching được bật tự động (tắt bằng DISABLE_PROMPT_CACHING=1, TTL 1 giờ với ENABLE_PROMPT_CACHING_1H=1, tính phí cao hơn cho cache write). Khi dùng Agent Platform, lệnh /logout không khả dụng vì xác thực do Google Cloud credentials quản lý.

Claude Code tắt mặc định MCP tool search trên Agent Platform để tool định nghĩa MCP load sẵn từ đầu. Agent Platform hỗ trợ tool search cho Claude Sonnet 4.5+ và Opus 4.5+ - bật bằng ENABLE_TOOL_SEARCH=true. Model đời cũ không nhận beta header cần thiết nên sẽ lỗi nếu bật.

5. Pin phiên bản model

Chú ý

Luôn pin phiên bản model cụ thể khi triển khai cho nhiều người dùng. Không pin, các alias như sonnet/opus sẽ trỏ tới default tích hợp sẵn của Claude Code cho Agent Platform, có thể chậm hơn bản mới nhất và chưa chắc được bật trong project của bạn.

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 mặc định khi không pin gì:

Loại model	Giá trị mặc định
Primary model	claude-opus-5
Small/fast model	claude-sonnet-4-5@20250929

Các tác vụ nền (như đặt tiêu đề session) dùng model small/fast, thường là Haiku. Trên Agent Platform, Claude Code dùng model Sonnet mặc định cho tác vụ nền vì Haiku có thể chưa được bật ở mọi project/region. Để dùng Haiku cho tác vụ nền, đặt ANTHROPIC_DEFAULT_HAIKU_MODEL thành model ID khả dụng trong project bạn.

Chú ý

Model Opus có giá theo token cao hơn Sonnet, nên một deployment không pin primary model sẽ bị tính phí theo mức Opus khi cập nhật lên v2.1.207 trở lên. Kiểm tra kỹ chi phí trước khi rollout.

6. Xác minh cấu hình

Chạy /status - dòng API provider hiển thị Google Vertex AI, cùng GCP project, Default region, và Model.

Kiểm tra model lúc khởi động

Khi khởi động với Agent Platform, Claude Code kiểm tra các model dự định dùng có truy cập được không. Nếu bạn pin một phiên bản cũ hơn default hiện tại và project của bạn gọi được bản mới, Claude Code sẽ hỏi có muốn cập nhật pin không. Nếu chưa pin và default hiện không khả dụng, Claude Code fallback về phiên bản cũ hơn cho phiên làm việc hiện tại (không lưu lại).

Cấu hình IAM

Role roles/aiplatform.user bao gồm quyền cần thiết (aiplatform.endpoints.predict). Để hạn chế hơn, tạo custom role chỉ với quyền này.

Mẹo

Nên tạo một project GCP riêng cho Claude Code để đơn giản hóa theo dõi chi phí và kiểm soát truy cập.

Cửa sổ ngữ cảnh 1M token

Claude Sonnet 5, Opus 4.6 trở lên, và Sonnet 4.6 hỗ trợ cửa sổ ngữ cảnh 1M token trên Agent Platform. Sonnet 5 luôn chạy với cửa sổ 1M, không có variant [1m] để chọn. Với các model khác, thêm [1m] vào model ID khi pin thủ công để bật cửa sổ mở rộng.

Xử lý sự cố

Lỗi “Could not load the default credentials”: chạy gcloud auth application-default login, hoặc đặt GOOGLE_APPLICATION_CREDENTIALS trỏ tới service account key.

Lỗi quota: kiểm tra hoặc yêu cầu tăng quota qua Cloud Console.

Lỗi 404 “model not found”: xác nhận model đã Enabled trong Model Garden, và khả dụng ở location bạn chỉ định (một số model chỉ có ở global hoặc multi-region).

Lỗi 429: với regional endpoint, đảm bảo model primary và small/fast được hỗ trợ ở region đã chọn, hoặc chuyển sang CLOUD_ML_REGION=global.

Nguồn

Dịch và biên soạn từ Claude Code on Google Cloud’s Agent Platform.