Fundamentals

Silnik kontekstu

Silnik kontekstu kontroluje sposób, w jaki OpenClaw buduje kontekst modelu dla każdego uruchomienia: które wiadomości uwzględnić, jak podsumowywać starszą historię i jak zarządzać kontekstem na granicach subagentów.

OpenClaw zawiera wbudowany silnik legacy i używa go domyślnie - większość użytkowników nigdy nie musi tego zmieniać. Zainstaluj i wybierz silnik Plugin tylko wtedy, gdy potrzebujesz innego składania, Compaction lub zachowania przywoływania między sesjami.

Szybki start

Check which engine is active

bash

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

Install a plugin engine

Pluginy silnika kontekstu instaluje się tak jak każdy inny Plugin OpenClaw.

From npm

bash

openclaw plugins install @martian-engineering/lossless-claw

From a local path

bash

openclaw plugins install -l ./my-context-engine

Enable and select the 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)      },    },  },}

Po instalacji i konfiguracji uruchom ponownie gateway.

Switch back to legacy (optional)

Ustaw contextEngine na "legacy" (albo całkowicie usuń klucz - "legacy" jest wartością domyślną).

Jak to działa

Za każdym razem, gdy OpenClaw uruchamia prompt modelu, silnik kontekstu bierze udział w czterech punktach cyklu życia:

1. Ingest

Wywoływane, gdy do sesji dodawana jest nowa wiadomość. Silnik może przechować lub zindeksować wiadomość we własnym magazynie danych.

2. Assemble

Wywoływane przed każdym uruchomieniem modelu. Silnik zwraca uporządkowany zestaw wiadomości (oraz opcjonalne systemPromptAddition), które mieszczą się w budżecie tokenów.

3. Compact

Wywoływane, gdy okno kontekstu jest pełne albo gdy użytkownik uruchamia /compact. Silnik podsumowuje starszą historię, aby zwolnić miejsce.

4. After turn

Wywoływane po zakończeniu uruchomienia. Silnik może utrwalić stan, uruchomić Compaction w tle albo zaktualizować indeksy.

Dla dołączonego harnessu Codex bez ACP OpenClaw stosuje ten sam cykl życia, odwzorowując złożony kontekst na instrukcje deweloperskie Codex i prompt bieżącej tury. Codex nadal posiada własną natywną historię wątku i natywny compactor.

Cykl życia subagenta (opcjonalnie)

OpenClaw wywołuje dwa opcjonalne hooki cyklu życia subagenta:

prepareSubagentSpawnmethod

Przygotowuje współdzielony stan kontekstu przed rozpoczęciem uruchomienia podrzędnego. Hook otrzymuje klucze sesji nadrzędnej/podrzędnej, contextMode (isolated albo fork), dostępne identyfikatory/pliki transkryptów oraz opcjonalny TTL. Jeśli zwróci uchwyt wycofania, OpenClaw wywoła go, gdy uruchomienie subagenta nie powiedzie się po udanym przygotowaniu. Natywne uruchomienia subagentów, które żądają lightContext i rozwiązywane są do contextMode="isolated", celowo pomijają ten hook, aby element podrzędny startował z lekkiego kontekstu bootstrap bez zarządzanego przez silnik kontekstu stanu sprzed uruchomienia.

onSubagentEndedmethod

Czyści zasoby po zakończeniu lub wymieceniu sesji subagenta.

Dodatek do promptu systemowego

Metoda assemble może zwrócić ciąg systemPromptAddition. OpenClaw dokleja go na początku promptu systemowego dla uruchomienia. Pozwala to silnikom wstrzykiwać dynamiczne wskazówki przywoływania, instrukcje pobierania lub podpowiedzi zależne od kontekstu bez wymagania statycznych plików workspace.

Silnik legacy

Wbudowany silnik legacy zachowuje oryginalne zachowanie OpenClaw:

