Перейти к основному содержанию
На этой странице документированы запросы, которые Claude Code отправляет на gateway, включая вызываемые конечные точки, заголовки и поля тела, которые gateway должен пересылать, и какие функции перестают работать, если этого не происходит. Она написана для операторов, настраивающих продукт gateway для работы с Claude Code. Работающий Claude apps gateway предоставляет машиночитаемую версию этого контракта по адресу GET /protocol, охватывающую те же требования пересылки плюс специфичные для Claude apps gateway конечные точки для входа SSO, доставки управляемых параметров и телеметрии. Claude apps gateway работает из того же двоичного файла claude, что и CLI, поэтому быстрый старт Claude apps gateway — это кратчайший путь к работающему экземпляру, из которого вы можете получить спецификацию.
  • Чтобы развернуть существующий или сторонний gateway для вашей организации, см. Развертывание LLM gateway
  • Если вы отдельный разработчик, аутентифицирующий Claude Code на gateway с учетными данными, которые вам были предоставлены, см. Подключение Claude Code к LLM gateway
На этой странице рассматриваются: На этой странице используются два термина для описания того, что ваш gateway делает с каждым заголовком и полем тела:
  • Пересылать без изменений: передать его upstream побайтово
  • Использовать: gateway может прочитать его для маршрутизации, атрибуции или трассировки и не обязан пересылать его
Все, что не отмечено как пересылка без изменений, вы можете использовать или игнорировать.

​
API форматы

Gateway должен предоставить клиентам Claude Code по крайней мере один из следующих форматов API. Какой формат использует Claude Code, определяется конфигурацией клиента: переменная в столбце “Выбрано” таблицы ниже указывает Claude Code на ваш gateway в этом формате. Google Cloud’s Agent Platform — это конечная точка Claude компании Google Cloud, ранее известная как Vertex AI; названия её переменных сохраняют написание VERTEX.

​
Foundry и Claude Platform on AWS

Microsoft Foundry и Claude Platform on AWS реализуют формат Anthropic Messages. Claude Code маршрутизирует их через собственные переменные, ANTHROPIC_FOUNDRY_BASE_URL и ANTHROPIC_AWS_BASE_URL, но gateway, находящийся перед ними, реализует строку Anthropic Messages выше. Gateway, находящийся перед Claude Platform on AWS, также должен пересылать заголовок anthropic-workspace-id, который эта платформа требует для каждого запроса.

​
Опциональные конечные точки и трафик при запуске

Конечные точки подсчета токенов — единственные опциональные: когда их нет, Claude Code локально оценивает использование контекста. Запросы вывода отправляются на /v1/messages?beta=true, поэтому сопоставляйте по пути, а не по полному URL. Суффиксы метода Google Cloud’s Agent Platform присоединяются к пути модели издателя, как в /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict. Gateway также видит трафик при запуске, который он может отклонить без нарушения чего-либо: зонд подключения HEAD / и на gateway-ах формата Amazon Bedrock запрос GET /inference-profiles?type=SYSTEM_DEFINED.

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

Ответы вывода должны передаваться потоком. Claude Code использует события, отправляемые сервером, по мере их поступления, поэтому gateway, который буферизирует полные ответы перед их передачей, замораживает клиент.

​
Несоответствие формата с upstream

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

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

Claude Code включает эти заголовки в запросы API. Имена заголовков не чувствительны к регистру на проводе. Пересылайте anthropic-version и anthropic-beta без изменений, плюс anthropic-workspace-id когда upstream — это Claude Platform on AWS; остальное gateway может использовать для маршрутизации, атрибуции и трассировки и не обязан пересылать. Идентификаторы подагентов генерируются заново для каждого порождения. Агенты товарищей, названные члены команды агентов, повторно используют стабильный идентификатор на основе имени при переподключениях. В обоих случаях идентификатор идентифицирует агента, а не человека или устройство, поэтому не рассматривайте заголовок идентификатора агента как идентификатор пользователя. Если ваши разработчики установили ANTHROPIC_CUSTOM_HEADERS, эти заголовки также появляются в запросах.

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

