--- read_when: - Вы хотите понять, как OpenClaw формирует контекст модели - Вы переключаетесь между устаревшим движком и движком плагина - Вы создаёте плагин движка контекста sidebarTitle: Context engine summary: 'Контекстный движок: подключаемая сборка контекста, Compaction и жизненный цикл субагентов' title: Контекстный движок x-i18n: generated_at: "2026-07-13T18:02:36Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 05cb5eb01f002001354dc63b77cdb86f3e9f3bc51722bd943ac20c9e1566dc60 source_path: concepts/context-engine.md workflow: 16 --- Контекстный движок управляет тем, как OpenClaw формирует контекст модели для каждого запуска: какие сообщения включать, как суммировать более раннюю историю и как управлять контекстом на границах субагентов. OpenClaw поставляется со встроенным движком `legacy` и использует его по умолчанию. Устанавливайте и выбирайте движок-плагин, только если вам требуется иное поведение при сборке, Compaction или восстановлении контекста между сеансами. ## Быстрый старт ```bash openclaw doctor # или проверьте конфигурацию напрямую: cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine' ``` Плагины контекстных движков устанавливаются так же, как и любые другие плагины OpenClaw. ```bash openclaw plugins install @martian-engineering/lossless-claw ``` ```bash openclaw plugins install -l ./my-context-engine ``` ```json5 // openclaw.json { plugins: { slots: { contextEngine: "lossless-claw", // должен соответствовать зарегистрированному идентификатору движка плагина }, entries: { "lossless-claw": { enabled: true, // Здесь указывается конфигурация плагина (см. документацию плагина) }, }, }, } ``` После установки и настройки перезапустите Gateway. Установите для `contextEngine` значение `"legacy"` (или полностью удалите ключ — `"legacy"` используется по умолчанию). ## Принцип работы При каждом запуске запроса модели в OpenClaw контекстный движок участвует в четырёх точках жизненного цикла: Вызывается при добавлении нового сообщения в сеанс. Движок может сохранить или проиндексировать сообщение в собственном хранилище данных. Вызывается перед каждым запуском модели. Движок возвращает упорядоченный набор сообщений (и необязательный `systemPromptAddition`), укладывающийся в бюджет токенов. Вызывается при заполнении контекстного окна или когда пользователь запускает `/compact`. Движок суммирует более раннюю историю, чтобы освободить место. Вызывается после завершения запуска. Движок может сохранить состояние, запустить фоновую Compaction или обновить индексы. Движки также могут реализовать необязательный метод `maintain()` для обслуживания транскрипта (безопасного перезаписывания посредством `runtimeContext.rewriteTranscriptEntries()`) после начальной загрузки, успешного хода или Compaction. Установите `info.turnMaintenanceMode: "background"`, чтобы выполнять его как отложенную задачу, а не блокировать ответ. Для встроенной оболочки Codex без ACP OpenClaw применяет тот же жизненный цикл, проецируя собранный контекст в инструкции разработчика Codex и запрос текущего хода. Codex по-прежнему управляет собственной историей потока и собственным механизмом Compaction. ### Жизненный цикл субагента (необязательно) OpenClaw вызывает два необязательных перехватчика жизненного цикла субагента: Подготавливает общее состояние контекста перед началом дочернего запуска. Перехватчик получает ключи родительского и дочернего сеансов, `contextMode` (`isolated` или `fork`), доступные идентификаторы и файлы транскрипта, а также необязательный TTL. Если он возвращает дескриптор отката, OpenClaw вызывает его, когда создание субагента завершается сбоем после успешной подготовки. Нативные создания субагентов, которые запрашивают `lightContext` и разрешаются в `contextMode="isolated"`, намеренно пропускают этот перехватчик, чтобы дочерний процесс запускался с облегчённым контекстом начальной загрузки без состояния, подготовленного контекстным движком до запуска. Выполняет очистку после завершения или удаления сеанса субагента. ### Дополнение системного запроса Метод `assemble` может возвращать строку `systemPromptAddition`. OpenClaw добавляет её в начало системного запроса для запуска. Это позволяет движкам внедрять динамические рекомендации по восстановлению контекста, инструкции по поиску или подсказки с учётом контекста без необходимости использовать статические файлы рабочей области. ## Устаревший движок Встроенный движок `legacy` сохраняет исходное поведение OpenClaw: - **Приём**: бездействие (диспетчер сеансов напрямую управляет сохранением сообщений). - **Сборка**: сквозная передача (существующий в среде выполнения конвейер очистки → проверки → ограничения управляет сборкой контекста). - **Compaction**: делегирует встроенному механизму суммирующей Compaction, который создаёт единую сводку более ранних сообщений и сохраняет последние сообщения без изменений. - **После хода**: бездействие. Устаревший движок не регистрирует инструменты и не предоставляет `systemPromptAddition`. Если `plugins.slots.contextEngine` не задан (или имеет значение `"legacy"`), этот движок используется автоматически. ## Движки-плагины Плагин может зарегистрировать контекстный движок с помощью API плагинов: ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-core"; export default function register(api) { api.registerContextEngine("my-engine", (ctx) => ({ info: { id: "my-engine", name: "My Context Engine", ownsCompaction: true, }, async ingest({ sessionId, message, isHeartbeat }) { // Сохраните сообщение в своём хранилище данных return { ingested: true }; }, async assemble({ sessionId, sessionKey, messages, tokenBudget, availableTools, citationsMode, }) { // Верните сообщения, укладывающиеся в бюджет return { messages: buildContext(messages, tokenBudget), estimatedTokens: countTokens(messages), systemPromptAddition: buildMemorySystemPromptAddition({ availableTools: availableTools ?? new Set(), citationsMode, agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }), agentSessionKey: sessionKey, }), }; }, async compact({ sessionId, force }) { // Суммируйте более ранний контекст return { ok: true, compacted: true }; }, })); } ``` Фабрика `ctx` включает необязательные значения `config`, `agentDir` и `workspaceDir`, чтобы плагины могли инициализировать состояние для отдельного агента или рабочей области до запуска первого перехватчика жизненного цикла. Затем включите его в конфигурации: ```json5 { plugins: { slots: { contextEngine: "my-engine", }, entries: { "my-engine": { enabled: true, }, }, }, } ``` ### Интерфейс ContextEngine Обязательные элементы: | Элемент | Вид | Назначение | | ------------------ | -------- | -------------------------------------------------------- | | `info` | Свойство | Идентификатор, имя и версия движка, а также признак того, управляет ли он Compaction | | `ingest(params)` | Метод | Сохранение одного сообщения | | `assemble(params)` | Метод | Формирование контекста для запуска модели (возвращает `AssembleResult`) | | `compact(params)` | Метод | Суммирование или сокращение контекста | `assemble` возвращает `AssembleResult` со следующими полями: Упорядоченные сообщения для отправки модели. Оценка движком общего количества токенов в собранном контексте. OpenClaw использует её для принятия решений о пороге Compaction и диагностической отчётности. Добавляется в начало системного запроса. Определяет, какую оценку количества токенов исполнитель использует для упреждающих проверок переполнения. По умолчанию используется `"assembled"`: для движков, не управляющих Compaction, проверяется только оценка собранного запроса. Движки, задающие `ownsCompaction: true`, самостоятельно управляют допуском запросов, поэтому OpenClaw по умолчанию пропускает общую проверку перед отправкой запроса. Устанавливайте `"preassembly_may_overflow"` только в том случае, если собранное представление может скрывать риск переполнения в исходном транскрипте; тогда исполнитель сохраняет общую проверку активной и при принятии решения об упреждающей Compaction использует максимальное значение из оценки собранного контекста и оценки истории сеанса до сборки (без ограничения окном). В любом случае модель получает именно возвращённые вами сообщения — `promptAuthority` влияет только на предварительную проверку. Необязательный жизненный цикл проекции для хостов с постоянными серверными потоками (например, app-server Codex). `mode: "thread_bootstrap"` со стабильным `epoch` предписывает хосту внедрить собранный контекст один раз за эпоху и повторно использовать серверный поток до смены эпохи вместо повторной проекции на каждом ходу. Для обычной проекции на каждом ходу не указывайте это поле. `compact` возвращает `CompactResult`. Когда Compaction изменяет идентичность активного сеанса, `result.sessionTarget` (типизированный `ContextEngineSessionTarget`, содержащий идентичность сеанса и область хранилища) определяет сеанс-преемник, который должен использоваться при следующей повторной попытке или ходе; `result.sessionId` дублирует идентификатор преемника. Необязательные элементы: | Элемент | Вид | Назначение | | ------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `bootstrap(params)` | Метод | Инициализация состояния движка для сеанса. Вызывается один раз, когда движок впервые обнаруживает сеанс (например, при импорте истории). | | `maintain(params)` | Метод | Обслуживание транскрипта после начальной загрузки, успешного хода или Compaction. Используйте `runtimeContext.rewriteTranscriptEntries()` для безопасного перезаписывания. | | `ingestBatch(params)` | Метод | Приём завершённого хода в виде пакета. Вызывается после завершения запуска и получает сразу все сообщения этого хода. | | `afterTurn(params)` | Метод | Работа жизненного цикла после запуска (сохранение состояния, запуск фоновой Compaction). | | `prepareSubagentSpawn(params)` | Метод | Настройка общего состояния дочернего сеанса перед его запуском. | | `onSubagentEnded(params)` | Метод | Очистка после завершения работы субагента. | | `dispose()` | Метод | Освобождение ресурсов. Вызывается при завершении работы Gateway или перезагрузке плагина, а не для каждого сеанса. | ### Настройки среды выполнения Перехватчики жизненного цикла, выполняемые внутри OpenClaw, получают необязательный объект `runtimeSettings`. Это версионированная внутренняя поверхность API «производитель — потребитель» только для чтения: OpenClaw формирует её для выбранного контекстного движка, а контекстный движок использует её внутри перехватчиков жизненного цикла. Она не отображается пользователям напрямую и не создаёт отдельную поверхность отчётности. - `schemaVersion`: в настоящее время `1` - `runtime`: хост OpenClaw, режим среды выполнения (`normal`, `fallback` или `degraded`) и необязательные идентификаторы тестовой обвязки/среды выполнения - `contextEngineSelection`: идентификатор выбранного движка контекста и источник выбора - `executionHost`: идентификатор и метка хоста для поверхности, вызывающей перехватчик - `model`: запрошенная модель, определённая модель, провайдер и необязательное семейство моделей - `limits`: бюджет токенов промпта и максимальное количество выходных токенов, если они известны - `diagnostics`: коды причин закрытого отказа и работы в ограниченном режиме, если они известны Поля, значения которых могут быть неизвестны, представлены как `null`; поля-дискриминаторы, такие как режим среды выполнения и источник выбора, не допускают значения null. Старые движки остаются совместимыми: если строгий устаревший движок отклоняет `runtimeSettings` как неизвестное свойство, OpenClaw повторяет вызов жизненного цикла без него вместо помещения движка в карантин. ### Требования к хосту Движки контекста могут объявлять требования к возможностям хоста в `info.hostRequirements`. OpenClaw проверяет эти требования перед началом операции и выполняет закрытый отказ с информативным сообщением об ошибке, если выбранная среда выполнения не может им соответствовать. Для запусков агента объявите `assemble-before-prompt`, когда движок должен управлять фактическим промптом модели через `assemble()`: ```ts info: { id: "my-context-engine", name: "My Context Engine", hostRequirements: { "agent-run": { requiredCapabilities: ["assemble-before-prompt"], unsupportedMessage: "Используйте встроенную среду выполнения нативного Codex или OpenClaw либо выберите устаревший движок контекста.", }, }, } ``` Запуски агента во встроенных средах выполнения нативного Codex и OpenClaw соответствуют `assemble-before-prompt`. Универсальные серверные части CLI не соответствуют этому требованию, поэтому нуждающиеся в нём движки отклоняются до запуска процесса CLI. ### Изоляция сбоев OpenClaw изолирует выбранный движок плагина от основного пути ответа. Если неустаревший движок отсутствует, не проходит проверку контракта, выбрасывает исключение при создании фабрики или из метода жизненного цикла, OpenClaw помещает этот движок в карантин на время работы текущего процесса Gateway и переводит операции движка контекста на встроенный движок `legacy`. Ошибка регистрируется вместе с неудавшейся операцией, чтобы оператор мог исправить, обновить или отключить плагин, не лишая агента возможности отвечать. Сбои требований к хосту обрабатываются иначе: когда движок объявляет, что среда выполнения не обладает необходимой возможностью, OpenClaw выполняет закрытый отказ до начала запуска. Это защищает движки, которые могли бы повредить состояние при работе на неподдерживаемом хосте. ### ownsCompaction `ownsCompaction` определяет, остаётся ли включённой для запуска встроенная автоматическая Compaction среды выполнения OpenClaw в рамках попытки: Движок управляет поведением Compaction. OpenClaw отключает для этого запуска встроенную автоматическую Compaction среды выполнения OpenClaw и универсальную предварительную проверку переполнения перед промптом, а реализация `compact()` движка отвечает за `/compact`, Compaction для восстановления после переполнения провайдера и любую упреждающую Compaction, которую она хочет выполнять в `afterTurn()`. OpenClaw по-прежнему запускает защиту от переполнения перед промптом, когда движок возвращает `promptAuthority: "preassembly_may_overflow"` из `assemble()`. Встроенная автоматическая Compaction среды выполнения OpenClaw всё ещё может выполняться во время обработки промпта, однако метод `compact()` активного движка по-прежнему вызывается для `/compact` и восстановления после переполнения. `ownsCompaction: false` **не** означает, что OpenClaw автоматически возвращается к пути Compaction устаревшего движка. Таким образом, допустимы два шаблона плагинов: Реализуйте собственный алгоритм Compaction и задайте `ownsCompaction: true`. Задайте `ownsCompaction: false` и вызывайте в `compact()` функцию `delegateCompactionToRuntime(...)` из `openclaw/plugin-sdk/core`, чтобы использовать встроенное поведение Compaction OpenClaw. Пустая реализация `compact()` небезопасна для активного движка, не управляющего Compaction, поскольку она отключает для этого слота движка обычный путь Compaction `/compact` и восстановления после переполнения. ## Справочник по конфигурации ```json5 { plugins: { slots: { // Выберите активный движок контекста. По умолчанию: "legacy". // Укажите идентификатор плагина, чтобы использовать его движок. contextEngine: "legacy", }, }, } ``` Во время выполнения слот является эксклюзивным — для конкретного запуска или операции Compaction определяется только один зарегистрированный движок контекста. Другие включённые плагины `kind: "context-engine"` всё ещё могут загружаться и выполнять свой код регистрации; `plugins.slots.contextEngine` лишь выбирает, какой идентификатор зарегистрированного движка OpenClaw определяет, когда ему требуется движок контекста. **Удаление плагина:** при удалении плагина, выбранного в данный момент как `plugins.slots.contextEngine`, OpenClaw возвращает слот к значению по умолчанию (`legacy`). Такое же поведение сброса применяется к `plugins.slots.memory`. Ручное редактирование конфигурации не требуется. ## Связь с Compaction и памятью Compaction — одна из обязанностей движка контекста. Устаревший движок делегирует её встроенному механизму суммаризации OpenClaw. Движки плагинов могут реализовывать любую стратегию Compaction (сводки на основе DAG, векторный поиск и т. д.). Плагины памяти (`plugins.slots.memory`) отделены от движков контекста. Плагины памяти обеспечивают поиск и извлечение; движки контекста управляют тем, что видит модель. Они могут работать совместно — движок контекста может использовать данные плагина памяти при сборке. Движкам плагинов, которым нужен активный путь промпта памяти, следует предпочесть `buildMemorySystemPromptAddition(...)` из `openclaw/plugin-sdk/core`, преобразующий активные разделы промпта памяти в готовый к добавлению в начало `systemPromptAddition`. Если движку требуется более низкоуровневое управление, он всё ещё может получать необработанные строки из `openclaw/plugin-sdk/memory-host-core` через `buildActiveMemoryPromptSection(...)`. Удаление старых результатов инструментов из памяти выполняется независимо от того, какой движок контекста активен. ## Советы - Используйте `openclaw doctor`, чтобы убедиться, что ваш движок загружается правильно. - При переключении движков существующие сеансы продолжают использовать свою текущую историю. Новый движок применяется к последующим запускам. - Ошибки движка регистрируются, а выбранный движок плагина помещается в карантин на время работы текущего процесса Gateway. OpenClaw возвращается к `legacy` для пользовательских запросов, чтобы ответы могли продолжаться, но неисправный плагин всё равно следует исправить, обновить, отключить или удалить. - При разработке используйте `openclaw plugins install -l ./my-engine`, чтобы подключить локальный каталог плагина без копирования. ## Связанные материалы - [Compaction](/ru/concepts/compaction) — суммаризация длинных диалогов - [Контекст](/ru/concepts/context) — как формируется контекст для запросов агента - [Архитектура плагинов](/ru/plugins/architecture) — регистрация плагинов движка контекста - [Манифест плагина](/ru/plugins/manifest) — поля манифеста плагина - [Плагины](/ru/tools/plugin) — обзор плагинов