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

Перед настройкой 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

Чтобы войти со своими учетными данными Google Cloud's Agent Platform, следуйте инструкциям Вход с Google Cloud's Agent Platform ниже. Чтобы развернуть Claude Code для команды, используйте шаги ручной установки и закрепите версии ваших моделей перед развертыванием.

Вход с Agent Platform

Если у вас есть учетные данные Google Cloud и вы хотите начать использовать Claude Code через Agent Platform Google Cloud, мастер входа проведет вас через этот процесс. Вы выполняете предварительные требования на стороне GCP один раз для каждого проекта; мастер обрабатывает сторону Claude Code.

После входа запустите /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 через переменные окружения вместо мастера, например в CI или при развертывании в масштабах предприятия, следуйте приведенным ниже шагам.

1. Включите API Agent Platform

Включите API Agent Platform Google Cloud в вашем проекте GCP. Замените YOUR-PROJECT-ID на ID вашего проекта GCP здесь и на этапе конфигурации ниже:

# Установите ID вашего проекта
gcloud config set project YOUR-PROJECT-ID

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

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

Запросите доступ к моделям Claude в Google Cloud's Agent Platform:

1. Перейдите в Google Cloud's Agent Platform Model Garden
2. Найдите модели "Claude"
3. Запросите доступ к нужным моделям Claude (например, Claude Sonnet 4.6)
4. Дождитесь одобрения (может занять 24-48 часов)

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

Claude Code использует стандартную аутентификацию Google Cloud.

Для получения дополнительной информации см. документацию по аутентификации Google Cloud.

Claude Code поддерживает Федерацию рабочих нагрузок на основе сертификатов X.509 через ту же цепочку Application Default Credentials. Установите GOOGLE_APPLICATION_CREDENTIALS на путь к файлу конфигурации учетных данных.

Расширенная конфигурация учетных данных

Claude Code поддерживает автоматическое обновление учетных данных GCP через параметр gcpAuthRefresh. Добавьте его в файл параметров Claude Code, например ~/.claude/settings.json. Когда Claude Code обнаруживает, что ваши учетные данные GCP истекли или не могут быть загружены, он запускает настроенную команду для получения новых учетных данных перед повторной попыткой запроса.

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

Перед запуском команды Claude Code запрашивает маркер доступа с вашими текущими учетными данными, чтобы подтвердить, что они действительно истекли, и пропускает команду, когда они все еще работают.

Если проверка не завершится в течение пяти секунд, Claude Code также пропускает команду и запускает ее только после того, как запрос завершится с ошибкой учетных данных. До версии 2.1.261 проверка, которая истекла по времени, считалась истекшими учетными данными, поэтому команда могла открыть ваш браузер при запуске, даже если ваши учетные данные были еще действительны.

Claude Code показывает вывод команды, но не может отправлять интерактивный ввод команде. Это хорошо работает для потоков аутентификации на основе браузера, где CLI показывает URL, и вы завершаете аутентификацию в браузере. Команда обновления истекает через три минуты, если аутентификация не завершена. Если вы установите gcpAuthRefresh в параметрах проекта, таких как .claude/settings.json, Claude Code запускает его в соответствии с тем же правилом доверия рабочей области, что и hooks в файлах параметров, которое включает сеансы -p в папках, которым вы никогда не доверяли.

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

Установите следующие переменные окружения:

# Включите интеграцию Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Опционально: переопределите URL конечной точки Agent Platform для пользовательских конечных точек или шлюзов
# 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_*. Полный список см. в справочнике переменных окружения. Проверьте 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 3.x: Claude Code загружает определения инструментов MCP заранее, потому что их стеки обслуживания Agent Platform отклоняют требуемый бета-заголовок. Установка ENABLE_TOOL_SEARCH=true не переопределяет это.

Установите ENABLE_TOOL_SEARCH=false, чтобы отключить поиск инструментов на каждой модели. До версии 2.1.221 Claude Code отключал поиск инструментов для всех моделей на Google Cloud's Agent Platform, если вы не установили ENABLE_TOOL_SEARCH=true.

5. Закрепите версии моделей

Установите эти переменные окружения на конкретные 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. Этот пример закрепляет каждый псевдоним на конкретную версию:

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'

Для текущих и устаревших ID моделей см. Обзор моделей. Полный список переменных окружения см. в разделе Конфигурация моделей.

Claude Code использует эти модели по умолчанию, когда переменные закрепления не установлены:

Фоновые задачи, такие как генерация названия сеанса, используют малую/быструю модель, обычно модель класса 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 модели, который доступен в вашем проекте.

До версии 2.1.280 основная модель на Google Cloud's Agent Platform по умолчанию была Opus 5, и псевдоним opus разрешался в Opus 5 с версии 2.1.219. На версиях 2.1.207 по 2.1.218 основная модель на Google Cloud's Agent Platform по умолчанию была Opus 4.8, и псевдоним opus разрешался в Opus 4.8. До версии 2.1.207 основная модель по умолчанию была Sonnet 4.5, псевдоним opus разрешался в Opus 4.6, и фоновые задачи всегда использовали основную модель.

