Silnik kontekstu

silnik kontekstu kontroluje, jak OpenClaw buduje kontekst modelu dla każdego uruchomienia: które komunikaty uwzględnić, jak podsumowywać starszą historię oraz jak zarządzać kontekstem między granicami subagentów.

OpenClaw zawiera wbudowany silnik legacy i domyślnie go używa - większość użytkowników nigdy nie musi tego zmieniać. Zainstaluj i wybierz silnik Plugin tylko wtedy, gdy chcesz uzyskać inne zachowanie składania, Compaction lub 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 monit modelu, silnik kontekstu uczestniczy w czterech punktach cyklu życia:

Dla dołączonego harnessu Codex innego niż ACP OpenClaw stosuje ten sam cykl życia, projektując złożony kontekst do instrukcji deweloperskich Codex oraz monitu bieżącej tury. Codex nadal zarządza własną natywną historią wątku i natywnym kompaktorem.

# Cykl życia subagenta (opcjonalnie)

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

# Dodatek do monitu systemowego

Metoda assemble może zwrócić ciąg systemPromptAddition. OpenClaw poprzedza nim monit systemowy dla uruchomienia. Dzięki temu silniki mogą wstrzykiwać dynamiczne wskazówki przywoływania, instrukcje pobierania lub podpowiedzi zależne od kontekstu bez wymagania statycznych plików obszaru roboczego.

# Silnik legacy

Wbudowany silnik legacy zachowuje pierwotne zachowanie OpenClaw:

• Pobieranie: brak operacji (menedżer sesji bezpośrednio obsługuje utrwalanie komunikatów).
• Składanie: przekazanie bez zmian (istniejący potok sanitize → validate → limit w środowisku uruchomieniowym obsługuje składanie kontekstu).
• Compaction: deleguje do wbudowanej Compaction podsumowującej, która tworzy pojedyncze podsumowanie starszych komunikatów i zachowuje najnowsze komunikaty bez zmian.
• Po turze: 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, aby Pluginy mogły zainicjalizować stan dla agenta lub obszaru roboczego przed uruchomieniem pierwszego haka 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 aktywną transkrypcję, result.sessionId i result.sessionFile identyfikują następną sesję, której musi użyć kolejna próba lub tura.

Opcjonalne elementy:

# ownsCompaction

ownsCompaction kontroluje, czy wbudowana w Pi automatyczna Compaction w ramach próby pozostaje włączona dla uruchomienia:

Oznacza to, że istnieją dwa poprawne wzorce Plugin:

Puste compact() jest niebezpieczne dla aktywnego silnika nieposiadającego Compaction, ponieważ wyłącza normalną ścieżkę Compaction /compact i odzyskiwania po przepełnieniu dla tego slotu silnika.

# Odniesienie do konfiguracji

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

# Relacja z Compaction i pamięcią

# Wskazówki

• Użyj openclaw doctor, aby zweryfikować, że silnik ładuje się poprawnie.
• Jeśli przełączasz silniki, istniejące sesje kontynuują pracę z bieżącą historią. Nowy silnik przejmuje obsługę przyszłych uruchomień.
• Błędy silnika są rejestrowane i pokazywane w diagnostyce. Jeśli silnik Plugin nie zarejestruje się albo nie da się rozwiązać identyfikatora wybranego silnika, OpenClaw nie przełączy się automatycznie na rozwiązanie zapasowe; uruchomienia będą kończyć się niepowodzeniem, dopóki nie naprawisz pluginu albo nie przełączysz plugins.slots.contextEngine z powrotem na "legacy".
• Podczas developmentu 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 - rejestrowanie pluginów silnika kontekstu
• Manifest Plugin - pola manifestu pluginu
• Pluginy - omówienie pluginów