Strona główna / Artykuły

Claude CodeLLM GatewaySecurityAI InfrastructurePrompt Caching

Kierowanie ruchem w Claude Code na podstawie nagłówków zamiast analizy wpisu

Dowiedz się, w jaki sposób nagłówki wskazówek bramy opt-in Claude Code umożliwiają bramie LLM priorytetyzowanie, planowanie i zarządzanie pamięciami cache na podstawie metadanych żądania, bez konieczności analizy treści zapytania.

Wydawca: REACTAPP.TOP9 min czytania1990 słów

Źródła: Your LLM Gateway Reads Your Prompt to Decide Where to Send It. Claude Code Just Shipped Five Headers That Make That Unnecessary.

Gdy firma przesyła ruch Claude Code przez bramkę LLM, ta bramka musi podjąć decyzję dotyczącą każdej prośby przed jej przekazaniem: jakiego źródła danych użyć, do której kolejki dodać ją, jakiego limitu szybkości stosować oraz jaką priorytetność przyznać. Do niedawna jedynym miejscem, gdzie można było znaleźć informacje leżące u podstaw tych decyzji, był treść prośby – czyli twoje polecenia, zawartość plików, wyniki narzędzi oraz plik CLAUDE.md. Zestaw nagłówków prośby, które można aktywować i które dodano w najnowszej wersji Claude Code, przenosi te informacje na samą kopertę przesyłki. Poniżej zobaczysz, co każdy z tych nagłówków umożliwia określić, jak zmienia się funkcjonowanie proxy przy ich użyciu oraz w których przypadkach nadal nie należy im ufać.

Dlaczego bramki ostatecznie czytają twoje polecenia

Inspekcja treści nie jest kwestią teoretyczną – tak właśnie działa obecnie wiele routerów. Routerzy semantyczne, takie jak vLLM Semantic Router, wyodrębniają zapytanie użytkownika, włączają je do modelu w stylu BERT i porównują wektor z wektorami zadań referencyjnych w celu sklasyfikowania żądania. Routerzy zoptymalizowane pod kątem opóźnień przy przekazywaniu danych mogą odczytać nazwę modelu mniej więcej z pierwszego kilobajtu i przesyłać resztę, ale każdy router, który musi sprostać zadaniu klasyfikacji, musi zbuforować i przeanalizować całą treść.

To właśnie ta inspekcja stanowi kluczową cechę produktu i sprawia, że brama sieciowa stanowi znacznie bardziej wrażliwą granicę zaufania, niż sugeruje jej skromna nazwa. Może ona widzieć, a potencjalnie przechowywać, wszystko, co wysyła agent programisty.

Claude Code 2.1.273 z datą 15 września 2026 roku w dzienniku zmian dodaje pięć nagłówków przeznaczonych dla operatorów bramek. Razem stanowią one raczej minimalne metadane niezbędne bramce do działania jako planer, niż funkcję umożliwiającą obserwowalność.

Ograniczenia oryginalnych nagłówków identyfikatorów

Przed wersją 2.1.273 przewodnik kompatybilności bramek opisywał trzy nagłówki Claude Code, z których wszystkie były identyfikatorami:

+--------------------------------+---------------------------------+
| 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

Dokumentacja umożliwia ich agregację: identyfikator sesji pozwala grupować wszystko, co zostało wysłane w ramach sesji, bez konieczności analizy treści, natomiast identyfikator agenta w połączeniu z identyfikatorem sesji umożliwia przypisanie kosztów agentom działającym równolegle. To właśnie jest rachunkowość. Wystarcza to do tworzenia paneli kontrolnych kosztów, ale nie do planowania. Wiedza o tym, że żądanie pochodzi z sesji abc i agenta def, nic nie mówi o tym, jak drogie będzie, ile czasu zajmie ani czy dany agent może sobie pozwolić na czekanie. Dlatego każdy bramkarz, który chciałby być bardziej inteligentny niż zwykły licznik, musiałby otworzyć treść żądania.

Pięć nowych nagłówków wskazówek

Zgodnie z dziennikiem zmian, wersja 2.1.273 wprowadziła pięć nagłówków, które wszystkie zostały włączone razem z CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Dwa opisują wywołującego (x-claude-code-agent-type i x-claude-code-request-class), jeden opisuje ostatnie czasy wykonywania zadań (x-claude-code-prev-tool-durations), a para opisuje modyfikacje kontekstu (x-claude-code-context-compacted wraz z x-claude-code-compaction).

