Руководство совместимости Claude Code gateway

• Форматы API и конечные точки для обслуживания для каждого
• Поведение клиента по методу подключения: как идентификаторы моделей, значения anthropic-beta, поля запроса и значения по умолчанию отличаются между форматами и входом в Claude apps gateway
• Заголовки запроса: какие должны достичь вышестоящего сервера и какие может использовать ваш шлюз
• Заголовки ответа: что возвращать, чтобы обнаружение зависания, повторные попытки и отображение лимита использования работали
• Блок атрибуции системного приглашения и как он взаимодействует с кэшированием приглашений
• Сквозная передача функций: что перестает работать при удалении заголовков или полей тела
• Обнаружение модели

• Передавать без изменений: передать его вышестоящему серверу побайтово
• Использовать: шлюз может прочитать его для маршрутизации, атрибуции или трассировки и не обязан передавать его

​

Форматы API

​

Foundry и Claude Platform on AWS

​

Опциональные endpoints и стартовый трафик

• Запросы вывода отправляются на /v1/messages?beta=true
• Метод Google Cloud’s Agent Platform добавляет суффиксы к пути модели издателя, как в /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

​

Потоковая передача

• Если ваш шлюз буферизирует ответ до его завершения, Claude Code зависает.
• Claude Code ожидает полную последовательность событий каждого ответа, по порядку, вплоть до финальных событий message_delta и message_stop. Если тело завершается чисто после начала блока контента, но до этого финального message_delta, Claude Code рассматривает ответ как разорванное соединение. The response above may be incomplete описывает, что в этом случае видит пользователь, а раздел Автоматические повторные попытки — когда Claude Code вместо этого повторно отправляет запрос.
• Когда guardrail Amazon Bedrock блокирует ответ, события, которые отправляет Bedrock, могут ссылаться на блок контента, чей content_block_stop уже прибыл, и Claude Code рассчитывает получить их в том виде, в каком они были отправлены. AWS Guardrails описывает, как завершается такой ответ.
• Claude Code прерывает потоковый ответ, как только на него не поступают байты дольше, чем его таймаут простоя потоковой передачи. Во время длительной паузы мышления SSE-события ping вышестоящего сервера могут быть единственными байтами в потоке, поэтому шлюз, который удаляет или буферизирует их, может вызвать срабатывание этого таймаута посреди ответа. У шлюза, который выполняет преобразование с вышестоящего сервера без пингов, такого как двоичный поток событий Amazon Bedrock, возникает тот же пробел, если только он не выдаёт собственные события ping.
• В формате Amazon Bedrock InvokeModel Claude Code читает ответ /model/{model}/invoke-with-response-stream как двоичное тело application/vnd.amazon.eventstream, которое возвращает Bedrock, и не может его разобрать, если шлюз преобразует его в server-sent events или переписывает этот заголовок Content-Type. Раздел Ошибки потоковой передачи за шлюзом или прокси описывает, что в этом случае видит пользователь.

​

Несоответствие формата с вышестоящим сервером

• Когда клиент использует формат Amazon Bedrock или Google Cloud’s Agent Platform, Claude Code отправляет только подмножество своего полного набора возможностей, которое эти поставщики принимают
• Когда клиент использует формат Anthropic Messages, Claude Code отправляет полный набор, даже если ваш шлюз пересылает на вышестоящий сервер Amazon Bedrock или Google Cloud’s Agent Platform

​

Как метод подключения изменяет поведение клиента

• Формат Amazon Bedrock или Agent Platform: разработчик устанавливает CLAUDE_CODE_USE_BEDROCK=1 с ANTHROPIC_BEDROCK_BASE_URL или CLAUDE_CODE_USE_VERTEX=1 с ANTHROPIC_VERTEX_BASE_URL, указывающие на ваш шлюз. Claude Code использует ID моделей этого поставщика, поля запроса и значения по умолчанию.
• Формат Anthropic Messages: разработчик устанавливает ANTHROPIC_BASE_URL на ваш шлюз. Claude Code рассматривает шлюз как Claude API и не может определить, на какой upstream вы перенаправляете.
• Вход в шлюз Claude apps: разработчик входит в шлюз Claude apps. Этот шлюз использует формат Anthropic Messages, но может маршрутизировать на любой upstream, поэтому Claude Code отправляет только значения anthropic-beta и предположения о возможностях модели, которые также принимают Amazon Bedrock и Agent Platform.

