---
read_when:
    - Ви хочете зрозуміти, як OpenClaw збирає контекст моделі
    - Ви перемикаєтеся між застарілим механізмом і механізмом на основі плагіна
    - Ви створюєте плагін механізму контексту
summary: 'Механізм контексту: підключуване збирання контексту, компактування та життєвий цикл субагентів'
title: Механізм контексту
x-i18n:
    generated_at: "2026-04-07T08:01:17Z"
    model: gpt-5.4
    provider: openai
    source_hash: e8290ac73272eee275bce8e481ac7959b65386752caa68044d0c6f3e450acfb1
    source_path: concepts/context-engine.md
    workflow: 15
---

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

**Механізм контексту** керує тим, як OpenClaw будує контекст моделі для кожного запуску.
Він вирішує, які повідомлення включати, як підсумовувати давнішу історію та
як керувати контекстом через межі субагентів.

OpenClaw постачається з вбудованим механізмом `legacy`. Плагіни можуть реєструвати
альтернативні механізми, які замінюють активний життєвий цикл механізму контексту.

## Швидкий старт

Перевірте, який механізм активний:

```bash
openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
```

### Встановлення плагіна механізму контексту

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

```bash
# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine
```

Потім увімкніть плагін і виберіть його як активний механізм у своїй конфігурації:

```json5
// 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)
      },
    },
  },
}
```

Після встановлення та налаштування перезапустіть gateway.

Щоб повернутися до вбудованого механізму, встановіть `contextEngine` у `"legacy"` (або
повністю видаліть цей ключ — `"legacy"` використовується за замовчуванням).

## Як це працює

Щоразу, коли OpenClaw запускає запит моделі, механізм контексту бере участь
у чотирьох точках життєвого циклу:

1. **Ingest** — викликається, коли до сесії додається нове повідомлення. Механізм
   може зберегти або проіндексувати повідомлення у власному сховищі даних.
2. **Assemble** — викликається перед кожним запуском моделі. Механізм повертає впорядкований
   набір повідомлень (і необов’язковий `systemPromptAddition`), які вміщаються в
   бюджет токенів.
3. **Compact** — викликається, коли вікно контексту заповнене або коли користувач запускає
   `/compact`. Механізм підсумовує давнішу історію, щоб звільнити місце.
4. **After turn** — викликається після завершення запуску. Механізм може зберегти стан,
   запустити фонове компактування або оновити індекси.

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

Наразі OpenClaw викликає один хук життєвого циклу субагента:

- **onSubagentEnded** — очищення після завершення сесії субагента або її прибирання.

Хук `prepareSubagentSpawn` є частиною інтерфейсу для майбутнього використання, але
середовище виконання поки що його не викликає.

### Додавання до системного промпту

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

## Механізм legacy

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

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

Механізм legacy не реєструє інструменти й не надає `systemPromptAddition`.

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

## Механізми на основі плагінів

Плагін може зареєструвати механізм контексту за допомогою API плагінів:

```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    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 };
    },
  }));
}
```

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

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

### Інтерфейс ContextEngine

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

| Елемент            | Тип      | Призначення                                              |
| ------------------ | -------- | -------------------------------------------------------- |
| `info`             | Властивість | Ідентифікатор механізму, назва, версія та чи керує він компактуванням |
| `ingest(params)`   | Метод    | Зберегти одне повідомлення                               |
| `assemble(params)` | Метод    | Побудувати контекст для запуску моделі (повертає `AssembleResult`) |
| `compact(params)`  | Метод    | Підсумувати/скоротити контекст                           |

`assemble` повертає `AssembleResult` з такими полями:

- `messages` — упорядковані повідомлення для надсилання моделі.
- `estimatedTokens` (обов’язкове, `number`) — оцінка механізмом загальної кількості
  токенів у зібраному контексті. OpenClaw використовує це для рішень щодо порогу компактування
  та діагностичної звітності.
- `systemPromptAddition` (необов’язкове, `string`) — додається на початок системного промпту.

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

