From ec2c33b7cddfaf85d9a440cf874a1a2db5352777 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Tue, 7 Apr 2026 17:56:15 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@12331f04631f51ff51ab9a003799eeda17bcd353 --- .openclaw-sync/source.json | 4 +- docs/.generated/config-baseline.sha256 | 4 +- docs/concepts/compaction.md | 65 +++++++++++++++++++ docs/gateway/configuration-reference.md | 2 + .../session-management-compaction.md | 15 +++++ 5 files changed, 86 insertions(+), 4 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 0f086d82d..16f59c666 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "e973275fd0fd4b51bfbfe9c5e91be3fc736308a0", - "syncedAt": "2026-04-07T15:06:37.086Z" + "sha": "12331f04631f51ff51ab9a003799eeda17bcd353", + "syncedAt": "2026-04-07T17:56:14.539Z" } diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 68654c94d..818ba987e 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/docs/.generated/config-baseline.sha256 @@ -1,4 +1,4 @@ -af24bd5a2a86e8bb481302211b35c440e82636585c46f57050648c0290b1d4ee config-baseline.json -73bda77ebf7d70609c57f394655332536eb5ff55516a6b7db06243bd4e8e44a5 config-baseline.core.json +f7b342080a730da84d1ac84a888e9506d24ee7ce7ec6ec6c0cc4f1897fabcde3 config-baseline.json +c3dd9fb8a0059dba411c4d88a6b84ca28af1e0b1925c669058ef9f38c6d2718b config-baseline.core.json d22f4414b79ee03d896e58d875c80523bcc12303cbacb1700261e6ec73945187 config-baseline.channel.json d42cee3dea4668bdb7daf6ff5e6f87f326fdef56a8c3716d73079b92cab6e7b2 config-baseline.plugin.json diff --git a/docs/concepts/compaction.md b/docs/concepts/compaction.md index 1ebc0e78f..977d50cc7 100644 --- a/docs/concepts/compaction.md +++ b/docs/concepts/compaction.md @@ -41,6 +41,71 @@ Before compacting, OpenClaw automatically reminds the agent to save important notes to [memory](/concepts/memory) files. This prevents context loss. +Use the `agents.defaults.compaction` setting in your `openclaw.json` to configure compaction behavior (mode, target tokens, etc.). +Compaction summarization preserves opaque identifiers by default (`identifierPolicy: "strict"`). You can override this with `identifierPolicy: "off"` or provide custom text with `identifierPolicy: "custom"` and `identifierInstructions`. + +You can optionally specify a different model for compaction summarization via `agents.defaults.compaction.model`. This is useful when your primary model is a local or small model and you want compaction summaries produced by a more capable model. The override accepts any `provider/model-id` string: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "openrouter/anthropic/claude-sonnet-4-6" + } + } + } +} +``` + +This also works with local models, for example a second Ollama model dedicated to summarization or a fine-tuned compaction specialist: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "model": "ollama/llama3.1:8b" + } + } + } +} +``` + +When unset, compaction uses the agent’s primary model. + +## Pluggable compaction providers + +Plugins can register a custom compaction provider via `registerCompactionProvider()` on the plugin API. When a provider is registered and configured, OpenClaw delegates summarization to it instead of the built-in LLM pipeline. + +To use a registered provider, set the provider id in your config: + +```json +{ + "agents": { + "defaults": { + "compaction": { + "provider": "my-provider" + } + } + } +} +``` + +Setting a `provider` automatically forces `mode: "safeguard"`. Providers receive the same compaction instructions and identifier-preservation policy as the built-in path, and OpenClaw still preserves recent-turn and split-turn suffix context after provider output. If the provider fails or returns an empty result, OpenClaw falls back to built-in LLM summarization. + +## Auto-compaction (default on) + +When a session nears or exceeds the model’s context window, OpenClaw triggers auto-compaction and may retry the original request using the compacted context. + +You’ll see: + +- `🧹 Auto-compaction complete` in verbose mode +- `/status` showing `🧹 Compactions: ` + +Before compaction, OpenClaw can run a **silent memory flush** turn to store +durable notes to disk. See [Memory](/concepts/memory) for details and config. + ## Manual compaction Type `/compact` in any chat to force a compaction. Add instructions to guide diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 481086f53..236e9c15b 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1160,6 +1160,7 @@ Periodic heartbeat runs. defaults: { compaction: { mode: "safeguard", // default | safeguard + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom @@ -1180,6 +1181,7 @@ Periodic heartbeat runs. ``` - `mode`: `default` or `safeguard` (chunked summarization for long histories). See [Compaction](/concepts/compaction). +- `provider`: id of a registered compaction provider plugin. When set, the provider's `summarize()` is called instead of built-in LLM summarization. Falls back to built-in on failure. Setting a provider forces `mode: "safeguard"`. See [Compaction](/concepts/compaction). - `timeoutSeconds`: maximum seconds allowed for a single compaction operation before OpenClaw aborts it. Default: `900`. - `identifierPolicy`: `strict` (default), `off`, or `custom`. `strict` prepends built-in opaque identifier retention guidance during compaction summarization. - `identifierInstructions`: optional custom identifier-preservation text used when `identifierPolicy=custom`. diff --git a/docs/reference/session-management-compaction.md b/docs/reference/session-management-compaction.md index 1b22a8cc6..236001aab 100644 --- a/docs/reference/session-management-compaction.md +++ b/docs/reference/session-management-compaction.md @@ -275,6 +275,21 @@ Implementation: `ensurePiCompactionReserveTokens()` in `src/agents/pi-settings.t --- +## Pluggable compaction providers + +Plugins can register a compaction provider via `registerCompactionProvider()` on the plugin API. When `agents.defaults.compaction.provider` is set to a registered provider id, the safeguard extension delegates summarization to that provider instead of the built-in `summarizeInStages` pipeline. + +- `provider`: id of a registered compaction provider plugin. Leave unset for default LLM summarization. +- Setting a `provider` forces `mode: "safeguard"`. +- Providers receive the same compaction instructions and identifier-preservation policy as the built-in path. +- The safeguard still preserves recent-turn and split-turn suffix context after provider output. +- If the provider fails or returns an empty result, OpenClaw falls back to built-in LLM summarization automatically. +- Abort/timeout signals are re-thrown (not swallowed) to respect caller cancellation. + +Source: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. + +--- + ## User-visible surfaces You can observe compaction and session state via: