РЕКЛАМА Playerok Playerok — маркетплейс игровых аккаунтов, предметов и цифровых товаров.Реклама. Playerok. erid: 2SDnjdoNNsV. Рекламодатель ООО "Смарт Хоум", ИНН 9731066701. Перейти →
ГАЙД 2026

Headroom: как сжимать контекст агента и платить меньше за токены

Агент платит за каждый токен, который прочитал: логи, JSON, файлы, историю сессии. Headroom сжимает это локально до отправки в модель — от 21% до 57% на реальных сценариях, с возможностью вернуть оригинал.

ГайдКонтекстЭкономия токенов
Уровень СреднийВремя настройки 10–20 минутЛицензия Apache-2.0Обновлено 08.11.2026

Результат гайда: вы включаете сжатие контекста за десять минут — одной командой для coding-агента или парой строк кода для своего приложения — и видите, сколько токенов реально экономится на вашем трафике, а не в чужом бенчмарке.

Перед началом
Нужен Python 3.11+ или Node.js 18+, если ставите SDK. Сжатие работает на вашей машине: ни промпты, ни файлы наружу не отправляются. Для полностью офлайнового прогона есть HEADROOM_OFFLINE=1.

01Зачем сжимать контекст и что именно болит

Большая часть счёта coding-агента — это не ответы, а чтение: вывод тестов, ответы MCP-серверов, куски файлов, история правок. Полезная строка в логе обычно одна (та самая FATAL), а платите вы за десять тысяч токенов вокруг неё.

Headroom ставит между агентом и провайдером локальный слой, который переписывает входной контекст: режет повторы в JSON-массивах, выкидывает шаблонные строки логов, ужимает историю сессии. Оригиналы остаются на диске, и модель может запросить полный текст инструментом headroom_retrieve — то есть сжатие обратимое.

Плати по всему миру — карта для оплаты зарубежных нейросетей, приложений и подписок из России
Реклама. ООО «КАПИБАРА», ИНН 9703231520
Из чего состоит контекст агента
42%25%21%12%100%входных токеновВывод инструментов и логи42 · 42%Файлы и код25 · 25%История диалога21 · 21%RAG и поиск12 · 12%
Типовая структура входа coding-агента по описанию проекта: три четверти контекста — служебные данные, а не задача.

Экономия не бесплатна по смыслу: любое сжатие — это ставка на то, что деталь не понадобится. Поэтому в гайде отдельный раздел про замеры точности и про то, где сжатие почти не работает — на связной прозе и уже плотном тексте.

02Как устроено: четыре узла и хранилище оригиналов

Слои обработки запроса
CacheAlignerНаходит волатильные куски, которые ломают KV-кэш провайдера. Промпт не переписывает.до моделиContentRouterОпределяет тип содержимого: JSON, код, проза — и выбирает компрессор.локальноКомпрессорыSmartCrusher (JSON), CodeCompressor (AST кода), Kompress-v2-base (текст, модель на HuggingFace).провайдерCCRХранит оригиналы локально и отдаёт их по запросу headroom_retrieve.
Путь одного запроса
1АгентClaude Code, Codex, Cursor иливаш код собирает контекст2HeadroomСжимает вход и сохраняеторигиналы локально3ПровайдерПолучает меньше токенов иотвечает как обычноСжатие происходит до провайдера, на вашей машине

Ключевая деталь — маршрутизация по типу. JSON-массивы и логи сжимаются на 90%+, а связная проза почти не поддаётся: если бы компрессор был один на всё, экономия на документации съедалась бы риском потерять смысл.

Кэш важнее процентов
Провайдеры дают скидку за повторное использование префикса промпта. Если сжатие меняет префикс на каждом запросе, выигрыш на токенах съедается потерей кэша — поэтому CacheAligner не «улучшает» промпт, а только помечает волатильные участки.

03Установка за 60 секунд

От установки до первого отчёта
1
Поставьте CLI
Изолированное окружение через uv — основной способ из README; pip тоже работает и приносит команду headroom.
terminalcopy
uv tool install --python 3.13 "headroom-ai[all]"
2
Выберите режим
wrap запускает агент через прокси, proxy поднимает прокси отдельно, deploy ставит постоянный сервис.
terminalcopy
headroom wrap claude
3
Проверьте здоровье
doctor подтверждает, что маршрутизация и сжатие работают, perf показывает скорость обработки.
terminalcopy
headroom doctor && headroom perf
4
Смотрите цифры
dashboard открывает локальную панель с экономией; savings считает по вашему трафику.
terminalcopy
headroom savings

Для своего приложения установка проще: pip install headroom-ai, затем from headroom import compress. Функция принимает список сообщений в формате OpenAI или Anthropic, возвращает объект с полями messages, tokens_saved и compression_ratio — второй аргумент model= нужен для правильного токенизатора.

