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

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

Jak to działa

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

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:

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:

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

Interfejs ContextEngine

Wymagane elementy:

assemble zwraca AssembleResult z:

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:

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:

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

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

{  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

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