Контекстний рушій

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

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

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

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

# Додавання до system prompt

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

# Механізм legacy

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

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

Механізм legacy не реєструє tools і не надає 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 };
    },
  }));
}

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

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

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

# Інтерфейс ContextEngine

Обов’язкові члени:

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

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

Необов’язкові члени:

# ownsCompaction

ownsCompaction керує тим, чи залишається ввімкненою вбудована in-attempt auto-compaction Pi для запуску:

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

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

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

{
  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-рушій не вдається зареєструвати або ідентифікатор вибраного рушія неможливо розв’язати, OpenClaw не виконує автоматичний fallback; запуски завершуються помилкою, доки ви не виправите Plugin або не перемкнете plugins.slots.contextEngine назад на "legacy".
• Для розробки використовуйте openclaw plugins install -l ./my-engine, щоб зв’язати локальний каталог плагіна без копіювання.

# Пов’язане

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