Рассматривайте заголовки и поля тела как открытые списки, а не закрытые. Claude Code получает возможности в выпусках, и они поступают как новые значения anthropic-beta, новые поля тела запроса и иногда новые заголовки anthropic-* или x-claude-code-*. При пересылке на upstream формата Anthropic пропускайте заголовки запроса anthropic-* и поля тела запроса без изменений, а не создавайте список разрешений видимых вами сегодня. Gateway, привязанный к наблюдаемому списку, удаляет заголовок или поле следующей возможности и ломает его при выпуске, который его вводит. Исключением является upstream, не относящийся к Anthropic, такой как Amazon Bedrock или Google Cloud’s Agent Platform, где преодоление различия схемы — задача gateway; см. сквозная передача функций.

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

Claude Code добавляет в начало системного приглашения короткий блок атрибуции, содержащий версию клиента и отпечаток, полученный из разговора. Конечная точка api.anthropic.com удаляет блок перед обработкой, когда он поступает без изменений в качестве первого системного блока, поэтому он не влияет на кеширование приглашений первой стороны. Любой другой upstream получает его как часть приглашения. Удаление является позиционным, поэтому оно работает только тогда, когда шлюз пересылает массив system без изменений. Чтобы исключить блок из приглашения без потери другого системного содержимого:
  • Пересылайте массив system точно так, как он был получен, сохраняя блок первым: добавление другого системного блока в начало, переупорядочение массива или преобразование его в одну строку нарушает удаление, и блок затем достигает модели и ключа кеша приглашений.
  • Сохраняйте блок в собственной записи массива: конечная точка рассматривает объединённый блок, который начинается с заголовка атрибуции, как атрибуцию в целом и удаляет всё объединённое в него, включая остальную часть системного приглашения.
  • Если ваш шлюз должен переформатировать системное содержимое, установите CLAUDE_CODE_ATTRIBUTION_HEADER=0, чтобы Claude Code опустил блок. Anthropic и конечные точки Claude облачных поставщиков читают блок для атрибуции, поэтому опустите его на клиенте, а не удаляйте или перемещайте его в шлюзе.
Запросы, которые достигают конечной точки без изменений, не затронуты. Начиная с Claude Code v2.1.181, блок стабилен в течение всего времени жизни разговора, когда запросы маршрутизируются через пользовательский базовый URL, поэтому кеш приглашений gateway на основе полного тела запроса работает без отключения его. До v2.1.181 блок включал токен для каждого запроса; на этих версиях установите CLAUDE_CODE_ATTRIBUTION_HEADER=0, если ваш gateway реализует такой кеш.

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

Claude Code рассматривает gateway ANTHROPIC_BASE_URL как конечную точку формата Anthropic и отправляет ему бета-заголовки и поля тела запроса, которые он отправляет на api.anthropic.com, за исключением небольшого набора диагностики и значений по умолчанию, зарезервированных для прямых соединений, таких как значение по умолчанию для потоковой передачи инструментов с точной детализацией, описанное ниже. Этот набор варьируется в зависимости от выпуска, поэтому не полагайтесь на его содержимое. Возможности, которые добавляют поля тела, связывают их с бета-заголовком, и пара путешествует вместе. Gateway, который удаляет заголовок при передаче тела или пересылает тело формата Anthropic на upstream с другой схемой, создает жесткие ошибки 400; только когда обе половины отсутствуют вместе, функция отключается тихо. Gateway, который переписывает или редактирует тела запросов для проверки содержимого, нарушает связь так же, как удаление, поэтому проверяйте без изменения. Таблица отмечает, где функция отклоняется от связи. Потоковая передача инструментов с точной детализацией — одно из значений по умолчанию для прямого соединения: она отключена по умолчанию, когда запросы маршрутизируются через пользовательский базовый URL, и gateway получает ее, когда разработчики установили CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1. Переменные ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES объявляют возможности модели только в конфигурациях поставщика: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY и CLAUDE_CODE_USE_MANTLE. Они не имеют эффекта позади gateway ANTHROPIC_BASE_URL.

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

