Если у вас есть учетные данные Google Cloud и вы хотите начать использовать Claude Code через Vertex AI, мастер входа проведет вас через этот процесс. Вы выполняете предварительные требования на стороне GCP один раз для каждого проекта; мастер обрабатывает сторону Claude Code.
Запустите claude. В приглашении входа выберите 3rd-party platform, затем Google Vertex AI.
3
Следуйте подсказкам мастера
Выберите способ аутентификации в Google Cloud: Application Default Credentials из gcloud, файл ключа сервисного аккаунта или учетные данные, уже находящиеся в вашей среде. Мастер обнаруживает ваш проект и регион, проверяет, какие модели Claude может вызывать ваш проект, и позволяет вам их закрепить. Результат сохраняется в блок env вашего файла пользовательских настроек, поэтому вам не нужно самостоятельно экспортировать переменные окружения.
После входа запустите /setup-vertex в любое время, чтобы снова открыть мастер и изменить учетные данные, проект, регион или закрепления моделей.
Конфигурация региона
Claude Code поддерживает Vertex AI глобальные, многорегиональные и региональные конечные точки. Установите CLOUD_ML_REGION на global, многорегиональное местоположение, такое как eu или us, или конкретный регион, такой как us-east5. Claude Code выбирает правильное имя хоста Vertex AI для каждой формы, включая хосты aiplatform.eu.rep.googleapis.com и aiplatform.us.rep.googleapis.com для многорегиональных местоположений.
Ручная установка
Чтобы настроить Vertex AI через переменные окружения вместо мастера, например в CI или при развертывании в масштабах предприятия, следуйте приведенным ниже шагам.
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
Claude Code версии 2.1.121 или позже поддерживает Федерацию рабочих нагрузок на основе сертификатов X.509 через ту же цепочку Application Default Credentials. Установите GOOGLE_APPLICATION_CREDENTIALS на путь к файлу конфигурации учетных данных.
Расширенная конфигурация учетных данных
Claude Code поддерживает автоматическое обновление учетных данных GCP через параметр gcpAuthRefresh. Когда Claude Code обнаруживает, что ваши учетные данные GCP истекли или не могут быть загружены, он запускает настроенную команду для получения новых учетных данных перед повторной попыткой запроса.
Вывод команды отображается пользователю, но интерактивный ввод не поддерживается. Это хорошо работает для потоков аутентификации на основе браузера, где CLI показывает URL, и вы завершаете аутентификацию в браузере. Команда обновления истекает через три минуты, если аутентификация не завершена. Если вы установите gcpAuthRefresh в параметрах проекта, таких как .claude/settings.json, команда запускается только после того, как вы примете приглашение доверия рабочей области.
4. Настройте Claude Code
Установите следующие переменные окружения:
# Включите интеграцию Vertex AIexport CLAUDE_CODE_USE_VERTEX=1export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID# Опционально: переопределите URL конечной точки Vertex для пользовательских конечных точек или шлюзов# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com# Опционально: отключите кэширование запросов, если необходимоexport DISABLE_PROMPT_CACHING=1# Опционально: запросите TTL кэша запросов на 1 час вместо стандартного 5-минутногоexport ENABLE_PROMPT_CACHING_1H=1# Когда CLOUD_ML_REGION=global, переопределите регион для моделей, которые не поддерживают глобальные конечные точкиexport VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
Большинство версий моделей имеют соответствующую переменную VERTEX_REGION_CLAUDE_*. Полный список см. в справочнике переменных окружения. Проверьте Vertex Model Garden, чтобы определить, какие модели поддерживают глобальные конечные точки в сравнении с региональными только.
Кэширование запросов включается автоматически. Чтобы отключить его, установите DISABLE_PROMPT_CACHING=1. Чтобы запросить TTL кэша на 1 час вместо стандартного 5-минутного, установите ENABLE_PROMPT_CACHING_1H=1; записи кэша с TTL на 1 час тарифицируются по более высокому тарифу. Для повышенных лимитов скорости обратитесь в поддержку Google Cloud. При использовании Vertex AI команда /logout недоступна, так как аутентификация обрабатывается через учетные данные Google Cloud.
Claude Code отключает поиск инструментов MCP по умолчанию на Vertex AI, поэтому определения инструментов MCP загружаются заранее. Vertex AI поддерживает поиск инструментов для Claude Sonnet 4.5 и позже, а также Claude Opus 4.5 и позже. Установите ENABLE_TOOL_SEARCH=true, чтобы включить его на этих моделях. Более ранние модели на Vertex AI не принимают требуемый бета-заголовок, и запросы не выполняются, если вы включите поиск инструментов с ними.
5. Закрепите версии моделей
Установите эти переменные окружения на конкретные ID моделей Vertex AI.
Без ANTHROPIC_DEFAULT_OPUS_MODEL псевдоним opus на Vertex разрешается в Opus 4.6. Установите его на ID Opus 4.8, чтобы использовать последнюю модель:
Claude Code использует эти модели по умолчанию, когда переменные закрепления не установлены:
Тип модели
Значение по умолчанию
Основная модель
claude-sonnet-4-5@20250929
Малая/быстрая модель
То же, что и основная модель
Фоновые задачи, такие как генерация названия сеанса, используют малую/быструю модель, обычно модель класса Haiku. На Vertex AI Claude Code по умолчанию использует основную модель, потому что Haiku может быть не включен в каждом проекте или регионе. Чтобы использовать Haiku для фоновых задач, установите ANTHROPIC_DEFAULT_HAIKU_MODEL на ID модели, который доступен в вашем проекте.
Когда Claude Code запускается с настроенным Vertex AI, он проверяет, что модели, которые он намеревается использовать, доступны в вашем проекте. Эта проверка требует Claude Code v2.1.98 или более поздней версии.
Если вы закрепили версию модели, которая старше текущего значения по умолчанию Claude Code, и ваш проект может вызывать более новую версию, Claude Code предлагает вам обновить закрепление. Принятие записывает новый ID модели в ваш файл пользовательских настроек и перезапускает Claude Code. Отклонение запоминается до следующего изменения версии по умолчанию.
Если вы не закрепили модель и текущее значение по умолчанию недоступно в вашем проекте, Claude Code откатывается на предыдущую версию для текущего сеанса и показывает уведомление. Откат не сохраняется. Включите более новую модель в Model Garden или закрепите версию, чтобы сделать выбор постоянным.
Конфигурация IAM
Назначьте требуемые разрешения IAM:
Роль roles/aiplatform.user включает требуемые разрешения:
aiplatform.endpoints.predict - требуется для вызова модели и подсчета токенов
Для более строгих разрешений создайте пользовательскую роль только с указанными выше разрешениями.
Claude Sonnet 5, Opus 4.6 и более поздние версии, а также Sonnet 4.6 поддерживают контекстное окно с 1M токенов на Vertex AI. Sonnet 5 всегда работает с окном 1M, без варианта [1m] для выбора. Для других моделей Claude Code автоматически включает расширенное контекстное окно при выборе варианта модели с 1M.
Проверьте, что модель доступна в указанном вами местоположении. Некоторые модели предлагаются только на global или многорегиональных местоположениях, таких как eu и us, а не в конкретных регионах
Если вы используете CLOUD_ML_REGION=global, проверьте, что ваши модели поддерживают глобальные конечные точки в Model Garden в разделе "Supported features". Для моделей, которые не поддерживают глобальные конечные точки, либо:
Укажите поддерживаемую модель через ANTHROPIC_MODEL или ANTHROPIC_DEFAULT_HAIKU_MODEL, либо
Установите регион или многорегиональное местоположение, используя переменные окружения VERTEX_REGION_<MODEL_NAME>
Если вы столкнулись с ошибками 429:
Для региональных конечных точек убедитесь, что основная модель и малая/быстрая модель поддерживаются в выбранном регионе
Рассмотрите возможность переключения на CLOUD_ML_REGION=global для лучшей доступности
290 Контекстное окно с 1M токенов290 Контекстное окно с 1M токенов
291</h2>291</h2>
292292
293Claude Opus 4.6 и более поздние версии, а также Sonnet 4.6, поддерживают [контекстное окно с 1M токенов](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) на Vertex AI. Claude Code автоматически включает расширенное контекстное окно при выборе варианта модели с 1M.293Claude Sonnet 5, Opus 4.6 и более поздние версии, а также Sonnet 4.6 поддерживают [контекстное окно с 1M токенов](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) на Vertex AI. Sonnet 5 всегда работает с окном 1M, без варианта `[1m]` для выбора. Для других моделей Claude Code автоматически включает расширенное контекстное окно при выборе варианта модели с 1M.
294294
295[Мастер установки](#sign-in-with-vertex-ai) предлагает опцию контекстного окна с 1M при закреплении моделей. Чтобы включить его для вручную закрепленной модели, добавьте `[1m]` к ID модели. Подробности см. в разделе [Закрепите модели для развертываний третьих сторон](/ru/model-config#pin-models-for-third-party-deployments).295[Мастер установки](#sign-in-with-vertex-ai) предлагает опцию контекстного окна с 1M при закреплении моделей. Чтобы включить его для вручную закрепленной модели, добавьте `[1m]` к ID модели. Подробности см. в разделе [Закрепите модели для развертываний третьих сторон](/ru/model-config#pin-models-for-third-party-deployments).