​

Запросы и значения по умолчанию по методу подключения

​

Параметры для нераспознанных ID моделей

• Окно контекста: Claude Code предполагает 200K или 1M, когда ID содержит [1m]. Чтобы объявить реальное окно, см. Исправьте окно для шлюза или пользовательского ID модели
• Возможности: чтобы дать alias шлюза возможности модели позади него, сопоставьте ID Anthropic этой модели с вашим alias с помощью записи modelOverrides в параметрах, которые вы распространяете. Для того, где применяются переменные ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES, см. передача функций

​

Заголовки запроса

​

Заголовки подсказок Gateway

• Прямое подключение к API Anthropic: отправляются по умолчанию
• Пользовательский базовый URL: отключено по умолчанию, потому что прокси, который отклоняет неизвестные заголовки, приведет к отказу запроса. Чтобы их получить, установите CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 для ваших разработчиков, например в блоке env управляемых параметров
• Любой другой backend, включая Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry и Claude Platform on AWS: отправляются только когда установлено CLAUDE_CODE_GATEWAY_HINT_HEADERS=1

• Записи: одна на каждый выполненный вызов инструмента, в порядке сбора его результата, в целых миллисекундах
• Ограничение: Claude Code отправляет максимум 32 записи и 4 КБ, сохраняя первые записи
• Кодирование: имена инструментов кодируются в процентах, охватывая %, ;, =, запятую, пробел и любой символ вне печатаемого ASCII
• Анализ: разделите на ;, затем на =, и декодируйте каждое имя
• Отсутствие: вызовы компактирования, побочные запросы и первый запрос нового подсказки никогда его не содержат. Не читайте отсутствующий заголовок как ход, который не запустил никакие инструменты
• Времена: каждое исключает подсказки разрешения и hooks, и параллельные вызовы инструментов каждый сообщают свое собственное время, поэтому записи не складываются в промежуток между запросами

​

Пересылка как открытые списки

​

Заголовки ответов

​

Блок атрибуции системного приглашения

• Пересылайте массив system точно так, как он был получен, сохраняя блок первым: добавление другого системного блока в начало, переупорядочение массива или преобразование его в одну строку нарушает удаление, и блок затем достигает модели и ключа кеша приглашений.
• Сохраняйте блок в собственной записи массива: конечная точка рассматривает объединённый блок, который начинается с заголовка атрибуции, как атрибуцию в целом и удаляет всё объединённое в него, включая остальную часть системного приглашения.
• Если ваш шлюз должен переформатировать системное содержимое, установите CLAUDE_CODE_ATTRIBUTION_HEADER=0, чтобы Claude Code опустил блок. Anthropic и конечные точки Claude облачных поставщиков читают блок для атрибуции, поэтому опустите его на клиенте, а не удаляйте или перемещайте его в шлюзе.

• Запросы поступают на api.anthropic.com, с ANTHROPIC_BASE_URL не установленной или указывающей на этот хост, и ни один поставщик третьей стороны не выбран.
• Активные учётные данные не являются профилем Anthropic или учётными данными федерации.

• Реализует кеш приглашений, использующий ключ на основе тела запроса.
• Пересылает запросы поставщику третьей стороны, такому как Amazon Bedrock, Microsoft Foundry или Google Cloud’s Agent Platform, в формате Anthropic Messages или в собственном формате поставщика, где изменяющийся префикс снижает повторное использование кеша приглашений у этого поставщика.

​

Сквозная передача функций

​

Пары бета-заголовков и полей тела

​

Автоматический повтор и пересылка ошибок