Zgrupowane według decyzji, które każdy z nich umożliwia:

+---------------------------+------------------------------------------+
| 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 oddziela rzeczywiste rundy rozmowy od małych, wewnętrznych wywołań, dzięki czemu można nadać pierwszym wyższy priorytet, a drugie skierować do tańszego zasobu.
  • agent-type wskazuje, jaki rodzaj podagenta dokonuje wywołania, co umożliwia ustalanie budżetów i kwot dla poszczególnych typów agentów.
  • prev-tool-durations podaje czas trwania ostatnich wykonywań narzędzi, co pomaga w ustalaniu czasów oczekiwania i okien ponownych prób.
  • compaction oznacza żądanie, które samo wykonuje podsumowanie, więc nie powinno wpływać na opóźnienia widoczne dla użytkownika.
  • context-compacted sygnalizuje, że prefiks rozmowy został właśnie przepisany, więc nie należy oczekiwać dostępu z pamięci podręcznej.

To nie są żadne nowe informacje. Gateway może już wywnioskować klasę zapytania, analizując pełny prompt systemu Claude Code w porównaniu z uproszczonym promptem klasyfikatora, określić typ agenta na podstawie sekcji agenta w promptzie systemu oraz zauważyć kompresję na podstawie struktury tablicy wiadomości. Nagłówki nie ujawniają żadnych dodatkowych informacji o tobie. To, co się zmienia, to cena wiedzy: zamiast analizować do megabajta kodu źródłowego, gateway czyta krótki ciąg znaków z nagłówków.

Ta sama zasada routingu, przed i po

Weźmy konkretny cel: skierowanie podsumowywania tła do tańszego zasobu. Bez wskazówek proxy musi zapamiętać i przetworzyć rozmowę, a następnie odgadnąć jej treść na podstawie tego, co ma do dyspozycji:

// 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;

i dopiero wtedy przesłać zapamiętany treść wiadomości:

route(isBackground ? "cheap-pool" : "interactive-pool", body);

Ten podejście ma trzy problemy, od najmniej poważnego do najpoważniejszego. Buforowanie całego treści zniszcza opóźnienie w transmisji strumieniowej. Porównywanie zgodnie ze słowami w promptzie jest kruche, ponieważ te sformułowania zmieniają się między wersjami Claude Code. Najgorsze jest to, że pełny tekst twojego repozytorium znajduje się teraz w pamięci procesu warstwy routingu, w jego plikach heap dump oraz prawdopodobnie w logach – miejscu, które nie występuje na żadnym diagramie architektury i którego nikt nie pomyślał o zabezpieczeniu.

Za pomocą nagłówków wskazówek router odczytuje dwa wartości z koperty:

// 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"];

i kieruje nienaruszony strumień żądania. Jak zaznaczono w komentarzu do fragmentu kodu, ciągi znaków o wartościach dosłownych służą jedynie do ilustracji, ponieważ format nie jest jeszcze udokumentowany:

// 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

Nie ma buforowania, nie ma parsowania JSON ani żadnych informacji przechowywanych w pamięci. Przewodnik kompatybilności już zezwala na taki wzorzec: oprócz anthropic-workspace-id, anthropic-beta i anthropic-version nagłówki są opisywane jako dane, których bramka może używać do śledzenia, przypisywania odpowiedzialności lub kierowania ruchem, i nie jest konieczne ich przekazywanie dalej. Te informacje są zaprojektowane tak, by pozostać przy bramce; ponieważ model ich nigdy nie widzi, mogą być proste i nieskosztowne.

Parowanie danych to sygnał do buforowania

Dwa z tych nagłówków wydają się zbędne, ale odpowiadają na różne pytania. Pierwszy, x-claude-code-compaction, jest ustawiany podczas samego wywołania, które tworzy streszczenie. Drugi, x-claude-code-context-compacted, pojawia się przy późniejszych wywołaniach, po tym jak już nastąpiło buforowanie.

Różnica ta ma znaczenie, gdy korzystasz z pamięci cache. Klucze cache dla poleceń składają się z prefiksów utworzonych na podstawie narzędzi, następnie poleceń systemowych i wiadomości; dlatego zmiana czegokolwiek na początku unieważnia wszystko, co znajduje się dalej. Zapisy do cache są również droższe od odczytów z cache, więc niepotrzebne zapisy stanowią czystą stratę. Kompresja jest największym czynnikiem unieważniania danych w zwykłej sesji – zamienia zgromadzoną historię na streszczenie, co z definicji tworzy zupełnie nowy prefiks.

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  |
                +------------------+     +------------------+