CLI только в PyPI-пакете
npm-пакет headroom-ai — это TypeScript SDK без команды headroom. Если приложение на Node, SDK отправляет сообщения в локальный прокси, который поднимается отдельно: pip install "headroom-ai[proxy]" и headroom proxy --port 8787.

04Три режима и когда какой брать

РежимКак включаетсяКому подходитМинусы
Библиотекаcompress(messages, model=...)Свой код на Python или TSПравки в коде приложения
Проксиheadroom proxy --port 8787Любой клиент, включая TS и GoНужен запущенный процесс
Wrap агентаheadroom wrap claudeCoding-агенты без изменений кодаЖивёт только на время сессии
MCP-серверheadroom mcp installMCP-нативные клиентыМеньше контроля над потоком
Режимы комбинируются: wrap поднимает прокси сам, а библиотека может ходить в тот же процесс.

Wrap поддерживает два десятка агентов: Claude Code, Codex, Grok CLI, Aider, Copilot CLI, VS Code Copilot, OpenCode, Cline, Continue, Goose, OpenHands, Kimi CLI, Factory Droid, ZCode и другие. Для Cursor настройка ручная — прокси печатает базовые адреса, которые нужно вписать в настройки. Cortex Code работает только как библиотека.

Отмена durable-обёртки — одна команда headroom unwrap <tool>. Это важно для тех, кто пробует инструмент на рабочей машине: конфиги агента возвращаются в исходное состояние, а не остаются с прописанным адресом прокси.

Свой код: минимальный пример
1
Импорт и сжатие
Сжимаются сообщения инструментов и ассистента; сообщения пользователя не трогаются без явного флага.
app.pycopy
from headroom import compress
r = compress(msgs, model="gpt-4o")
print(r.tokens_saved, r.compression_ratio)
2
Отправка в модель
В провайдер уходит r.messages — обычный вызов, без правок клиента и без ключа Headroom.
app.pycopy
client.chat.completions.create(
    model="gpt-4o", messages=r.messages)
Сторонний OpenAI-совместимый провайдер
По умолчанию wrap отправляет OpenAI-трафик на api.openai.com. Для DeepSeek, OpenRouter или своего шлюза передайте --openai-api-url (или переменную OPENAI_TARGET_API_URL), иначе ключ уйдёт не туда и вернётся 401.

05Что реально экономит: замеры проекта

В README опубликованы четыре сценария, собранные из реальных форматов вывода MCP-серверов, с провайдерским токенизатором и тем же compress(), что ставится из пакета. Замеры воспроизводимы: uv run python benchmarks/index_proof_table.py --seed 20260902.

Токены до и после сжатиячетыре сценария, данные авторов
015 00030 00045 00060 000Поиск по кодуРазбор инцидентаОбход кодовой базыРазбор issue17 19955 95758 80146 06713 59724 34033 89532 429До сжатияПосле
Сценарии построены на форматах вывода MCP-серверов, а не на живом трафике конкретной команды.
Доля сэкономленных входных токенов%, чем длиннее повторы, тем выше экономия
0%30%60%Разбор инцидента57%Обход кодовой базы42%Разбор issue30%Поиск по коду21%
Данные авторов проекта на 08.11.2026. На вашем трафике цифра будет другой — её показывает команда headroom savings.

Обратите внимание на разброс: 21% на поиске по коду и 57% на разборе инцидента — это один и тот же компрессор на разных данных. Повторяющиеся JSON-массивы и строки логов уходят за 90%, а плотная проза почти не сжимается. Отсюда вывод: включать сжатие стоит там, где агент много читает машинного вывода.

Разработка Headroom по неделямкоммитов в неделю, последние 16 недель, снято 08.11.2026
050100150200н1н3н5н7н9н11н13н1534761247932294922135144178565961183183
Источник — stats/participation GitHub API. Ровный темп без «мёртвых» недель: проект активно развивается.

06Не теряет ли модель смысл: точность и скорость

В репозитории есть набор проверок точности: python -m headroom.evals suite --tier 1. Цифры ниже — из README, на выборке 100 задач; при таком N изменение ±0,03 статистически неотличимо от нуля, и авторы честно пишут, что TruthfulQA не улучшилась, а «не показала разницы».

БенчмаркЧто меритБазовая линияС HeadroomРазница
GSM8KШкольная математика0,8700,870±0,000
TruthfulQAФактологичность0,5300,560+0,030
SQuAD v2Вопросы по тексту—97%при 19% сжатия
BFCLВызов инструментов—97%при 32% сжатия
Данные авторов проекта, N=100 на бенчмарк. Для продакшена важнее свой замер на своих задачах.