Claude Code автоматически повторяет попытку после некоторых отказов upstream и отключает отклоненную возможность на оставшуюся часть разговора. Отказы поля thinking, сигнатур мышления и системных сообщений в середине разговора восстанавливаются таким образом. Отказы управления контекстом и отказы полей схемы инструментов не повторяются; эти ошибки 400 достигают разработчика. Логика повтора соответствует формулировке ошибки upstream, поэтому пересылайте тела ответов об ошибках без изменений. Gateway, который оборачивает ошибки upstream в собственный конверт, нарушает путь восстановления, даже если он сохраняет код состояния.

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

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 останавливает Claude Code от отправки возможностей предварительного выпуска и их полей тела на каждого поставщика, включая управление контекстом и бета-поля инструментов. Это не влияет на адаптивное рассуждение, которое выбирается по модели, а не по бета, и никогда не подавляет возможность OAuth, которую требует аутентификация подписки. Набор возможностей, которые отправляет Claude Code, растет в выпусках. Для текущих строк бета-заголовков см. справочник бета-заголовков; тестируйте ваш gateway против новых выпусков Claude Code, а не привязывайтесь к наблюдаемому списку.

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

Когда ANTHROPIC_BASE_URL указывает на gateway, который предоставляет формат Anthropic Messages, Claude Code может запросить конечную точку /v1/models gateway при запуске и добавить возвращаемые модели в средство выбора /model. Разработчики включают это, установив CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 в своей собственной среде или через управляемые параметры. Обнаружение отключено по умолчанию, чтобы gateway-ы, поддерживаемые общим ключом API, не выводили каждую модель, к которой ключ может получить доступ, каждому пользователю. Это требует Claude Code v2.1.129 или позже.

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

Обнаружение применяется только к формату Anthropic Messages. Оно не выполняется, когда:
  • Установлена любая переменная поставщика CLAUDE_CODE_USE_*, даже если также установлен ANTHROPIC_BASE_URL
  • ANTHROPIC_BASE_URL не установлен или указывает на api.anthropic.com
  • Несущественный трафик отключен через CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC или политику организации

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

Запрос — это GET /v1/models?limit=1000 с тайм-аутом 3 секунды, и любое перенаправление рассматривается как отказ, поэтому учетные данные не могут утечь на цель перенаправления. Gateway, который отвечает медленно или перенаправляет /v1/models, даже http на https, молча не выполняет обнаружение; обслуживайте конечную точку непосредственно по настроенному базовому URL. Запрос обнаружения отправляет ровно один заголовок учетных данных:
  • ANTHROPIC_AUTH_TOKEN как токен носителя, когда установлен
  • В противном случае разрешенный ключ API, включая значение apiKeyHelper, в заголовке x-api-key
Это отличается от запросов вывода, которые отправляют значение помощника в обоих заголовках. Gateway, который аутентифицирует /v1/models, должен принимать x-api-key для развертываний помощника. Любые заголовки из ANTHROPIC_CUSTOM_HEADERS также включены. Claude Code читает id и опциональный display_name из каждой записи в массиве data ответа и игнорирует записи, чей id не начинается с claude или anthropic:

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

Средство выбора — это интерактивный список моделей, который открывается, когда разработчик запускает /model в Claude Code. Каждая обнаруженная запись помечена “From gateway” и использует display_name при предоставлении. Управляемый параметр availableModels ограничивает то, что может добавить обнаружение. Обнаруженный ID пропускается, когда он точно совпадает со строкой, уже находящейся в средстве выбора, или когда оба обнаруженный и существующий ID разрешаются в Fable. Начиная с Claude Code v2.1.197, обнаруженный явный ID также объединяется со встроенной записью, когда оба разрешаются в одну и ту же модель. Встроенные строки ключены по псевдонимам, таким как sonnet, поэтому обнаруженный явный ID модели, на которую псевдоним в настоящее время разрешается, такой как claude-sonnet-5, объединяется в строку sonnet, в то время как ID, на который псевдоним не разрешается, такой как claude-sonnet-4-6, по-прежнему добавляет собственную строку “From gateway” рядом со встроенной записью. Результаты кешируются в ~/.claude/cache/gateway-models.json или %USERPROFILE%\.claude\cache\gateway-models.json на Windows и обновляются при каждом запуске. Если запрос не выполняется или gateway не реализует /v1/models, средство выбора возвращается к кешированному списку из предыдущего запуска или к встроенному списку моделей. Если ваш gateway обслуживает модели Claude под псевдонимами, которые не совпадают с фильтром обнаружения, разработчики могут добавить эти псевдонимы вручную с помощью переменных конфигурации модели. Для остальной документации gateway и базовых справочников API: