Контекстный движок

Контекстный движок управляет тем, как OpenClaw формирует контекст модели для каждого запуска: какие сообщения включать, как суммировать более раннюю историю и как управлять контекстом на границах субагентов.

OpenClaw поставляется со встроенным движком legacy и использует его по умолчанию. Устанавливайте и выбирайте движок-плагин, только если вам требуется иное поведение при сборке, Compaction или восстановлении контекста между сеансами.

Быстрый старт

openclaw doctor# или проверьте конфигурацию напрямую:cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

// openclaw.json{  plugins: {    slots: {      contextEngine: "lossless-claw", // должен соответствовать зарегистрированному идентификатору движка плагина    },    entries: {      "lossless-claw": {        enabled: true,        // Здесь указывается конфигурация плагина (см. документацию плагина)      },    },  },}

Принцип работы

При каждом запуске запроса модели в OpenClaw контекстный движок участвует в четырёх точках жизненного цикла:

Движки также могут реализовать необязательный метод maintain() для обслуживания транскрипта (безопасного перезаписывания посредством runtimeContext.rewriteTranscriptEntries()) после начальной загрузки, успешного хода или Compaction. Установите info.turnMaintenanceMode: "background", чтобы выполнять его как отложенную задачу, а не блокировать ответ.

Для встроенной оболочки Codex без ACP OpenClaw применяет тот же жизненный цикл, проецируя собранный контекст в инструкции разработчика Codex и запрос текущего хода. Codex по-прежнему управляет собственной историей потока и собственным механизмом Compaction.

Жизненный цикл субагента (необязательно)

OpenClaw вызывает два необязательных перехватчика жизненного цикла субагента:

Дополнение системного запроса

Метод assemble может возвращать строку systemPromptAddition. OpenClaw добавляет её в начало системного запроса для запуска. Это позволяет движкам внедрять динамические рекомендации по восстановлению контекста, инструкции по поиску или подсказки с учётом контекста без необходимости использовать статические файлы рабочей области.

Устаревший движок

Встроенный движок legacy сохраняет исходное поведение OpenClaw:

• Приём: бездействие (диспетчер сеансов напрямую управляет сохранением сообщений).
• Сборка: сквозная передача (существующий в среде выполнения конвейер очистки → проверки → ограничения управляет сборкой контекста).
• Compaction: делегирует встроенному механизму суммирующей Compaction, который создаёт единую сводку более ранних сообщений и сохраняет последние сообщения без изменений.
• После хода: бездействие.

Устаревший движок не регистрирует инструменты и не предоставляет systemPromptAddition.

Если plugins.slots.contextEngine не задан (или имеет значение "legacy"), этот движок используется автоматически.

Движки-плагины

Плагин может зарегистрировать контекстный движок с помощью API плагинов:

  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, чтобы плагины могли инициализировать состояние для отдельного агента или рабочей области до запуска первого перехватчика жизненного цикла.

Затем включите его в конфигурации:

{  plugins: {    slots: {      contextEngine: "my-engine",    },    entries: {      "my-engine": {        enabled: true,      },    },  },}

Интерфейс ContextEngine

Обязательные элементы:

assemble возвращает AssembleResult со следующими полями:

compact возвращает CompactResult. Когда Compaction изменяет идентичность активного сеанса, result.sessionTarget (типизированный ContextEngineSessionTarget, содержащий идентичность сеанса и область хранилища) определяет сеанс-преемник, который должен использоваться при следующей повторной попытке или ходе; result.sessionId дублирует идентификатор преемника.

Необязательные элементы:

Настройки среды выполнения

Перехватчики жизненного цикла, выполняемые внутри 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():

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 в рамках попытки:

Таким образом, допустимы два шаблона плагинов:

Пустая реализация compact() небезопасна для активного движка, не управляющего Compaction, поскольку она отключает для этого слота движка обычный путь Compaction /compact и восстановления после переполнения.

Справочник по конфигурации

{  plugins: {    slots: {      // Выберите активный движок контекста. По умолчанию: "legacy".      // Укажите идентификатор плагина, чтобы использовать его движок.      contextEngine: "legacy",    },  },}

Связь с Compaction и памятью

Советы

• Используйте openclaw doctor, чтобы убедиться, что ваш движок загружается правильно.
• При переключении движков существующие сеансы продолжают использовать свою текущую историю. Новый движок применяется к последующим запускам.
• Ошибки движка регистрируются, а выбранный движок плагина помещается в карантин на время работы текущего процесса Gateway. OpenClaw возвращается к legacy для пользовательских запросов, чтобы ответы могли продолжаться, но неисправный плагин всё равно следует исправить, обновить, отключить или удалить.
• При разработке используйте openclaw plugins install -l ./my-engine, чтобы подключить локальный каталог плагина без копирования.

Связанные материалы

• Compaction — суммаризация длинных диалогов
• Контекст — как формируется контекст для запросов агента
• Архитектура плагинов — регистрация плагинов движка контекста
• Манифест плагина — поля манифеста плагина
• Плагины — обзор плагинов