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

​
API форматы

Gateway должен предоставить клиентам Claude Code по крайней мере один из следующих форматов API. Какой формат использует Claude Code, определяется конфигурацией клиента: переменная в столбце “Выбрано” таблицы ниже указывает Claude Code на ваш gateway в этом формате.
ФорматВыбраноКонечные точкиПересылать без изменений
Anthropic MessagesANTHROPIC_BASE_URL/v1/messages, /v1/messages/count_tokens (опционально)заголовки запроса anthropic-beta и anthropic-version
Bedrock InvokeModelANTHROPIC_BEDROCK_BASE_URL с CLAUDE_CODE_USE_BEDROCK=1/model/{model}/invoke, /model/{model}/invoke-with-response-streamполя тела запроса anthropic_beta и anthropic_version
Vertex rawPredictANTHROPIC_VERTEX_BASE_URL с CLAUDE_CODE_USE_VERTEX=1:rawPredict, :streamRawPredict, count-tokens:rawPredict (опционально)заголовки запроса anthropic-beta и anthropic-version, и поле тела запроса anthropic_version

​
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. Суффиксы метода Vertex присоединяются к пути модели издателя, как в /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict. Gateway также видит трафик при запуске, который он может отклонить без нарушения чего-либо: зонд подключения HEAD / и на gateway-ах формата Bedrock запрос GET /inference-profiles?type=SYSTEM_DEFINED.

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

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

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

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

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

Claude Code включает эти заголовки в запросы API. Имена заголовков не чувствительны к регистру на проводе. Пересылайте anthropic-version и anthropic-beta без изменений, плюс anthropic-workspace-id когда upstream — это Claude Platform on AWS; остальное gateway может использовать для маршрутизации, атрибуции и трассировки и не обязан пересылать.
ЗаголовокОписание
Authorization, x-api-keyУчетные данные gateway разработчика, в одном или обоих заголовках в зависимости от того, какую переменную учетных данных они установили
anthropic-versionВерсия API, в настоящее время 2023-06-01. Запросы формата Bedrock и Vertex также содержат поле тела anthropic_version, значение которого — строка диалекта поставщика, а не значение этого заголовка
anthropic-betaЗначения возможностей, разделенные запятыми, для запроса. Пересылайте заголовок дословно; не создавайте список разрешений отдельных значений, потому что набор изменяется с выпусками Claude Code. Когда разработчик аутентифицируется с помощью входа claude.ai, что возможно, когда ANTHROPIC_BASE_URL установлен без переменной учетных данных gateway, этот заголовок также содержит возможность OAuth, которую требует upstream, и удаление его приводит к отказу этих запросов с 401
x-claude-code-session-idУникальный идентификатор текущего сеанса Claude Code. Используйте его для агрегирования всех запросов из одного сеанса без анализа тел запросов
x-claude-code-agent-idИдентификатор подагента, который выдал запрос, присутствует только в запросах от агента, порожденного Claude Code внутри сеанса. Используйте его с идентификатором сеанса для отнесения затрат к параллельным агентам
x-claude-code-parent-agent-idИдентификатор агента, который породил запрашивающего агента, присутствует только для вложенных агентов
Идентификаторы подагентов генерируются заново для каждого порождения. Агенты товарищей, названные члены команды агентов, повторно используют стабильный идентификатор на основе имени при переподключениях. В обоих случаях идентификатор идентифицирует агента, а не человека или устройство, поэтому не рассматривайте заголовок идентификатора агента как идентификатор пользователя. Если ваши разработчики установили ANTHROPIC_CUSTOM_HEADERS, эти заголовки также появляются в запросах.

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

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

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

Claude Code добавляет в начало системного приглашения короткий блок атрибуции, содержащий версию клиента и отпечаток, полученный из разговора. Конечная точка api.anthropic.com удаляет блок перед обработкой, поэтому он не влияет на кеширование приглашений первой стороны; любой другой upstream получает его как часть приглашения. Anthropic и конечные точки Claude облачных поставщиков читают его для атрибуции, поэтому чтобы опустить его, установите CLAUDE_CODE_ATTRIBUTION_HEADER=0 вместо удаления его в gateway. Начиная с 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.
ФункцияЗаголовок и связь телаСимптом при нарушенииИсправление
Адаптивное рассуждениеНет бета-заголовка. Claude Code отправляет thinking: {"type": "adaptive"} для Claude 4.6 и позже и рассматривает имена моделей, которые он не распознает, такие как псевдонимы gateway, как текущие модели, которые получают поле400 с указанием поля thinking или тега adaptive, когда сборка модели upstream его не принимаетОбновите upstream. На Opus 4.6 и Sonnet 4.6 разработчики могут вместо этого установить CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
Управление контекстомБета-заголовок управления контекстом связан с полем тела context_management400 с Extra inputs are not permitted. Часто встречается, когда gateway принимает запросы формата Anthropic, но пересылает их на BedrockПересылайте оба или CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Расширенный контекст и чередующееся мышлениеТолько бета-заголовки, нет поля телаМолча недоступно, когда заголовок удален; upstream никогда не видит запрос возможностиПересылайте anthropic-beta дословно
Бета поля инструментовБета-заголовки, связанные с инструментами, связаны с полями схемы инструментов, такими как strict и defer_loading400 с указанием неузнанного поля схемы инструмента, когда тело проходит без его заголовкаПересылайте оба или CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Усилие и структурированные выходыПоле тела output_config содержит усилие, формат структурированного вывода и параметры бюджета задачи; каждое связано с собственным бета-заголовком400 с указанием output_config, часто Extra inputs are not permitted, на upstream-ах Bedrock и VertexПересылайте поле и его заголовки вместе
Подсчет токеновНет бета-связи; использует конечную точку count_tokensClaude Code возвращается к локальной оценке использования контекстаПредоставьте конечную точку, если вы хотите точные подсчеты
Переменные 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: 
{
  "data": [
    { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },
    { "id": "claude-opus-4-7" }
  ]
}

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

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