На этой странице описан один из двух способов использования Claude через ваш проект Google Cloud: Google Cloud’s Agent Platform, ранее известная как Vertex AI, которой управляет Google. Если вы используете Claude Models on Google Cloud (под управлением Anthropic), вместо этого следуйте её странице настройки Claude Code. Чтобы узнать, какой из вариантов вы используете, см. Which offering are you using?
Предварительные требования
Перед настройкой Claude Code с Google Cloud’s Agent Platform, ранее известной как Vertex AI, убедитесь, что у вас есть:- Учетная запись Google Cloud Platform (GCP) с включенной биллингом
- Проект GCP с включенным API Google Cloud’s Agent Platform
- Доступ к нужным моделям Claude (например, Claude Sonnet 4.6)
- Установленный и настроенный Google Cloud SDK (
gcloud) - Квота, выделенная в нужном регионе GCP
Вход с Agent Platform
Если у вас есть учетные данные Google Cloud и вы хотите начать использовать Claude Code через Agent Platform Google Cloud, мастер входа проведет вас через этот процесс. Вы выполняете предварительные требования на стороне GCP один раз для каждого проекта; мастер обрабатывает сторону Claude Code.1
Включите модели Claude в вашем проекте GCP
Включите API Agent Platform Google Cloud для вашего проекта, затем запросите доступ к моделям Claude, которые вам нужны, в Model Garden Agent Platform Google Cloud. См. Конфигурация IAM для разрешений, которые требуются вашей учетной записи.
2
Запустите Claude Code и выберите Agent Platform Google Cloud
Запустите
claude. В приглашении входа выберите 3rd-party platform, затем Google Vertex AI, метку, которую мастер входа все еще использует для Agent Platform Google Cloud. Если вы уже вошли, запустите /login для открытия того же меню.3
Следуйте подсказкам мастера
Выберите способ аутентификации в Google Cloud: Application Default Credentials из
gcloud, файл ключа сервисного аккаунта или учетные данные, уже находящиеся в вашей среде. Мастер обнаруживает ваш проект и регион, проверяет, какие модели Claude может вызывать ваш проект, и позволяет вам их закрепить. Результат сохраняется в блок env вашего файла пользовательских настроек, поэтому вам не нужно самостоятельно экспортировать переменные окружения./setup-vertex в любое время, чтобы снова открыть мастер и изменить учетные данные, проект, регион или закрепления моделей. Шаг закрепления модели начинается с ваших текущих закрепленных моделей. Мастер записывает данные в ~/.claude/settings.json или в $CLAUDE_CONFIG_DIR/settings.json, когда установлена переменная CLAUDE_CONFIG_DIR.
Конфигурация региона
Claude Code поддерживает Google Cloud’s Agent Platform глобальные, многорегиональные и региональные конечные точки. УстановитеCLOUD_ML_REGION на global, многорегиональное местоположение, такое как eu или us, или конкретный регион, такой как us-east5. Claude Code выбирает правильное имя хоста Google Cloud’s Agent Platform для каждой формы, включая хосты aiplatform.eu.rep.googleapis.com и aiplatform.us.rep.googleapis.com для многорегиональных местоположений.
Google Cloud’s Agent Platform может не поддерживать модели Claude Code по умолчанию на каждом типе конечной точки. Доступность моделей варьируется в зависимости от конкретных регионов, многорегиональных местоположений и глобальных конечных точек. Вам может потребоваться переключиться на поддерживаемое местоположение или указать поддерживаемую модель.
Ручная установка
Чтобы настроить Google Cloud’s Agent Platform через переменные окружения вместо мастера, например в CI или при развертывании в масштабах предприятия, следуйте приведенным ниже шагам.
- Включите API Agent Platform
Включите API Agent Platform Google Cloud в вашем проекте GCP. Замените YOUR-PROJECT-ID на ID вашего проекта GCP здесь и на этапе конфигурации ниже:
- Запросите доступ к модели
Запросите доступ к моделям Claude в Google Cloud’s Agent Platform:
- Перейдите в Google Cloud’s Agent Platform Model Garden
- Найдите модели “Claude”
- Запросите доступ к нужным моделям Claude (например, Claude Sonnet 4.6)
- Дождитесь одобрения (может занять 24-48 часов)
- Настройте учетные данные GCP
Claude Code использует стандартную аутентификацию Google Cloud.
Для получения дополнительной информации см. документацию по аутентификации Google Cloud.
Claude Code поддерживает Федерацию рабочих нагрузок на основе сертификатов X.509 через ту же цепочку Application Default Credentials. Установите GOOGLE_APPLICATION_CREDENTIALS на путь к файлу конфигурации учетных данных.
Claude Code адресует запросы Google Cloud’s Agent Platform проекту в
ANTHROPIC_VERTEX_PROJECT_ID, даже если GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT или файл учетных данных, на который ссылается GOOGLE_APPLICATION_CREDENTIALS, содержит другой проект.Расширенная конфигурация учетных данных
Claude Code поддерживает автоматическое обновление учетных данных GCP через параметрgcpAuthRefresh. Добавьте его в файл параметров Claude Code, например ~/.claude/settings.json. Когда Claude Code обнаруживает, что ваши учетные данные GCP истекли или не могут быть загружены, он запускает настроенную команду для получения новых учетных данных перед повторной попыткой запроса.
gcpAuthRefresh в параметрах проекта, таких как .claude/settings.json, Claude Code запускает его в соответствии с тем же правилом доверия рабочей области, что и hooks в файлах параметров, которое включает сеансы -p в папках, которым вы никогда не доверяли.
- Настройте Claude Code
Установите следующие переменные окружения:
VERTEX_REGION_CLAUDE_*. Полный список см. в справочнике переменных окружения. Проверьте Google Cloud’s Agent Platform Model Garden, чтобы определить, какие модели поддерживают глобальные эндпоинты, а какие только региональные.
Если значение региона не похоже на имя региона или местоположения, Claude Code рассматривает его как неустановленное. Например, Claude Code рассматривает значение, содержащее косую черту, точку или пробел, как неустановленное. Claude Code откатывается на другой источник для каждой переменной:
VERTEX_REGION_CLAUDE_*: Claude Code откатывается наCLOUD_ML_REGION.CLOUD_ML_REGION: Claude Code откатывается наus-east5.
DISABLE_PROMPT_CACHING=1. Чтобы запросить TTL кэша на 1 час вместо стандартного 5-минутного, установите ENABLE_PROMPT_CACHING_1H=1; записи кэша с TTL на 1 час тарифицируются по более высокому тарифу. Чтобы установить разные TTL для вашего основного разговора и для запросов, которые Claude Code делает вне его, выберите TTL самостоятельно.
Чтобы повысить ваши лимиты скорости, обратитесь в поддержку Google Cloud. При использовании Google Cloud’s Agent Platform команда /logout недоступна, так как аутентификация обрабатывается через учетные данные Google Cloud.
Claude Code выбирает между поиском инструментов MCP и предварительной загрузкой по поколению модели:
- Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 и позже: Claude Code включает поиск инструментов по умолчанию.
- Более ранние модели: Claude Code загружает определения инструментов MCP заранее, потому что их стеки обслуживания Agent Platform отклоняют требуемый бета-заголовок. Установка
ENABLE_TOOL_SEARCH=trueне переопределяет это.
ENABLE_TOOL_SEARCH=false, чтобы отключить поиск инструментов на каждой модели.
- Закрепите версии моделей
Установите эти переменные окружения на конкретные ID моделей Google Cloud’s Agent Platform.
Без ANTHROPIC_DEFAULT_OPUS_MODEL псевдоним opus на Google Cloud’s Agent Platform разрешается в Opus 5.5, а без ANTHROPIC_DEFAULT_SONNET_MODEL псевдоним sonnet разрешается в Sonnet 4.5. Этот пример закрепляет каждый псевдоним на конкретную версию:
До версии 2.1.280 основная модель на Google Cloud’s Agent Platform по умолчанию была Opus 5, и псевдоним
opus разрешался в Opus 5 с версии 2.1.219.
Фоновые задачи, такие как генерация названия сеанса, используют малую/быструю модель, обычно модель класса Haiku. На Google Cloud’s Agent Platform Claude Code использует модель Sonnet по умолчанию для фоновых задач, потому что Haiku может быть не включен в каждом проекте или регионе. Два выбора изменяют, какая модель их выполняет:
- Когда вы выбираете основную модель с помощью
--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 модели, который доступен в вашем проекте.
- Проверьте вашу конфигурацию
Запустите Claude Code и выполните /status, чтобы подтвердить установку. Строка API provider показывает Google Vertex AI, а строки GCP project, Default region и Model показывают ID вашего проекта, регион и разрешенную модель. Если строка provider отсутствует, переменные окружения не достигают процесса. Подтвердите, что они экспортированы в оболочке, где вы запустили claude, или установите их в блоке env вашего файла параметров.
Проверки моделей при запуске
Когда Claude Code запускается с настроенной Agent Platform от Google Cloud, он проверяет, доступны ли в вашем проекте модели, которые он собирается использовать. Возможно, вы закрепили версию модели, которая старше текущей версии по умолчанию в Claude Code. Если ваш проект может вызывать более новую версию, Claude Code предложит обновить закреплённую версию:- Если вы согласитесь: Claude Code запишет новый идентификатор модели в ваш файл пользовательских настроек и перезапустится
- Если вы откажетесь: Claude Code запомнит ваш выбор до следующей смены версии по умолчанию
env управляемых настроек Claude Code не выполняет проверку и не предлагает обновление. Если предложение обновления всё равно появляется для этой закреплённой версии, обновите Claude Code до версии 2.1.314 или новее. До версии 2.1.314 управляемая закреплённая версия оставалась в силе после вашего согласия, поэтому предложение появлялось снова при следующем запуске.
Если вы не закрепили модель и текущая модель по умолчанию недоступна в вашем проекте, Claude Code использует резервный вариант для текущей сессии и показывает уведомление. Сначала он пробует более ранние версии модели по умолчанию, а если модель по умолчанию относится к Opus и ни одна версия Opus не доступна, переключается на модель Sonnet по умолчанию. Резервный вариант не сохраняется. Включите более новую модель в Model Garden или закрепите версию, чтобы сделать выбор постоянным.
Запуск сессии на конкретной модели
Когда вы запускаете сессию на конкретной версии Sonnet или Opus, например с помощью--model, ANTHROPIC_MODEL или настройки model, эта версия выступает закреплённой моделью по умолчанию для сессии для соответствующего псевдонима sonnet или opus. Claude Code пропускает проверку доступности встроенной модели по умолчанию, которую заменяет ваша модель, и запускается на настроенной вами модели без уведомления о резервном варианте.
Когда вы запускаете сессию на псевдониме модели, например opus, или на идентификаторе модели, который Claude Code не распознаёт, это значение не считается закреплением.
Запомненные отказы в доступе к моделям
Когда проверки моделей при запуске обнаруживают модель, которую ваш проект не может вызвать, Claude Code может запомнить отказ на этом компьютере на срок до одного дня. Если с последней проверки прошло десять минут, Claude Code при запуске заново проверяет запомненный отказ для текущей модели по умолчанию. Благодаря этому модель по умолчанию, которую ваш администратор снова включил, возвращается. Чтобы отключить это запоминание, установитеCLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1.
Когда ваша организация применяет список разрешённых моделей
Если вы задалиenforceAvailableModels в управляемых настройках, проверки моделей при запуске используют только модели, разрешённые вашим списком availableModels. Для этого требуется Claude Code версии 2.1.287 или новее. Список без enforceAvailableModels не ограничивает эти проверки.
Проверки сравнивают каждую запись с идентификатором модели, который они отправили бы в Agent Platform, поэтому указывайте в списке именно такие идентификаторы. Этот пример разрешает Opus 4.8 и Sonnet 4.5:
modelOverrides см. Закрепление моделей для сторонних развёртываний.
Когда модель отключается во время сессии
Когда Agent Platform отклоняет модель вашей сессии как недоступную в вашем проекте или регионе, Claude Code переключает сессию на другую модель, и вы можете продолжать работу. Вы увидите сообщение, которое начинается сSwitched to <fallback> because <model> is not available. Это происходит, например, когда администратор отключает модель в Model Garden или она не предоставляется в вашем регионе.
Если вы настроили цепочку резервных моделей, Claude Code вместо этого переключается на настроенную вами резервную модель. Без цепочки запрос завершается ошибкой, например в таких случаях:
- Ваша сессия работает на закреплённой модели или на выбранной вами конкретной версии
- Ни одна из моделей, которые пробует Claude Code, не доступна. В авторежиме Claude Code переключается только на модель, которую авторежим поддерживает на Agent Platform.
/model в сессии и нажмите s на модели, доступной в вашем проекте и регионе; при этом ваша модель по умолчанию не изменится.
Чтобы отклонённые запросы завершались ошибкой, а не приводили к переключению, установите CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1. Если вы настроили цепочку резервных моделей, удалите и её, поскольку Claude Code всё равно переключится на эту резервную модель.
Конфигурация IAM
Назначьте рольroles/aiplatform.user, которая включает требуемые разрешения:
aiplatform.endpoints.predict- требуется для вызова модели и подсчета токенов
Создайте выделенный проект GCP для Claude Code, чтобы упростить отслеживание затрат и контроль доступа.
Контекстное окно с 1M токенов
Модели Fable, Sonnet 5 и более поздние версии, а также Opus 4.7 и более поздние версии по умолчанию работают с контекстным окном с 1M токенов на платформе Agent Platform Google Cloud, без необходимости добавлять суффикс[1m]. Чтобы вместо этого сохранить окно 200K, установите CLAUDE_CODE_DISABLE_1M_CONTEXT=1.
Opus 4.6 и Sonnet 4.6 получают окно 1M при выборе их варианта [1m]. Мастер установки предлагает опцию контекстного окна с 1M при закреплении моделей. Чтобы вместо этого включить его для вручную закреплённой модели, добавьте [1m] к ID модели. Подробности см. в разделе Закрепите модели для развёртываний третьих сторон, включая способы использования окна 1M без изменения закрепления.
До версии v2.1.287 модели Fable, а также Opus 4.7 и более поздние версии по умолчанию работали с окном 200K на платформе Agent Platform Google Cloud и получали окно 1M через суффикс [1m].
Устранение неполадок
Если вы столкнулись с ошибками “Could not load the default credentials”:- Запустите
gcloud auth application-default loginдля установки Application Default Credentials - Установите
GOOGLE_APPLICATION_CREDENTIALSна путь файла ключа сервисного аккаунта - См. Configure GCP credentials для всех вариантов
- Проверьте текущие квоты или запросите увеличение квоты через Cloud Console
- Подтвердите, что модель включена в Model Garden
- Проверьте, что модель доступна в указанном вами местоположении. Некоторые модели предлагаются только на
globalили многорегиональных местоположениях, таких какeuиus, а не в конкретных регионах - Если вы используете
CLOUD_ML_REGION=global, проверьте, что ваши модели поддерживают глобальные эндпоинты в Model Garden в разделе “Supported features”. Для моделей, которые не поддерживают глобальные эндпоинты, либо:- Укажите поддерживаемую модель через
ANTHROPIC_MODELилиANTHROPIC_DEFAULT_HAIKU_MODEL, либо - Установите регион или многорегиональное местоположение с помощью переменной
VERTEX_REGION_CLAUDE_*для соответствующей модели, указанной в справочнике по переменным окружения
- Укажите поддерживаемую модель через
- Для региональных конечных точек убедитесь, что основная модель и малая/быстрая модель поддерживаются в выбранном регионе
- Рассмотрите возможность переключения на
CLOUD_ML_REGION=globalдля лучшей доступности