Ingest: brak operacji (menedżer sesji bezpośrednio obsługuje utrwalanie wiadomości).
Assemble: przekazanie bez zmian (istniejący pipeline oczyszczania → walidacji → limitowania w runtime obsługuje składanie kontekstu).
Compact: deleguje do wbudowanej podsumowującej Compaction, która tworzy pojedyncze podsumowanie starszych wiadomości i pozostawia najnowsze wiadomości bez zmian.
After turn: brak operacji.

Silnik legacy nie rejestruje narzędzi ani nie udostępnia systemPromptAddition.

Gdy plugins.slots.contextEngine nie jest ustawione (albo jest ustawione na "legacy"), ten silnik jest używany automatycznie.

Silniki Plugin

Plugin może zarejestrować silnik kontekstu za pomocą 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 };    },  }));}

Fabryka ctx zawiera opcjonalne wartości config, agentDir i workspaceDir, dzięki czemu Pluginy mogą inicjalizować stan per agent lub per workspace przed uruchomieniem pierwszego hooka cyklu życia.

Następnie włącz go w konfiguracji:

json5

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

Interfejs ContextEngine

Wymagane elementy:

Element	Rodzaj	Cel
`info`	Właściwość	Identyfikator silnika, nazwa, wersja oraz informacja, czy zarządza Compaction
`ingest(params)`	Metoda	Przechowuje pojedynczą wiadomość
`assemble(params)`	Metoda	Buduje kontekst dla uruchomienia modelu (zwraca `AssembleResult`)
`compact(params)`	Metoda	Podsumowuje/redukuje kontekst

assemble zwraca AssembleResult z:

messagesMessage[]required

Uporządkowane wiadomości do wysłania do modelu.

estimatedTokensnumberrequired

Oszacowanie silnika dotyczące łącznej liczby tokenów w złożonym kontekście. OpenClaw używa tego do decyzji o progach Compaction i raportowania diagnostycznego.

systemPromptAdditionstring

Doklejane na początku promptu systemowego.

promptAuthority"assembled" | "preassembly_may_overflow"

Kontroluje, którego oszacowania tokenów runner używa do wyprzedzających kontroli przepełnienia. Domyślnie jest to "assembled", co oznacza, że dla silników, które nie zarządzają Compaction, sprawdzane jest tylko oszacowanie złożonego promptu. Silniki ustawiające ownsCompaction: true samodzielnie zarządzają dopuszczaniem własnych promptów, więc OpenClaw domyślnie pomija ogólną kontrolę przed promptem. Ustaw "preassembly_may_overflow" tylko wtedy, gdy złożony widok może ukrywać ryzyko przepełnienia w bazowym transkrypcie; runner utrzymuje wtedy ogólną kontrolę aktywną i bierze maksimum z oszacowania złożonego oraz oszacowania historii sesji sprzed składania (bez okna), decydując, czy wyprzedzająco wykonać Compaction. W każdym przypadku wiadomości, które zwracasz, nadal są tym, co widzi model - promptAuthority wpływa tylko na kontrolę wstępną.

compact zwraca CompactResult. Gdy Compaction rotuje aktywny transkrypt, result.sessionId i result.sessionFile identyfikują następczą sesję, której musi użyć następna próba lub tura.

Opcjonalne elementy:

Element	Rodzaj	Cel
`bootstrap(params)`	Metoda	Inicjalizuje stan silnika dla sesji. Wywoływane raz, gdy silnik po raz pierwszy widzi sesję (np. import historii).
`ingestBatch(params)`	Metoda	Pobiera zakończoną turę jako partię. Wywoływane po zakończeniu uruchomienia, ze wszystkimi wiadomościami z tej tury naraz.
`afterTurn(params)`	Metoda	Praca cyklu życia po uruchomieniu (utrwalenie stanu, uruchomienie Compaction w tle).
`prepareSubagentSpawn(params)`	Metoda	Konfiguruje współdzielony stan dla sesji podrzędnej przed jej rozpoczęciem.
`onSubagentEnded(params)`	Metoda	Czyści zasoby po zakończeniu subagenta.
`dispose()`	Metoda	Zwalnia zasoby. Wywoływane podczas zamykania gateway lub przeładowania Plugin - nie per sesja.

Ustawienia runtime

