Files
123XieCand123XieC d077263012 fix(openclaw): preserve assistant text blocks when tool arguments change (#4829)
## Description

OpenClaw history can contain text on both sides of an assistant tool
call. If the compression response changes the call arguments while
leaving the wire text intact, restoring that message currently moves
both pieces of text ahead of the call and joins them into a single
block.

## Type of Change

- [x] Bug fix

## Changes Made

- Compare the returned assistant text with the text sent for that
message. Keep the original blocks when the text matches, then apply the
changed arguments to the matching tool call.
- Extend the assemble regression to check the order and content of both
text blocks, the signed thinking block, and the updated tool call.

## Testing

- [x] Regression and existing OpenClaw tests pass.
- [x] Manual testing performed.

### Test Output

```text
cd plugins/openclaw
npm test          # 11 files, 162 tests passed
npm run typecheck # passed
npm run build     # passed
git diff --check  # passed
```

The repository commit hooks and Rust formatting check passed. The full
local pre-push suite stopped at Rust dependency resolution after the
registry fetch stalled. I used the hook's documented push override for
this TypeScript-only change. The verification above covers the changed
plugin.

## Real Behavior Proof

- Environment: macOS arm64, Node 22.22.2, built OpenClaw plugin with the
pinned JavaScript SDK, and a Node HTTP server listening on loopback. The
payload was synthetic and did not need a model.
- Exact command / steps: Run `npm run build` in `plugins/openclaw` on
base `9f2cc01` and the patched tree. In Node, import
`HeadroomContextEngine` from the built `dist/index.js`. Start a loopback
server that answers `GET /v1/retrieve/stats` with `{"store":{}}`. For
`POST /v1/compress`, echo the submitted messages and set the first tool
call's argument string to `{"id":7}`. Return `tokens_before: 100`,
`tokens_after: 25`, and `tokens_saved: 75`. Create the engine with that
`proxyUrl`, `autoStart: false`, and `minContextChars: 0`. Await
`ensureProxyUrl()`, then call `assemble()` with one assistant message
whose blocks are signed thinking, text `Checking.`, a `lookup` call with
ID `lookup-1` and arguments `{id: 7, notes: "fixture ".repeat(80)}`, and
text `Awaiting result.`.
- Observed result: the SDK sent one actual compression request in both
runs. Base returned `thinking, text("Checking.Awaiting result."),
toolCall({id:7})`. The patch returned `thinking, text("Checking."),
toolCall({id:7}), text("Awaiting result.")`. The signature and call ID
were preserved, and the engine reported 25 tokens in both runs.
- Not tested: a remote proxy, model calls, or an OpenClaw host process.
The runtime proof exercised the built plugin and SDK over HTTP with a
deterministic compression response.

## Runtime Rollout Safety

- Rollout-managed feature(s): OpenClaw context restoration.
- Minimum rollout channel: existing plugin channel.
- Stable/default behavior changed: text block placement is preserved
when only assistant tool arguments change.
- Kill switch / disable path: existing OpenClaw plugin enablement.
- Unsafe override required: none.
- Qualification impact: OpenClaw plugin suite and loopback verification
above.
- Rollback path: revert the commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

This is a small correction to the restoration path introduced by #3826.
AI assistance was used to investigate, implement, and verify the change.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4829"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

Co-authored-by: 123XieC <323077714+123XieC@users.noreply.github.com>
2026-11-16 23:05:24 -06:00
..

@headroom-ai/openclaw

Context compression plugin for OpenClaw. Compresses tool outputs, code, logs, and structured data — 70-90% token savings with zero LLM calls.

Tool-call normalization preserves provider metadata, including thought signatures, when restoring assistant turns after compression.

Install

Recommended one-command setup:

headroom wrap openclaw

Manual install:

pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw

This plugin can auto-start a local headroom proxy when needed. OpenClaw treats process-launching plugins as unsafe by default, so --dangerously-force-unsafe-install is required even if you plan to use a remote proxy (the capability is declared at install time).

Local Development Install (Detection-Friendly)

Building from source requires Node.js ^22.18.0 || ^24.11.0 || >=26.0.0 for the tsup 9 toolchain. Use a supported Node release before running npm ci and npm run build. This is a source-build requirement; the published plugin uses the Node runtime supported by your OpenClaw host and does not run tsup during plugin loading.

If you are testing from this repo, run npm install/build from the plugin directory so local launcher detection aligns with runtime paths. These linked installs are supported:

cd plugins/openclaw
npm install
npm run build
openclaw plugins install --dangerously-force-unsafe-install --link .
openclaw plugins install --dangerously-force-unsafe-install --link dist

From the repo root, install the plugin directory explicitly:

openclaw plugins install --dangerously-force-unsafe-install --link ./plugins/openclaw

Or, from inside dist/:

cd plugins/openclaw/dist
openclaw plugins install --dangerously-force-unsafe-install --link .

Why this matters:

  • The plugin checks launchers in this order: PATH -> local npm bin -> global npm -> python.
  • "local npm bin" means plugins/openclaw/node_modules/.bin/headroom relative to the source checkout.
  • Using --link dist (or --link . from dist/) still keeps runtime code adjacent to the checkout, and launcher detection falls back to PATH/global/python if a local npm bin is not present under the installed root.
  • plugins/openclaw also carries a no-op hook shim so OpenClaw's hook-pack fallback treats the path as valid instead of emitting a misleading package.json missing openclaw.hooks warning.
  • If you install from a .tgz, local npm bin may not exist in the installed extension and detection will fall back to PATH/global/python.

Configure

Install automatically selects the contextEngine slot for headroom on current OpenClaw releases. If you need to switch back manually, set plugins.slots.contextEngine to "legacy" or another engine id.

{
  "plugins": {
    "entries": {
      "headroom": {
        "enabled": true,
        "config": {
          "proxyUrl": "http://127.0.0.1:8787"
        }
      }
    },
    "slots": {
      "contextEngine": "headroom"
    }
  }
}

proxyUrl is optional. If omitted, the plugin auto-detects on localhost:

  • http://127.0.0.1:<proxyPort>
  • http://localhost:<proxyPort>

Default proxyPort is 8787. Auto-start is opt-in; in production, prefer an externally managed proxy such as systemd with proxyUrl set and autoStart: false.

Upstream gateway routing

By default, the plugin also rewrites the built-in openai-codex provider base URL to a verified active Headroom proxy at runtime. That means Codex provider traffic flows through Headroom, so /stats can observe real upstream request and cache activity instead of only local context compression.

This does not replace Headroom's existing Codex routing rules. The proxy already decides between api.openai.com and chatgpt.com/backend-api/codex/responses based on ChatGPT auth. The plugin change only points OpenClaw's provider config at the active proxy in memory and preserves the rest of the provider config.

You can also route additional provider ids such as anthropic, github-copilot, google, or openrouter through the same proxy:

{
  "plugins": {
    "entries": {
      "headroom": {
        "enabled": true,
        "config": {
          "gatewayProviderIds": ["openai-codex", "anthropic", "github-copilot", "google", "openrouter"]
        }
      }
    }
  }
}

When gatewayProviderIds is set, it becomes the exact list the plugin rewrites in memory for the current gateway process.

For convenience, the plugin also accepts family aliases:

  • codex -> openai-codex
  • claude -> anthropic
  • copilot -> github-copilot
  • gemini -> google

When OpenClaw has already resolved a provider's upstream baseUrl, the plugin preserves protocol-specific path segments while swapping only the origin. That keeps provider families on the right proxy route:

  • Codex / ChatGPT backend: /backend-api
  • OpenAI-compatible providers: /v1 or /api/v1
  • GitHub Copilot Claude-family models: /anthropic
  • Gemini: /v1beta

GitHub Copilot is a special case because OpenClaw can route it through either OpenAI Responses or Anthropic Messages depending on the selected model. The plugin only rewrites Copilot when OpenClaw has already resolved the upstream baseUrl, so it can preserve the correct /v1 or /anthropic path instead of guessing.

The routing is intentionally lightweight and reversible:

  • the plugin does not persist provider baseUrl changes back to openclaw.json
  • disabling the plugin, clearing gatewayProviderIds, or restarting without Headroom restores OpenClaw's normal provider resolution
  • if you want durable provider rewrites, use headroom wrap openclaw instead of relying on plugin install side effects

If you need to disable that behavior:

{
  "plugins": {
    "entries": {
      "headroom": {
        "enabled": true,
        "config": {
          "routeCodexViaProxy": false
        }
      }
    }
  }
}

Local proxy (auto-start)

When proxyUrl points to localhost (or is omitted), the plugin will auto-start headroom proxy if no running proxy is detected. Launch order:

  1. headroom from PATH
  2. local npm bin (node_modules/.bin/headroom)
  3. global npm bin
  4. Python module (python -m headroom.cli proxy ...)

If pythonPath is set, it is tried first in the Python fallback step.

Docker-native Headroom installs intentionally leave pythonPath unset so this launcher order prefers the installed host headroom wrapper on PATH, which then runs Headroom in Docker.

Remote proxy (connect-only)

Point proxyUrl to any reachable Headroom instance:

{
  "config": {
    "proxyUrl": "https://headroom.example.com:8787"
  }
}

Remote URLs are connect-only — the plugin probes the URL at startup and fails fast if the proxy is not reachable. No subprocess is spawned for remote addresses.

Manual Proxy Setup

If you prefer to manage the proxy yourself (or are running a remote instance), start it before launching OpenClaw:

Python install:

pip install "headroom-ai[proxy]"
headroom proxy --host 127.0.0.1 --port 8787

NPM install:

npm install -g headroom-ai
headroom proxy --host 127.0.0.1 --port 8787

How It Works

Every time OpenClaw assembles context for the model, the plugin compresses tool outputs and large messages:

  • JSON arrays (tool outputs, search results) — statistical selection keeps anomalies, errors, boundaries
  • Code — AST-aware compression via tree-sitter
  • Logs — pattern deduplication, keeps errors and boundaries
  • Text — ML-based token compression

Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored and the agent gets a headroom_retrieve tool to access full details when needed.

Configuration Options

Option Default Description
proxyUrl auto-detected Optional URL of a Headroom proxy. Configured URLs are probe-gated before provider routing. Remote URLs (https://headroom.example.com) are connect-only.
proxyPort 8787 Port used for default auto-detect and optional local auto-start when proxyUrl is not set.
pythonPath auto-detected Optional Python executable override for Python fallback launcher.
autoStart false Opt-in auto-start for a local headroom proxy if not already running (local URLs only; ignored for remote proxies). Keep false when systemd owns the proxy.
startupTimeoutMs 20000 Time to wait for auto-started proxy to become healthy
requestTimeoutMs 2000 Maximum milliseconds to wait for a single compress() call. The SDK aborts the request at this deadline and the original messages are used as a fallback.
minContextChars 800 Skip proxy compression below this approximate 200-token context floor. Large single tool results still qualify; set to 0 to disable the gate.
circuitBreakerThreshold 3 Number of consecutive assemble() failures before the circuit breaker opens and all requests bypass the proxy. Counts every way the proxy can fail a call — connection errors, timeouts, 5xx responses, and results that come back with no token count. Prevents cascading failures when the proxy is unhealthy.
circuitBreakerCooldownMs 60000 How long (ms) the circuit breaker stays open after the threshold is reached. After the cool-down the breaker resets automatically and the next assemble() call re-probes the proxy by attempting a real compression.
routeCodexViaProxy true Rewrite OpenClaw's built-in openai-codex provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom.
gatewayProviderIds [] Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases codex, claude, copilot, and gemini are also accepted. When set, this overrides the default openai-codex routing list.
announceCompression true Adds a static, cache-stable notice to the system prompt the first time a session compresses more than 100 tokens, then keeps it unchanged for the rest of the session. Set to false to guarantee Headroom never modifies the system prompt.
commitLogPath $HEADROOM_WORKSPACE_DIR/openclaw/commit-log.json, else ~/.headroom/openclaw/commit-log.json Where the plugin records each turn OpenClaw has accepted (one small marker file per turn, in a sibling commit-log.d/ directory), so a retried commit is answered as a duplicate even after a restart. Must be on a writable filesystem: on a read-only root (common in Kubernetes), point this or HEADROOM_WORKSPACE_DIR at a writable volume. While commits fail, OpenClaw 2026.9.9+ runs each later turn of the session on its legacy context path.

Comparison with lossless-claw

lossless-claw headroom
Compaction method LLM summarization (DAG) OpenClaw native compaction (delegated)
Cost of compaction Tokens (LLM calls) OpenClaw configuration-dependent
Best for Long conversations Tool-heavy agents with large outputs
Retrieval lcm_grep, lcm_expand headroom_retrieve (instant)

License

Apache-2.0