​
Предварительные требования

Перед настройкой Claude Code с Vertex AI убедитесь, что у вас есть:
  • Учетная запись Google Cloud Platform (GCP) с включенной биллингом
  • Проект GCP с включенным API Vertex AI
  • Доступ к желаемым моделям Claude (например, Claude Sonnet 4.5)
  • Установленный и настроенный Google Cloud SDK (gcloud)
  • Квота, выделенная в желаемом регионе GCP

​
Конфигурация региона

Claude Code можно использовать как с глобальными, так и с региональными конечными точками Vertex AI.
Vertex AI может не поддерживать модели Claude Code по умолчанию во всех регионах. Вам может потребоваться переключиться на поддерживаемый регион или модель.
Vertex AI может не поддерживать модели Claude Code по умолчанию на глобальных конечных точках. Вам может потребоваться переключиться на региональную конечную точку или поддерживаемую модель.

​
Установка

​
1. Включите API Vertex AI

Включите API Vertex AI в вашем проекте GCP: 
# Установите ID вашего проекта
gcloud config set project YOUR-PROJECT-ID

# Включите API Vertex AI
gcloud services enable aiplatform.googleapis.com

​
2. Запросите доступ к модели

Запросите доступ к моделям Claude в Vertex AI:
  1. Перейдите в Vertex AI Model Garden
  2. Найдите модели “Claude”
  3. Запросите доступ к желаемым моделям Claude (например, Claude Sonnet 4.5)
  4. Дождитесь одобрения (может занять 24-48 часов)

​
3. Настройте учетные данные GCP

Claude Code использует стандартную аутентификацию Google Cloud. Для получения дополнительной информации см. документацию по аутентификации Google Cloud.
При аутентификации Claude Code автоматически будет использовать ID проекта из переменной окружения ANTHROPIC_VERTEX_PROJECT_ID. Чтобы переопределить это, установите одну из этих переменных окружения: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT или GOOGLE_APPLICATION_CREDENTIALS.

​
4. Настройте Claude Code

Установите следующие переменные окружения: 
# Включите интеграцию Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Опционально: отключите кэширование подсказок, если необходимо
export DISABLE_PROMPT_CACHING=1

# Когда CLOUD_ML_REGION=global, переопределите регион для неподдерживаемых моделей
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Опционально: переопределите регионы для других конкретных моделей
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
Кэширование подсказок автоматически поддерживается при указании флага cache_control ephemeral. Чтобы отключить его, установите DISABLE_PROMPT_CACHING=1. Для повышенных ограничений скорости обратитесь в службу поддержки Google Cloud.
При использовании Vertex AI команды /login и /logout отключены, так как аутентификация обрабатывается через учетные данные Google Cloud.

​
5. Конфигурация модели

Claude Code использует эти модели по умолчанию для Vertex AI:
Тип моделиЗначение по умолчанию
Основная модельclaude-sonnet-4-5@20250929
Малая/быстрая модельclaude-haiku-4-5@20251001
Для пользователей Vertex AI Claude Code не будет автоматически обновляться с Haiku 3.5 на Haiku 4.5. Чтобы вручную переключиться на более новую модель Haiku, установите переменную окружения ANTHROPIC_DEFAULT_HAIKU_MODEL на полное имя модели (например, claude-haiku-4-5@20251001).
Для настройки моделей: 
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
Конфигурация IAM

Назначьте требуемые разрешения IAM: Роль roles/aiplatform.user включает требуемые разрешения:
  • aiplatform.endpoints.predict - требуется для вызова модели и подсчета токенов
Для более ограничивающих разрешений создайте пользовательскую роль только с указанными выше разрешениями. Для получения подробной информации см. документацию Vertex IAM.
Мы рекомендуем создать выделенный проект GCP для Claude Code, чтобы упростить отслеживание затрат и управление доступом.

​
Контекстное окно из 1 млн токенов

Claude Sonnet 4 и Sonnet 4.5 поддерживают контекстное окно из 1 млн токенов на Vertex AI.
Контекстное окно из 1 млн токенов в настоящее время находится в бета-версии. Чтобы использовать расширенное контекстное окно, включите заголовок бета-версии context-1m-2025-08-07 в ваши запросы Vertex AI.

​
Устранение неполадок

Если у вас возникают проблемы с квотой:
  • Проверьте текущие квоты или запросите увеличение квоты через Cloud Console
Если вы получаете ошибки “модель не найдена” 404:
  • Подтвердите, что модель включена в Model Garden
  • Проверьте, что у вас есть доступ к указанному региону
  • Если используется CLOUD_ML_REGION=global, проверьте, что ваши модели поддерживают глобальные конечные точки в Model Garden в разделе “Поддерживаемые функции”. Для моделей, которые не поддерживают глобальные конечные точки, либо:
    • Укажите поддерживаемую модель через ANTHROPIC_MODEL или ANTHROPIC_SMALL_FAST_MODEL, либо
    • Установите региональную конечную точку, используя переменные окружения VERTEX_REGION_<MODEL_NAME>
Если вы получаете ошибки 429:
  • Для региональных конечных точек убедитесь, что основная модель и малая/быстрая модель поддерживаются в выбранном регионе
  • Рассмотрите возможность переключения на CLOUD_ML_REGION=global для лучшей доступности

​
Дополнительные ресурсы