• Когда ошибка 400 сообщает, что значение thinking.type enabled или adaptive не поддерживается, Claude Code один раз повторяет попытку с другим типом и сохраняет поле thinking. Последующие запросы к этой модели используют измененный тип до выхода из Claude Code. До версии v2.1.121 Claude Code не повторял попытку, поэтому ошибка thinking.type.enabled is not supported доходила до разработчика
• Когда вышестоящий сервер отклоняет запись role: "system" внутри messages, Claude Code один раз повторяет попытку без этих системных сообщений в середине диалога и вместо этого передает их текст в пользовательских сообщениях. Последующие запросы в диалоге сохраняют эту форму, пока разработчик не выполнит /clear или диалог не будет сжат
• Когда вышестоящий сервер отклоняет только маркер cache_control на системном сообщении в середине диалога, Claude Code сохраняет системные сообщения и один раз повторяет попытку с перемещенным маркером. Маркер ставится на последнюю запись в messages, которая не является системным сообщением, — в этой повторной попытке и в последующих запросах до выхода из Claude Code
• Когда вышестоящий сервер отклоняет подпись мышления, включая ошибку 400, сообщение которой говорит, что блок bound to a different conversation, Claude Code удаляет более ранние блоки мышления из запроса, повторяет и исключает их из каждого последующего запроса. Новые ответы по-прежнему включают мышление
• Когда шлюз или его вышестоящий сервер отклоняет запись инструмента-советника в tools как неизвестный тип инструмента, Claude Code повторяет запрос один раз без этой записи и ее значения anthropic-beta. Последующие запросы их не содержат. Claude Code распознает это отклонение по ответу 400 или 422, сообщение которого называет тип инструмента после Input tag, например Input tag 'advisor_20260301'. До версии v2.1.280 Claude Code не повторял попытку при этом отклонении
• Когда вышестоящий сервер отклоняет output_config.effort или его значение anthropic-beta, шлюз получает запрос еще раз без них. Последующие запросы их не содержат. Вашему шлюзу не нужны изменения, если он пересылает ошибку 400 вышестоящего сервера без изменений, а ее сообщение:
  • Называет output_config.effort вместе с Extra inputs are not permitted
  • Сообщает, что модель не поддерживает параметр effort
  • Начинается с Unexpected value(s) и указывает effort-2025-11-24 для заголовка anthropic-beta. Требуется v2.1.310 или более поздняя версия. Разработчики, у которых ANTHROPIC_BETAS содержит это значение, продолжают его отправлять и получать ошибку 400, поэтому попросите их удалить эту запись
• Когда вышестоящий сервер отклоняет поле context_management или его значение anthropic-beta, шлюз получает запрос еще раз без них. Последующие запросы их не содержат. Claude Code распознает это отклонение по его сообщению, например содержащему context_management: Extra inputs are not permitted. До версии v2.1.304 Claude Code не повторял попытку при этом отклонении
• Когда ошибка 400 отклоняет по имени другое значение anthropic-beta, шлюз получает запрос еще раз без него, если повторная попытка распространяется на это значение
• Когда вышестоящий сервер отклоняет бета-поле инструмента, отличное от defer_loading, например strict, ошибка 400 доходит до разработчика. Перед этим шлюз может снова получить запрос без полей поиска инструментов. Чтобы прекратить отправку таких полей, попросите разработчиков установить CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

​

Повторная попытка без отклоненного бета-значения

• Предложение API: предложение Unexpected value(s), в котором указано значение для заголовка anthropic-beta
• Токен beta_header:: capability_rejected: beta_header:, за которым следует значение, — токен capability_rejected:

