Рушій контексту

<contextengine_docs_i18n_input> Рушій контексту керує тим, як OpenClaw формує контекст моделі для кожного запуску: які повідомлення включати, як підсумовувати давнішу історію та як керувати контекстом на межах підагентів.

OpenClaw постачається з вбудованим рушієм legacy і використовує його типово - більшості користувачів ніколи не потрібно це змінювати. Встановлюйте й вибирайте рушій Plugin лише тоді, коли вам потрібна інша поведінка складання, 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", // 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 harness Codex OpenClaw застосовує той самий життєвий цикл, проєктуючи зібраний контекст в інструкції розробника Codex і запит поточного ходу. Codex і надалі керує власною нативною історією треду та нативним компактором.

Життєвий цикл підагентів (необов'язково)

OpenClaw викликає два необов'язкові hooks життєвого циклу підагентів:

Додавання системного prompt

Метод assemble може повернути рядок systemPromptAddition. OpenClaw додає його на початок системного prompt для запуску. Це дає рушіям змогу ін'єктувати динамічні вказівки для пригадування, інструкції retrieval або контекстно-залежні підказки без потреби в статичних файлах workspace.

Рушій legacy

Вбудований рушій legacy зберігає початкову поведінку OpenClaw:

• Ingest: no-op (менеджер сеансу напряму обробляє збереження повідомлень).
• Assemble: pass-through (наявний pipeline sanitize → validate → limit у runtime обробляє складання контексту).
• Compact: делегує вбудованій summarization compaction, яка створює єдиний підсумок давніших повідомлень і залишає нещодавні повідомлення без змін.
• After turn: no-op.

Рушій legacy не реєструє інструменти й не надає systemPromptAddition.

Коли plugins.slots.contextEngine не задано (або задано як "legacy"), цей рушій використовується автоматично.

Рушії Plugin

Plugin може зареєструвати рушій контексту за допомогою API Plugin:

 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 };    },  }));}

Factory ctx містить необов'язкові значення config, agentDir і workspaceDir, щоб Plugin могли ініціалізувати стан для кожного агента або workspace до запуску першого hook життєвого циклу.

Потім увімкніть його в конфігурації:

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

Інтерфейс ContextEngine

Обов'язкові members:

assemble повертає AssembleResult з:

compact повертає CompactResult. Коли Compaction ротирує активний транскрипт, result.sessionId і result.sessionFile ідентифікують наступний сеанс, який має використовувати наступна повторна спроба або хід.

Необов'язкові members:

Налаштування runtime

Hooks життєвого циклу, що виконуються всередині OpenClaw, отримують необов'язковий об'єкт runtimeSettings. Це версіонована, внутрішня, read-only поверхня API producer/consumer: OpenClaw створює її для вибраного рушія контексту, а рушій контексту споживає її всередині hooks життєвого циклу. Вона не рендериться напряму користувачам і не створює окремої поверхні звітування.

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

Поля, які можуть бути невідомими, подаються як null; discriminator-поля, такі як режим runtime і джерело вибору, залишаються non-nullable. Старіші рушії залишаються сумісними: якщо strict legacy рушій відхиляє runtimeSettings як невідому властивість, OpenClaw повторює виклик життєвого циклу без нього, замість того щоб ізолювати рушій у карантин.

Вимоги хоста

Рушії контексту можуть оголошувати вимоги до можливостей хоста в info.hostRequirements. OpenClaw перевіряє ці вимоги перед запуском операції та fail closed з описовою помилкою, коли вибраний runtime не може їх задовольнити.

Для запусків агентів оголошуйте assemble-before-prompt, коли рушій має керувати фактичним 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. Generic CLI backends не задовольняють, тому рушії, які цього вимагають, відхиляються до запуску CLI process.

Ізоляція збоїв

</contextengine_docs_i18n_input>

OpenClaw ізолює вибраний рушій плагіна від основного шляху відповіді. Якщо незастарілий рушій відсутній, не проходить перевірку контракту, викидає помилку під час створення фабрики або викидає помилку з методу життєвого циклу, OpenClaw поміщає цей рушій у карантин для поточного процесу Gateway і понижує роботу context-engine до вбудованого рушія legacy. Помилка записується в журнал разом із невдалою операцією, щоб оператор міг виправити, оновити або вимкнути плагін без того, щоб агент замовк.

Збої вимог хоста відрізняються: коли рушій оголошує, що середовище виконання не має потрібної можливості, OpenClaw завершує роботу закрито до запуску виконання. Це захищає рушії, які могли б пошкодити стан, якби працювали в непідтримуваному хості.

ownsCompaction

ownsCompaction керує тим, чи залишається вбудоване в середовище виконання OpenClaw автоматичне стиснення всередині спроби ввімкненим для виконання:

Це означає, що існують два допустимі шаблони плагінів:

Порожній compact() небезпечний для активного рушія без володіння, тому що він вимикає звичайний шлях стиснення /compact і відновлення після переповнення для цього слота рушія.

Довідник конфігурації

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

Зв’язок зі стисненням і пам’яттю

Поради

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

Пов’язане

• Compaction - підсумовування довгих розмов
• Контекст - як будується контекст для ходів агента
• Архітектура Plugin - реєстрація плагінів рушія контексту
• Маніфест Plugin - поля маніфесту плагіна
• Plugins - огляд плагінів