Для дальнейшей настройки моделей:

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

6. Проверьте вашу конфигурацию

Запустите 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 использует резервный вариант для текущей сессии и показывает уведомление. Сначала он пробует более ранние версии модели по умолчанию, а если модель по умолчанию относится к Opus и ни одна версия Opus не доступна, переключается на модель Sonnet по умолчанию. Резервный вариант не сохраняется. Включите более новую модель в Model Garden или закрепите версию, чтобы сделать выбор постоянным.

Когда вы запускаете сессию на конкретной версии Sonnet или Opus, например с помощью --model, ANTHROPIC_MODEL или настройки model, эта версия выступает закреплённой моделью по умолчанию для сессии для соответствующего псевдонима sonnet или opus. Claude Code пропускает проверку доступности встроенной модели по умолчанию, которую заменяет ваша модель, и запускается на настроенной вами модели без уведомления о резервном варианте.

Псевдонимы моделей, такие как opus, не считаются закреплением, как и идентификатор модели, который Claude Code не распознаёт.

Когда эти проверки обнаруживают модель, которую ваш проект не может вызвать, Claude Code запоминает отказ на этом компьютере на срок до одного дня, и при запусках в течение этого времени запомненная модель пропускается без повторного обращения к Agent Platform. Запомненный отказ для текущей модели по умолчанию 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:

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

О псевдонимах, префиксах версий и записях modelOverrides см. Закрепление моделей для сторонних развёртываний.

Когда модель отключается во время сессии

Если ваш проект теряет доступ к модели, на которой работает ваша сессия, например потому что администратор отключил её в Model Garden, Claude Code переключает сессию на другую модель, чтобы каждый запрос не завершался ошибкой, и показывает Switched to <fallback> because <model> is not available. Он пробует те же модели, что и при резервном варианте при запуске: сначала более ранние версии того же уровня, а для сессии Opus, когда ни одна версия Opus не доступна, — модель Sonnet по умолчанию.

Переключение применяется только к уровню, который вы не закрепили, — то же условие, что и для резервного варианта при запуске. Сессия на выбранной вами конкретной версии сохраняет свою модель, и без цепочки резервных моделей запрос вместо этого завершается ошибкой. В авторежиме Claude Code переключается только на модель, которую авторежим поддерживает на Agent Platform. Если ни одна из этих моделей также не доступна, запрос завершается ошибкой.

Настроенная вами цепочка резервных моделей заменяет переключение уровня: при таких отказах Claude Code вместо этого переключается на настроенную вами резервную модель. Чтобы отклонённые запросы завершались ошибкой, а не приводили к переключению, установите CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1. Настроенная вами цепочка резервных моделей по-прежнему срабатывает при таких отказах; удалите и цепочку, если хотите, чтобы каждый отклонённый запрос завершался ошибкой.

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

Назначьте роль roles/aiplatform.user, которая включает требуемые разрешения:

• aiplatform.endpoints.predict - требуется для вызова модели и подсчета токенов

Для более строгих разрешений создайте пользовательскую роль только с указанными выше разрешениями.

Для получения дополнительной информации см. документацию Google Cloud Agent Platform IAM.

Контекстное окно с 1M токенов

Claude Sonnet 5, Opus 4.6 и более поздние версии, а также Sonnet 4.6 поддерживают контекстное окно с 1M токенов на платформе Agent Platform Google Cloud. Sonnet 5 всегда работает с окном 1M, без варианта [1m] для выбора. Для других моделей Claude Code автоматически включает расширенное контекстное окно при выборе варианта модели с 1M.

Мастер установки предлагает опцию контекстного окна с 1M при закреплении моделей. Чтобы включить его для вручную закрепленной модели, добавьте [1m] к ID модели. Подробности см. в разделе Закрепите модели для развертываний третьих сторон, включая способы использования окна 1M без изменения закрепления.

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

Если вы столкнулись с ошибками "Could not load the default credentials":

• Запустите gcloud auth application-default login для установки Application Default Credentials
• Установите GOOGLE_APPLICATION_CREDENTIALS на путь файла ключа сервисного аккаунта
• См. Configure GCP credentials для всех вариантов

Если вы столкнулись с проблемами квоты:

• Проверьте текущие квоты или запросите увеличение квоты через Cloud Console

Если вы столкнулись с ошибками "model not found" 404:

• Подтвердите, что модель включена в Model Garden
• Проверьте, что модель доступна в указанном вами местоположении. Некоторые модели предлагаются только на 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 для лучшей доступности

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

• Документация Google Cloud's Agent Platform
• Цены Google Cloud's Agent Platform
• Квоты и лимиты Google Cloud's Agent Platform