Hooki cyklu życia uruchamiane wewnątrz OpenClaw otrzymują opcjonalny obiekt runtimeSettings. Jest to wersjonowana, wewnętrzna, tylko do odczytu powierzchnia API producenta/konsumenta: OpenClaw wytwarza ją dla wybranego silnika kontekstu, a silnik kontekstu zużywa ją wewnątrz hooków cyklu życia. Nie jest renderowana bezpośrednio użytkownikom i nie tworzy dedykowanej powierzchni raportowania.

schemaVersion: obecnie 1
runtime: host OpenClaw, tryb runtime (normal, fallback albo degraded) oraz opcjonalne identyfikatory harnessu/runtime
contextEngineSelection: identyfikator wybranego silnika kontekstu i źródło wyboru
executionHost: identyfikator hosta i etykieta powierzchni wywołującej hook
model: żądany model, rozwiązany model, dostawca i opcjonalna rodzina modelu
limits: budżet tokenów promptu i maksymalna liczba tokenów wyjściowych, gdy znane
diagnostics: zamknięte kody powodów fallback i degradacji, gdy znane

Pola, które mogą być nieznane, są reprezentowane jako null; pola dyskryminujące, takie jak tryb runtime i źródło wyboru, pozostają nie-nullowalne. Starsze silniki pozostają zgodne: jeśli ścisły silnik legacy odrzuci runtimeSettings jako nieznaną właściwość, OpenClaw ponowi wywołanie cyklu życia bez niego, zamiast kwarantannować silnik.

Wymagania hosta

Silniki kontekstu mogą deklarować wymagania dotyczące możliwości hosta w info.hostRequirements. OpenClaw sprawdza te wymagania przed rozpoczęciem operacji i zamyka ją błędem z opisem, gdy wybrany runtime nie może ich spełnić.

Dla uruchomień agentów zadeklaruj assemble-before-prompt, gdy silnik musi kontrolować rzeczywisty prompt modelu przez 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.",    },  },}

Natywne uruchomienia agentów Codex i osadzone uruchomienia agentów OpenClaw spełniają assemble-before-prompt. Ogólne backendy CLI nie spełniają tego wymagania, więc silniki, które go wymagają, są odrzucane przed uruchomieniem procesu CLI.

Izolacja awarii

OpenClaw izoluje wybrany silnik pluginu od głównej ścieżki odpowiedzi. Jeśli silnika innego niż starszy brakuje, nie przechodzi walidacji kontraktu, zgłasza wyjątek podczas tworzenia fabryki albo zgłasza wyjątek z metody cyklu życia, OpenClaw poddaje ten silnik kwarantannie dla bieżącego procesu Gateway i degraduje pracę silnika kontekstu do wbudowanego silnika legacy. Błąd jest logowany wraz z nieudaną operacją, aby operator mógł naprawić, zaktualizować lub wyłączyć plugin bez wyciszenia agenta.

Niepowodzenia wymagań hosta są inne: gdy silnik deklaruje, że środowisko uruchomieniowe nie ma wymaganej funkcji, OpenClaw kończy działanie w trybie zamkniętym przed rozpoczęciem przebiegu. Chroni to silniki, które uszkodziłyby stan, gdyby działały na nieobsługiwanym hoście.

ownsCompaction

ownsCompaction kontroluje, czy wbudowana w środowisko uruchomieniowe OpenClaw automatyczna kompakcja w ramach próby pozostaje włączona dla przebiegu:

ownsCompaction: true

Silnik odpowiada za zachowanie kompakcji. OpenClaw wyłącza wbudowaną w środowisko uruchomieniowe OpenClaw automatyczną kompakcję i ogólny wstępny sprawdzian przepełnienia przed promptem dla tego przebiegu, a implementacja compact() silnika odpowiada za /compact, kompakcję odzyskiwania po przepełnieniu dostawcy oraz każdą proaktywną kompakcję, którą chce wykonać w afterTurn(). OpenClaw nadal uruchamia zabezpieczenie przed przepełnieniem przed promptem, gdy silnik zwraca promptAuthority: "preassembly_may_overflow" z assemble().

