Кераванація трафікам Claude Code празе апошыткай, а не чытаючы запрос
Дазвольце даклэ научыцца, як заголовкі падказкаў гейтвэю Claude Code, якія запрашваюць паўнай згоды, дазволяюць гейтвэю LLM прыорітэзаваць, кантроляваць бюджет і адрабатваць кэшы на адной з метаданых запиту, не паводлеючы аналізу тэкста запросу.
Калі компанія перадае трафік Claude Code через ворат LLM, гэты ворат павінен прыймаць рашынкі ўсёх запитоў пры іх перадачы: які шлях аплыву выкарыстоўваць, да якой чергі дадаць запит, які ліміт швычэйнасці застосаваць і якую прыоритэтнасць надаць. До няўзнікаў ёдыным месцам, дзе можна было знайсці факты, якія лежачы ў основе гэтых рашынкаў, быў тэл кожнага запиту — тое ўсё, што ўключалае вашы запросы, змест файлаў, рэзультаты працы інструментоў і CLAUDE.md. Набор загалаваеў запитоў, якія можна ўключыць за жаданнем у няўзнікнутай версіі Claude Code, пераносіць гэтыя факты на самы загалоў запиту. Чытайце нижэй, што можна рашыць за дапамогою кожнага загалоўка, як зміняецца праексі, калі ён можа іх выкарыстоўваць, і дзе яшчэ не трэба ў яных павержацца.
Чаму вораты чытаюць вашы запросы
Перагляд тэксту не ўяўны пытанне; так сама працуюць большасць маршрутаў сёння. Семантычныя маршрутавальнікі, такія як vLLM Semantic Router, выкарыстоўваюць запит корыстніка, інтегруюць яго з модэлем у стылі BERT і паўпоручваюць вектар з вектарамі задання-рэферэнса, каб класыфікацыйна адначасова адпрацаваць запит. Маршрутавальнікі, оптымізаваныя для зменшэння часу обробкі, можаць вычысляць назву модэлю прыбліжна з першага кілабайта і трансляваць рэшту, але кожны маршрутавальнік, якому трэба класыфікацыйна адпрацаваць тэкст, вынужаны ўтримваць у буфере і пераглядаць весь тэкст.
Этот перегляд являецца асоблівасцю продукту, і ён таксама робіць шлюз набліжна болей чутлівым межам довер'я, ніж можа супакоўваць яго простая назва. Шлюз бачыць, а потэнцыйна і зберагае, всё, што надсылае агент разработчика.
У версіі Claude Code 2.1.273, датаванай 15 сября 2026 года, у чатглаге было дадзеныя пяць заголовкаў, спрыятлівых для аператараў гэйтвэя. Разам яны больш прыменяюцца як мінімальныя метаданы, неабходныя гэйтвэю для выконання ролі планавальніка, чым як функцыяя для абліковання стану.
Мерыя первасніх заголовкаў-ідэнтыфікатораў
До версіі 2.1.273 у кансультатывным дапамозніку па сумеснасці гэйтвэяў былі задокументаваны трохі заголовкаў Claude Code, усе яны былі ідэнтыфікаторамі:
+--------------------------------+---------------------------------+
| HEADER | WHAT IT IS |
+--------------------------------+---------------------------------+
| x-claude-code-session-id | which session |
| x-claude-code-agent-id | which subagent (if any) |
| x-claude-code-parent-agent-id | which agent spawned it |
+--------------------------------+---------------------------------+
|
v
good for GROUPING after the fact
useless for DECIDING before forwarding
Дасяглінне документацыі праблему рашчыляе для аграгавання: ідэнтыфікатор сесіі дазваляе групаваць усё, што было адправлена ў сесію, без павтаральнага аналізу тэксту, а ідэнтыфікатор агента, спалучаны з ідэнтыфікаторам сесіі, дазваляе прызначаць вартасць агентам, якія працуюць паралельна. Гэта ўласне бухгалтерскі учёт. Гэтага дастаткова для панелі контролю вартоў, але недастаткова для планавання. Знанне таго, што запит прыйшоў з сесіі abc і агента def, нічога не сказвае пра тое, насколькі ён будзе дорогі, сколькі часу займе або чы можа ён сабе пэўнае чаканне. Таму кожны шлюз, які хацеў бы працаваць розумней, чым просты лічыльнік, быў змушаны адкрыць тэкст запита.
Пяць новых заголовкаў-падказак
За даным хронікайом змян, версія 2.1.273 адгукавала пяць хэдероў, якія ўсе былі увёмкнутыя разам з CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Два з іх описваюць аб’ект, які выканаў запыт (x-claude-code-agent-type і x-claude-code-request-class), аднам выказваецца няўзабавны час выканання (x-claude-code-prev-tool-durations), а пара — перапісвы контэксту (x-claude-code-context-compacted разам з x-claude-code-compaction).
Важна прытка: на момент напісання тэбл параграфоў запыту ў навадзіцеле па сумаспадобнасці гейтвэя яшчэ паказвае толькі тры параграфы-ідэнтыфікаторы, а зменная не прысутня ў справаке па зменных сераўіса. Назвы параграфоў взятыя з журналу змян, але форматы ўсіх іх значэнняў яшчэ не задокументаваны. Усё, што напісана нижэй, описвае, калі гейтвэй можа вырашыць на адной з асноваў параграфоў, а не гарантаваны формат передачы дадзенняў. Пераканайцеся ў своёй справе перш чым паспакоюватыся на конкрэтных значэннях, і перагляньце актуальныя дакументы — у яных можа ўжо быць неабходная інфармацыя.
Групавана па рашэннях, якія кожны з іх дазволяе прыймаць:
+---------------------------+------------------------------------------+
| HEADER | DECISION IT UNBLOCKS AT THE EDGE |
+---------------------------+------------------------------------------+
| request-class | is this a real turn, or a small |
| | internal call? -> priority, cheap pool |
+---------------------------+------------------------------------------+
| agent-type | which kind of subagent is asking |
| | -> per-agent-type budgets and quotas |
+---------------------------+------------------------------------------+
| prev-tool-durations | how long the last tools took |
| | -> timeout and retry window sizing |
+---------------------------+------------------------------------------+
| compaction | this turn IS the summarization call |
| | -> never count it as user latency |
+---------------------------+------------------------------------------+
| context-compacted | the prefix just changed under you |
| | -> do not expect a cache hit this turn |
+---------------------------+------------------------------------------+
Корача кажучы:
- request-class адмініструе розлік межываючых паведамленняў у размове і маленькіх внутраніх запытоў, тады можна надаць прывілеяў першым і направіць другія ў дешавейшы ресурс.
- agent-type вказывае, які тип падагента выкананы запыт, што дазволяе ствараць бюджэты і квоты па типам агента.
- prev-tool-durations паведамляе пра трываласць неякшых запускаў інструментаў, што дапамагае налажыць таймауты і періяды павторных спроб.
- compaction атрыбут, які пазначае запыт, які сам выкаананы сумарызацію, таму ён ніколі не павінен уваходзіць у расчыткі затрымкаў для корыстніка.
- context-compacted сигналізуе, што пачатак размовы быў неякша перапісаны, таму не спадзяваеццася на выкарыстоўванне кэшу.
Нічога з гэтаго не ўжо ўяўляе сабой новую інфармацыю. Гейтвэй можа вже выважваць клас запытку, разбіраючы павную промпт-заповедь системы Claude Code на адміну з промптам класыфікатора, выважваць тип агента з раздзелу промпта системы, прызначанага для агента, і выяўляць ступень складзення па тым, як структураваны массив зменакоў. Загаловкі не розкрываюць нічога дадатковага пра вас. Тое, што зміняецца, — цэна інформацыі: уместо парсавання да мегабайта коду вы карыстаецеся гейтвэй чытае короткі строк з загаловакоў.
Тая ж правіла маршрутацыі, до і пасля
Возьмем конкрэтную мету: направіць падсумовванне фонавай інфармацыі да менш дорогага пула. Без падказак проксі должен зберагаць у буферы і парсаваць кантакт, а потым здагадвацца пра його содержынку:
// BEFORE: the router has to read the conversation to classify it
const body = await readEntireBody(req); // buffers the whole prompt
const parsed = JSON.parse(body); // your files are now in gateway memory
const sys = flattenSystemBlocks(parsed.system);
const isBackground =
sys.includes("summarize the conversation") ||
parsed.messages.length > COMPACT_THRESHOLD;
і толькі пасля гэтаго перадаць зберажаны тэкст:
route(isBackground ? "cheap-pool" : "interactive-pool", body);
Эты спосаб выклікае тры проблемы, ад самай меншай да самай серьознай. Зберагчыце цэлы тэкст размяшчаеся ў памяці, што руйнуе затрымкі стрімавання. Пораўнанне за словамі запытку є нестабільным, адколькі гэтыя словы зменяюцца между версіямі Claude Code. Найгоршае — цэлы текст вашага репазітарыя тепер знаходзіцца ў памяці процеса шару маршрутацыі, у його дампах памяці і, можліва, у журналах, таму, дзе не паказана ні на аднай схеме архітектуры і якое ніхто не падумаў захаваць.
За дапамогою заголовкаў падказакі маршрутацыйны прыстрой чытае два значэння з пакета:
// AFTER: the router decides on the envelope and never touches the body
const cls = req.headers["x-claude-code-request-class"];
const comp = req.headers["x-claude-code-compaction"];
і маршрутуе незменены стрім запытку. Як зазначаецца ў каментары ў фрагменте, строгія значэння-строкі є ілюстрацыйнымі, адколькі формат яшчэ не задокументаваны:
// value strings below are illustrative: confirm them against your own
// traffic, since the wire format is not documented yet
const isBackground = Boolean(comp) || cls === "background";route(isBackground ? "cheap-pool" : "interactive-pool", req); // streams through
Няма буфаравання, няма парсінга JSON і няма запытку, яка застоюецца ў памяці. Кансэпт сумасупаднасці вже дазваляе такі патэрн: кроме anthropic-workspace-id, anthropic-beta і anthropic-version, заголовкі описваюцца як даны, якія гэйтвей можа выкарыстоўваць для трэйсінгу, атрыбуцыі чырактування, і якія не ўмоўлеваны перадаваць далей. Шэры функцыяныяя гэтых заголовкаў — зупініцца на гэйтвей; адколі модель ніколі іх не бачыць, яны можу застаўцца простымі і недорогімі.
Пара для кампактавання — это сігнал кашыравання
Два з заголовкаў выглядаюць зайвымі, але адпавядаюць на разныя запыткі. Першы, x-claude-code-compaction, задаецца пры самай вызове, якая стварае падсумак. Другі, x-claude-code-context-compacted, з’яўляецца пры пазнейшых вызовах, пасля таго, як кампактаванне вялісь.
Разлік мае значэнне, калі вы викорыстоўваеце кэш. Ключы кэша для запитоў складаюцца з прымакоў, якія формуюцца з інструментаў, потым з системнага запиту, а пасля — з прыемаў; таму перапісве ўсьго, што знаходзіцца на пачатку, уневалідавае все, што знаходзіцца пасля. Запісы ў кэш таксаваныя вышэ, чым чытанне з кэша, таму непатрэбныя запісы є простаю вартасцю. Компактаванне яўляецца галоўным факторам уневалідавання дадзеных у звычайной сесіі: яно заменяе накопаную історыю на статыстыку, што за сваёй сутнасцю стварае абліковы прымак.
turn N turn N+1 (compaction) turn N+2
+---------+ +------------------+ +------------------+
| prefix | | compaction: 1 | | context- |
| stable | --> | rewrites history | --> | compacted: 1 |
| cache | | EXPECT A MISS | | new prefix is |
| hits | | bill it as | | now the stable |
+---------+ | background | | one, re-warm it |
+------------------+ +------------------+
Шлюз, які выкарыстоўвае свой сабскэп, але нічога не ведае пра процес складання данных, пад час такога процесу працюе якомога гірш: ён выкарыстоўвае повны пошук, не знаходзіць трэбаваныя данні, запішвае ентрію для прэфікса, які за адзін крок стане некорыстным, а пасля задае высокі рэштунк падзейнасці успеху, што пазніяй адносіцца як дыфект. За дапамогою заголовкаў ён можа прыбегчы да пошуку пад час запиту на складання данных, зарахаваць гэты запыт да фонавай роботы і намерна «загрэяць» новы прэфікс у наступны крок, калі ён стане стабільным.
Падказкі — це тверджэння кліента, а не крантаванні
Як лог змян, так і назвы зменных выкарыстоўваюць гэтыя заголовкі-падказкі, і тут важна сама назва. Падказка — це непераканальнае тверджэння, якое дае кліент. Значэнне x-claude-code-request-class — гэта тое, што Claude Code выбірае адправіць; жадны вышэйшы компонент гэта не пераканвае.
Падзейце, калі ваш гэйтвей прызнае запыткі, пазначаныя як фонавыя, зямнейшымі тарифамі, большыми квотамі або послабленымі лімітамі швайнасці. Тады строка, падае з баку кліента, таямніча прыменяе рашэнне па автарызацыі. Разработчык, який правяроўвае сваё сераўыснае абецэславленне, або будзь-хто, хто запускае маленькі локальны проксі перед гэйтвейам, можа выбраць тую пазначку, якая апавярожнае найбольш ліберальны статус. Падказкі ўжоць паслужаюць годнымі дадзеннямі для формавання абэркі, прыняцьчы рашэнняў па кешаванні та вимеры затрымкі, але ніколі не для вярнення рашэння пра тое, калі права ў кліента.
Другая практычная проблема — адаптаванне. Заголовкі з’являюцца толькі тады, калі яны явнаа ўвёмканы, і гэта правы выбар для метаданных, якія адкрываюць структуру сесіі для промежуточнага сервера. Урахавляючы ўжо ў гэты час відсутнасць іх у значэннях зменных сераўіса, мало якія інсталяцыі, верагатна, будуць яныя увёмканы. У арганізацыі іх зазвычай трэба будзе запускати через кераваныя настройкі ад адміністратара, які зазначыў адпаведную строчку ў журнале змян.
План запуску для аператараў шлюзоў
Якщо ваша команда керуе шлюзам для трафіку Claude Code, астаточны план адаптавання выглядае так:
- Увёмкніце
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1для невялікай групы пілотаў. - Запісвайце всі пяць заголовкаў прыблізна на тыдзень, не робячы нічога з іхнімі данымі.
- Пораўняйце ўсі іхнія значэнні з рашэннямі, якія прымае ваш нынешні класифікатор для аналізу тэкста.
Рызыкт крэсце значна: код развіццялара больш не павінен праходзіць через памяць шару маршрутызацыі, і для яго выкарыстоўваецца адна зменная сяродовішча.
Заключанне
Самыя загаловкі ўзначальваюцься спецыфічна для Claude Code, але урок дизайну паслужыць для будзь-якой платформы агентаў. Кожны слой, які размешчаецца перед агентам, павінен класыфікаваць запиты пры ўсуненні іх далей, і для гэтага існуюць толькі два спосабы: вывяліць адпаведны адказ з пакета дадзеных або прыняць яго як частку явных метадаў. Вывяленне завжды работае, але ўсё роўна заставляе копію чутлівага контэнту ў компоненте, які не мяў прычыны яго зберагаць. Чэрз канал явных метадаў трэба больш прабачыцца дзеяння ў дазорку дизайна, але гэта ўжо едынственны варыянт, калі промежуцкі элемент можа праверна направіць запит, не прымоўваючы самых дадзеных. Чыба прыглядзецца да шырэйшага апісу таго, што здольнае даражыць гэйтвей, можна перайсці на апіс LLM гэйтвей у дакументах Claude Code.