Brama, która utrzymuje własną pamięć cache, ale nic nie wie o procesie kompresji, zachowuje się jak najgorszym możliwym sposobem podczas tej operacji: przeprowadza pełne wyszukiwanie, nie znajduje żadnych danych, przechowuje wpis dla prefiksu, który za jeden krok stanie się przestarzały, a następnie zgłasza spadek wskaźnika trafień, co jest badane jako wada. Dzięki nagłówkom może pominąć to wyszukiwanie przy żądaniu kompresji, zaliczyć tę operację jako pracę w tle i celowo „rozgrzać” nowy prefiks w następnym kroku, gdy stanie się on stabilny.

Sugestie to twierdzenia klienta, a nie dane uwierzytelniające

Zarówno dziennik zmian, jak i nazwy zmiennych odnoszą się do tych nagłówków sugestii, a to słowo ma znaczenie. Sugestia to niezweryfikowana twierdzenie składane przez klienta. Wartość x-claude-code-request-class jest taką, jaką Claude Code decyduje się wysłać; żaden komponent wyższego poziomu jej nie weryfikuje.

Załóżmy, że wasz bramkarz premiuje żądania oznaczone jako tła obniżonymi stawkami, większymi kwotami lub łagodniejszymi ograniczeniami szybkości. W takim przypadku ciąg znaków dostarczony przez klienta w tajemnicy podejmuje decyzję o autoryzacji. Programista, który edytuje swoje środowisko shell, lub ktokolwiek uruchamiający mały lokalny proxy przed bramkarzem, może wybrać taką etykietę, która zapewnia najłagodniejsze traktowanie. Wskazówki są przydatne do kolejek, decyzji dotyczących pamięci cache oraz pomiaru opóźnień, ale nigdy nie powinny służyć do określania tego, co dana strona ma prawo otrzymać.

Drugim praktycznym problemem jest wdrożenie. Nagłówki są wyłączone, chyba że zostaną wyraźnie włączone, co jest właściwym rozwiązaniem dla metadanych ujawniających strukturę sesji przed serwerem pośredniczącym. Biorąc pod uwagę ich brak w odniesieniach do zmiennych środowiskowych w momencie pisania tego tekstu, niewiele instalacji prawdopodobnie ma je włączone. W organizacji zazwyczaj trzeba będzie je wprowadzać poprzez zarządzane ustawienia przez administratora, który zauważy pojedynczy wiersz w dzienniku zmian.

Plan wdrożenia dla operatorów bram

Jeśli wasz zespół zarządza bramą dla ruchu Claude Code, ostrożna ścieżka wdrożenia wygląda następująco:

  • Włącz CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 dla małej grupy pilotażowej.
  • Zapisuj wszystkie pięć nagłówków przez około tydzień, nie podejmując żadnych działań na ich podstawie.
  • Porównaj ich wartości z decyzjami podejmowanymi obecnym klasyfikatorem analizującym treść.
  • Jeśli się zgodzą, przełącz routowanie na nagłówki, przestań buforować treści i usuń parsera.
  • Decyzje dotyczące uprawnień powinny opierać się na autoryzowanej tożsamości, a nie na wartościach wskazówek.

    • Korzyścią jest znacznie mniejszy zasięg wpływu: kod źródłowy waszych programistów nie musi już przechodzić przez pamięć warstwy routowania, a wymaga tylko jednej zmiennej środowiskowej.

    Zakończenie

    Tytuły te są specyficzne dla Claude Code, ale zasada projektowania ma zastosowanie do każdej platformy agentów. Każda warstwa umieszczona przed agentem musi sklasyfikować żądania przed przekazaniem ich dalej, a istnieją tylko dwie sposoby na to: wywnioskowanie odpowiedzi z treści żądania lub otrzymanie jej jako jawnych metadanych. Wywnioskowanie zawsze działa, ale zawsze pozostawia kopię wrażliwych danych w komponencie, który nie miał powodu, by je przechowywać. Użycie jawnych metadanych wymaga więcej pracy projektowej na początku, ale to jedyny sposób, w którym pośrednik może prawidłowo kierować żądania, nie otrzymując przy tym samych danych. Aby zapoznać się z szerszym obrazem tego, co oferuje brama, sprawdź przegląd bramy LLM w dokumentacji Claude Code.

    Literatura pokrewna

    ← Wszystkie artykułyWyślij brief