Механізм контексту

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

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

Швидкий початок

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()) після початкового завантаження, успішного ходу або ущільнення. Установіть info.turnMaintenanceMode: "background", щоб виконувати його як відкладену роботу, а не блокувати відповідь.

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

Життєвий цикл субагента (необов’язково)

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

Доповнення системного запиту

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

Застарілий рушій

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

• Приймання: не виконує жодних дій (диспетчер сеансів безпосередньо керує збереженням повідомлень).
• Формування: передає дані без змін (формуванням контексту керує наявний у середовищі виконання конвеєр очищення → перевірки → обмеження).
• Ущільнення: делегує роботу вбудованому ущільненню шляхом узагальнення, яке створює єдине резюме давніших повідомлень і залишає останні повідомлення без змін.
• Після ходу: не виконує жодних дій.

Застарілий рушій не реєструє інструменти й не надає 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. Коли ущільнення змінює ідентичність активного сеансу, 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 визначає, чи залишається ввімкненим для запуску вбудоване автоматичне ущільнення середовища виконання OpenClaw у межах спроби:

Отже, існує два коректні шаблони плагінів:

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

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

{  plugins: {    slots: {      // Виберіть активний рушій контексту. Типове значення: "legacy".      // Установіть ідентифікатор плагіна, щоб використовувати рушій плагіна.      contextEngine: "legacy",    },  },}

Зв’язок з ущільненням і пам’яттю

Поради

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

Пов’язані матеріали

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