| Елемент                        | Тип    | Призначення                                                                                                      |
| ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `bootstrap(params)`           | Метод  | Ініціалізувати стан механізму для сесії. Викликається один раз, коли механізм уперше бачить сесію (наприклад, імпорт історії). |
| `ingestBatch(params)`         | Метод  | Прийняти завершений хід пакетом. Викликається після завершення запуску з усіма повідомленнями цього ходу одразу. |
| `afterTurn(params)`           | Метод  | Робота життєвого циклу після запуску (збереження стану, запуск фонового компактування).                         |
| `prepareSubagentSpawn(params)`| Метод  | Налаштувати спільний стан для дочірньої сесії.                                                                   |
| `onSubagentEnded(params)`     | Метод  | Очистити ресурси після завершення субагента.                                                                     |
| `dispose()`                   | Метод  | Звільнити ресурси. Викликається під час вимкнення gateway або перезавантаження плагіна — не для кожної сесії.   |

### ownsCompaction

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

- `true` — механізм керує поведінкою компактування. OpenClaw вимикає вбудоване в Pi
  автоматичне компактування для цього запуску, а реалізація `compact()` механізму
  відповідає за `/compact`, компактування для відновлення після переповнення та будь-яке проактивне
  компактування, яке він хоче виконувати в `afterTurn()`.
- `false` або не встановлено — вбудоване автоматичне компактування Pi все ще може виконуватися під час
  виконання промпту, але метод `compact()` активного механізму все одно викликається для
  `/compact` і відновлення після переповнення.

`ownsCompaction: false` **не** означає, що OpenClaw автоматично повертається
до шляху компактування механізму legacy.

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

- **Режим керування** — реалізуйте власний алгоритм компактування й встановіть
  `ownsCompaction: true`.
- **Режим делегування** — встановіть `ownsCompaction: false` і зробіть так, щоб `compact()` викликав
  `delegateCompactionToRuntime(...)` з `openclaw/plugin-sdk/core`, щоб використовувати
  вбудовану поведінку компактування OpenClaw.

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

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

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

Слот є ексклюзивним під час виконання — лише один зареєстрований механізм контексту
визначається для певного запуску або операції компактування. Інші увімкнені
плагіни `kind: "context-engine"` все одно можуть завантажуватися й виконувати свій код
реєстрації; `plugins.slots.contextEngine` лише вибирає, який зареєстрований ідентифікатор механізму
OpenClaw визначає, коли йому потрібен механізм контексту.

## Зв’язок із компактуванням і пам’яттю

- **Compaction** — це одна з відповідальностей механізму контексту. Механізм legacy
  делегує вбудованому підсумовуванню OpenClaw. Механізми на основі плагінів можуть реалізовувати
  будь-яку стратегію компактування (DAG-резюме, vector retrieval тощо).
- **Плагіни пам’яті** (`plugins.slots.memory`) відокремлені від механізмів контексту.
  Плагіни пам’яті забезпечують пошук/retrieval; механізми контексту контролюють, що
  бачить модель. Вони можуть працювати разом — механізм контексту може використовувати дані
  плагіна пам’яті під час збирання. Механізмам на основі плагінів, яким потрібен активний шлях
  промпту пам’яті, слід віддавати перевагу `buildMemorySystemPromptAddition(...)` з
  `openclaw/plugin-sdk/core`, який перетворює активні секції промпту пам’яті
  на готовий до додавання на початок `systemPromptAddition`. Якщо механізму потрібен контроль
  нижчого рівня, він усе одно може отримувати сирі рядки з
  `openclaw/plugin-sdk/memory-host-core` через
  `buildActiveMemoryPromptSection(...)`.
- **Обрізання сесії** (скорочення старих результатів інструментів у пам’яті) усе ще виконується
  незалежно від того, який механізм контексту активний.

## Поради

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

Див. також: [Компактування](/uk/concepts/compaction), [Контекст](/uk/concepts/context),
[Плагіни](/uk/tools/plugin), [Маніфест плагіна](/uk/plugins/manifest).

## Пов’язане

- [Контекст](/uk/concepts/context) — як будується контекст для ходів агента
- [Архітектура плагінів](/uk/plugins/architecture) — реєстрація плагінів механізму контексту
- [Компактування](/uk/concepts/compaction) — підсумовування довгих розмов
