Механизм контекста

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

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

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

openclaw doctor# or inspect config directly: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", // must match the plugin's registered engine id    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin-specific config goes here (see the plugin's docs)      },    },  },}

Как это работает

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

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

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

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

Добавление к системному промпту

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

Движок legacy

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

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

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

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

Plugin-движки

Plugin может зарегистрировать движок контекста с помощью Plugin 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 }) {      // Store the message in your data store      return { ingested: true };    },     async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {      // Return messages that fit the budget      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,        }),      };    },     async compact({ sessionId, force }) {      // Summarize older context      return { ok: true, compacted: true };    },  }));}

Фабрика ctx включает необязательные значения config, agentDir и workspaceDir, чтобы Plugins могли инициализировать состояние для агента или рабочей области до запуска первого хука жизненного цикла.

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

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

Интерфейс ContextEngine

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

assemble возвращает AssembleResult с:

compact возвращает CompactResult. Когда Compaction ротирует активный транскрипт, result.sessionId и result.sessionFile идентифицируют следующую сессию, которую должен использовать следующий повтор или ход.

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

Настройки runtime

Хуки жизненного цикла, которые выполняются внутри OpenClaw, получают необязательный объект runtimeSettings. Это версионированная, доступная только для чтения внутренняя поверхность API producer/consumer: OpenClaw создает ее для выбранного движка контекста, а движок контекста потребляет ее внутри хуков жизненного цикла. Она не отображается напрямую пользователям и не создает отдельную поверхность отчетности.

• schemaVersion: сейчас 1
• runtime: хост OpenClaw, режим runtime (normal, fallback или degraded) и необязательные идентификаторы харнесса/runtime
• contextEngineSelection: идентификатор выбранного движка контекста и источник выбора
• executionHost: идентификатор хоста и метка поверхности, вызывающей хук
• model: запрошенная модель, разрешенная модель, провайдер и необязательное семейство моделей
• limits: бюджет токенов промпта и максимальное число выходных токенов, если известно
• diagnostics: закрытые коды причин fallback и degraded, если известны

Поля, которые могут быть неизвестны, представлены как null; поля-дискриминаторы, такие как режим runtime и источник выбора, остаются не-nullable. Старые движки остаются совместимыми: если строгий устаревший движок отклоняет runtimeSettings как неизвестное свойство, OpenClaw повторяет вызов жизненного цикла без него, а не помещает движок в карантин.

Требования к хосту

Движки контекста могут объявлять требования к возможностям хоста в info.hostRequirements. OpenClaw проверяет эти требования перед запуском операции и закрыто завершает ее с понятной ошибкой, когда выбранный runtime не может им соответствовать.

Для запусков агента объявляйте assemble-before-prompt, когда движок должен управлять фактическим промптом модели через assemble():

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

Нативные запуски агента Codex и встроенного агента OpenClaw удовлетворяют assemble-before-prompt. Универсальные CLI-бэкенды - нет, поэтому движки, которым это требуется, отклоняются до запуска CLI-процесса.

Изоляция сбоев

OpenClaw изолирует выбранный Plugin-движок от основного пути ответа. Если движок не legacy отсутствует, не проходит проверку контракта, выбрасывает исключение при создании фабрики или выбрасывает исключение из метода жизненного цикла, OpenClaw помещает этот движок в карантин для текущего процесса Gateway и понижает работу движка контекста до встроенного движка legacy. Ошибка записывается в журнал вместе с неудачной операцией, чтобы оператор мог исправить, обновить или отключить Plugin без того, чтобы агент перестал отвечать.

Ошибки требований хоста отличаются: когда движок объявляет, что среда выполнения не имеет необходимой возможности, OpenClaw завершает выполнение с отказом до запуска прогона. Это защищает движки, которые повредили бы состояние при запуске в неподдерживаемом хосте.

ownsCompaction

ownsCompaction управляет тем, остается ли встроенная в среду выполнения OpenClaw автоматическая Compaction внутри попытки включенной для прогона:

Это означает, что есть два допустимых шаблона Plugin:

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

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

{  plugins: {    slots: {      // Select the active context engine. Default: "legacy".      // Set to a plugin id to use a plugin engine.      contextEngine: "legacy",    },  },}

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

Советы

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

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

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