• Значение с собственной повторной попыткой, например советник или поиск инструментов: шлюз вместо этого видит собственную повторную попытку этой возможности
• Значение, которое Claude Code не распознает: значение, заданное разработчиком через ANTHROPIC_BETAS, остается в каждом запросе, поэтому запросы разработчика продолжают завершаться ошибкой 400. Попросите разработчика удалить эту запись
• Сообщение, содержащее только invalid beta flag: Claude Code предполагает, какое значение отклонил вышестоящий сервер. Если запрос содержал одно из предполагаемых значений, шлюз снова получает запрос без этого значения. Если ошибка 400 все равно доходит до разработчика, сделайте так, чтобы ваш шлюз указывал отклоненное значение в одной из этих форм

​

Как долго отклоненное бета-значение не отправляется

​

Повторная попытка без поиска инструментов

​

Отключение предварительных возможностей

• Управление контекстом и его поле тела context_management
• Бета-поля схемы инструментов, такие как strict и defer_loading. Стандартные поля инструментов name, description, input_schema и cache_control сохраняются
• Поле структурированного вывода output_config.format. Требуется Claude Code v2.1.287 или более поздней версии
• Поле output_config.task_budget
• MCP Tool Search, поэтому все инструменты MCP загружаются заранее, если только ваша организация не оставляет эту функцию включенной через управляемые настройки

• Значения anthropic-beta для расширенного контекста, чередующегося мышления и усилия, которые также принимают облачные поставщики
• Поле верхнего уровня output_config.effort. В разделе Автоматические повторные попытки и пересылка ошибок описан случай, когда вышестоящий сервер его отклоняет
• Поле thinking адаптивного рассуждения, у которого нет бета-заголовка
• Записи role: "system", которые содержат системные сообщения в середине диалога
• Значение anthropic-beta для OAuth, которое требуется для аутентификации по подписке
• Значения заголовков и поля тела, которые разработчики добавляют сами через ANTHROPIC_BETAS или CLAUDE_CODE_EXTRA_BODY

• При прямом соединении без конфигурации HIPAA или через шлюз, установленный с ANTHROPIC_BASE_URL, Claude Code продолжает отправлять бета-заголовок поиска инструментов, поля инструментов defer_loading и блоки tool_reference
• На облачном поставщике или при входе через Claude apps gateway, переопределение не имеет никакого эффекта
• В сессии, которая получает конфигурацию HIPAA, переопределение не имеет никакого эффекта, и поиск инструментов остается отключенным

​

Обнаружение моделей

​

Когда выполняется обнаружение

• Установлена любая переменная поставщика CLAUDE_CODE_USE_*, даже если также установлен ANTHROPIC_BASE_URL
• ANTHROPIC_BASE_URL не установлен или указывает на api.anthropic.com

​

Запрос и ответ

• Authorization: ANTHROPIC_AUTH_TOKEN как токен носителя, в противном случае значение apiKeyHelper как токен носителя.
• x-api-key: разрешенный Claude Code ключ API, такой как ANTHROPIC_API_KEY. Когда значение помощника является единственным учетным данием, этот заголовок также его содержит, поэтому значение поступает в оба заголовка.

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

​

Записи средства выбора и кеширование

• Одинаковый ID: обнаруженный ID точно совпадает с ID существующей строки, или оба ID являются написаниями одной и той же версии Fable.
• Та же модель, что и встроенный псевдоним: когда обнаруженный явный ID называет модель, в которую встроенный псевдоним в настоящее время разрешается, средство выбора показывает только строку псевдонима. Например, пока sonnet разрешается в claude-sonnet-5-5, обнаруженный claude-sonnet-5-5 объединяется в строку sonnet, а обнаруженный claude-sonnet-5 всё ещё получает свою собственную строку.

​

Связанные ресурсы

• Обзор gateway: что такое gateway и как выбрать между Claude apps gateway и другим продуктом
• Другие LLM gateway: как развернуть gateway, который работает в вашей организации, и как он взаимодействует с подписками claude.ai
• Развертывание LLM gateway для вашей организации: контрольный список администратора, который использует этот контракт
• Подключение Claude Code к LLM gateway: конфигурация для каждого разработчика и таблица устранения неполадок
• Справочник бета-заголовков: текущий набор значений anthropic-beta
• Messages API: формат API, который реализует gateway формата Anthropic