Руководство совместимости 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

​

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

​

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

• Когда клиент использует формат 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 или в собственном формате поставщика, где изменяющийся префикс снижает повторное использование кеша приглашений у этого поставщика.

​

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

​

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

• Когда вышестоящий сервер отклоняет поле thinking, системное сообщение в середине разговора или маркер cache_control на таком сообщении, Claude Code повторяет запрос и отключает отклоненную возможность для остальной части разговора
• Когда вышестоящий сервер отклоняет подпись мышления, включая ошибку 400, сообщение которой говорит, что блок bound to a different conversation, Claude Code удаляет более ранние блоки мышления из запроса, повторяет и исключает их из каждого последующего запроса. Новые ответы по-прежнему включают мышление
• Когда шлюз или его вышестоящий сервер отклоняет запись инструмента-советника в tools как неизвестный тип инструмента, Claude Code повторяет запрос один раз без этой записи и ее значения anthropic-beta. Более поздние запросы к этому базовому URL оставляют советника без внимания до выхода Claude Code, и /advisor недоступен разработчику в течение этого времени. Claude Code распознает это отклонение по ответу 400 или 422, сообщение которого называет тип инструмента после Input tag, например Input tag 'advisor_20260301'. До версии v2.1.280 Claude Code не повторял это отклонение
• Claude Code не повторяет отклонения управления контекстом или полей схемы инструментов, поэтому эти ошибки 400 достигают разработчика

​

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

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

​

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

​

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

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

​

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

• Authorization: ANTHROPIC_AUTH_TOKEN как токен носителя, в противном случае значение apiKeyHelper как токен носителя. В этом случае Claude Code ждет, пока помощник вернет результат перед отправкой запроса.
• 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, обнаруженный claude-sonnet-5 объединяется в строку sonnet, и обнаруженный claude-sonnet-4-6 все еще получает свою собственную строку. До версии v2.1.197 Claude Code не объединял эти ID во встроенные строки, поэтому claude-sonnet-5 также получал свою собственную строку “From gateway”.

​

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

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