ownsCompaction: false lub nieustawione

Wbudowana w środowisko uruchomieniowe OpenClaw automatyczna kompakcja może nadal działać podczas wykonywania promptu, ale metoda compact() aktywnego silnika nadal jest wywoływana dla /compact i odzyskiwania po przepełnieniu.

Oznacza to, że istnieją dwa prawidłowe wzorce pluginów:

Tryb przejmowania odpowiedzialności

Zaimplementuj własny algorytm kompakcji i ustaw ownsCompaction: true.

Tryb delegowania

Ustaw ownsCompaction: false i spraw, aby compact() wywoływało delegateCompactionToRuntime(...) z openclaw/plugin-sdk/core, aby użyć wbudowanego zachowania kompakcji OpenClaw.

Puste compact() jest niebezpieczne dla aktywnego silnika, który nie przejmuje odpowiedzialności, ponieważ wyłącza normalną ścieżkę kompakcji /compact i odzyskiwania po przepełnieniu dla tego slotu silnika.

Odniesienie konfiguracji

json5

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

Relacja do kompakcji i pamięci

Compaction

Compaction jest jedną z odpowiedzialności silnika kontekstu. Silnik legacy deleguje do wbudowanego podsumowywania OpenClaw. Silniki pluginów mogą implementować dowolną strategię kompakcji (podsumowania DAG, wyszukiwanie wektorowe itd.).

Pluginy pamięci

Pluginy pamięci (plugins.slots.memory) są oddzielone od silników kontekstu. Pluginy pamięci zapewniają wyszukiwanie/odzyskiwanie; silniki kontekstu kontrolują, co widzi model. Mogą działać razem - silnik kontekstu może używać danych pluginu pamięci podczas składania. Silniki pluginów, które chcą korzystać z aktywnej ścieżki promptu pamięci, powinny preferować buildMemorySystemPromptAddition(...) z openclaw/plugin-sdk/core, które konwertuje aktywne sekcje promptu pamięci na gotowe do poprzedzenia systemPromptAddition. Jeśli silnik potrzebuje niższego poziomu kontroli, nadal może pobierać surowe wiersze z openclaw/plugin-sdk/memory-host-core przez buildActiveMemoryPromptSection(...).

Przycinanie sesji

Przycinanie starych wyników narzędzi w pamięci nadal działa niezależnie od tego, który silnik kontekstu jest aktywny.

Wskazówki

Użyj openclaw doctor, aby sprawdzić, czy silnik ładuje się poprawnie.
Jeśli przełączasz silniki, istniejące sesje kontynuują pracę ze swoją bieżącą historią. Nowy silnik przejmuje przyszłe przebiegi.
Błędy silnika są logowane, a wybrany silnik pluginu jest poddawany kwarantannie dla bieżącego procesu Gateway. OpenClaw wraca do legacy dla tur użytkownika, aby odpowiedzi mogły być kontynuowane, ale nadal należy naprawić, zaktualizować, wyłączyć lub odinstalować uszkodzony plugin.
Podczas programowania użyj openclaw plugins install -l ./my-engine, aby połączyć lokalny katalog pluginu bez kopiowania.

Powiązane

Compaction - podsumowywanie długich rozmów
Kontekst - jak kontekst jest budowany dla tur agenta
Architektura pluginów - rejestrowanie pluginów silnika kontekstu
Manifest pluginu - pola manifestu pluginu
Pluginy - przegląd pluginów

Was this useful?

Silnik kontekstu

Szybki start

Check which engine is active

Install a plugin engine

From npm

From a local path

Enable and select the engine

Switch back to legacy (optional)

Jak to działa

Cykl życia subagenta (opcjonalnie)

Dodatek do promptu systemowego

Silnik legacy

Silniki Plugin

Interfejs ContextEngine

Ustawienia runtime

Wymagania hosta

Izolacja awarii

ownsCompaction

Tryb przejmowania odpowiedzialności

Tryb delegowania

Odniesienie konfiguracji

Relacja do kompakcji i pamięci

Wskazówki

Powiązane

On this page

Molty