Скорость сжатия — доли миллисекунды: 0,21 мс p50 на JSON-результате в 10 тыс. токенов и 1,4 мс на 100 тысячах. То есть на задержку агента это не влияет — в отличие от лишнего сетевого хопа к стороннему сервису сжатия.

Обратимость — главный аргумент
Сжатие не «выбрасывает» данные: оригинал лежит в локальном хранилище CCR, и модель может забрать полный текст инструментом headroom_retrieve. Поэтому редкая деталь не теряется навсегда — её просто не отправляют в контекст заранее.

Для команд важнее другое: headroom learn разбирает проваливавшиеся сессии и дописывает поправки в CLAUDE.local.md, AGENTS.md или GEMINI.md. Это уже не про токены, а про то, чтобы агент не повторял одну и ту же ошибку в следующей сессии.

07Ограничения, приватность и тарифы

  • Прозу и уже плотный текст сжатие почти не уменьшает — ждать 50% на документации не стоит.
  • Компрессор текста тянет модель Kompress-v2-base с HuggingFace: первый запуск требует загрузки, в закрытом контуре нужен HF_ENDPOINT и предварительная загрузка.
  • Телеметрия включена по умолчанию: отправляются коэффициенты сжатия и ID моделей, но не промпты и не код. Отключается HEADROOM_TELEMETRY=off или DO_NOT_TRACK=1.
  • Прокси — дополнительный процесс в цепочке: падение прокси останавливает агента, поэтому для продакшена нужен persistent-вариант через headroom deploy.
  • На Anthropic-пути режим cache отключает автоматическую инъекцию памяти — иначе ломается префикс кэша; память тогда включают режимом token.
оптимально
Open Source
0 ₽Apache-2.0
  • Библиотека, прокси, wrap
  • MCP-сервер и память
  • Локальное сжатие без лимитов
Enterprise
по запросуHeadroom Labs
  • Развёртывание on premise
  • Атрибуция расходов
  • Расширенная экономия
Свой замер
0 ₽headroom savings
  • Отчёт по вашему трафику
  • Панель dashboard
  • Без отправки данных наружу
Цены на 08.11.2026: открытая версия бесплатна, коммерческие условия Enterprise вендор публикует только по запросу — уточняйте на headroomlabs.ai.
Публичного прайса Enterprise нет; в README указан контакт hello@headroomlabs.ai.

Практический порядок внедрения: сначала замерьте baseline на своей задаче (сколько токенов уходит на типовую сессию), затем включите wrap на одном агенте, неделю смотрите отчёты и только после этого добавляйте сжатие в общий пайплайн. Так решение опирается на ваши цифры, а не на чужие проценты.

Итог гайда
8,8/ 10
Настройка занимает десять минут, работает локально, обратима и не добавляет задержки. Главное ограничение — экономия зависит от типа контекста: много выигрывают агенты, которые читают логи и JSON, почти ничего не получают те, кто работает с прозой.
Нет зарубежной карты для оплаты?Реклама. ООО «КАПИБАРА», ИНН 9703231520Оформить карту →
Как оплатить AI из России — разбор

Частые вопросы

Headroom отправляет мои данные на свой сервер?
Нет. Сжатие идёт в вашем процессе или в локальном прокси; оригиналы хранятся локально в CCR. Модель Kompress-v2-base скачивается один раз, дальнейшая работа возможна с HEADROOM_OFFLINE=1.
Сколько токенов экономится в реальности?
На четырёх сценариях авторов — от 21% до 57% входных токенов; на повторяющихся JSON-массивах и логах — 90%+. На прозе почти ноль, поэтому точную цифру для своего трафика даёт headroom savings.
Нужно ли менять код приложения?
Нет, если использовать прокси или wrap: агент просто ходит через локальный порт. Библиотека нужна, когда вы хотите сжимать сообщения в своём коде до вызова API.
Совместимо ли с Claude Code и Codex?
Да, это основные поддерживаемые агенты: headroom wrap claude и headroom wrap codex поднимают прокси и запускают агент с нужными настройками; отмена — headroom unwrap.
Сломает ли сжатие качество ответов?
По замерам авторов на GSM8K разницы нет, на TruthfulQA изменение в пределах погрешности, на SQuAD v2 и BFCL точность 97% при сжатии 19–32%. Для критичных задач проверяйте на своей выборке.
Что будет, если агенту понадобится сжатый фрагмент целиком?
Он запросит его инструментом headroom_retrieve: оригинал сохранён локально, поэтому сжатие не уничтожает данные, а только убирает их из отправляемого контекста.

Источники и документация

Считаете стоимость агентов?
В каталоге — обзоры агентов и моделей с единой методикой: цена, лимиты и то, как инструмент ведёт себя на длинном контексте.
Оплата AI-сервисов из РоссииКарта РФ, СБП или реселлер — рабочая страница оплаты без VPN
Перейти к оплате →