headroom/plugins/openclaw

@headroom-ai/openclaw

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

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)

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

{
  "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.

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.

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. Local addresses (http://127.0.0.1:<port>, http://localhost:<port>) enable auto-start; remote URLs (https://headroom.example.com) are connect-only.
proxyPort	8787	Port used for default auto-detect/auto-start when proxyUrl is not set.
pythonPath	auto-detected	Optional Python executable override for Python fallback launcher.
autoStart	true	Auto-start a local headroom proxy if not already running (local URLs only; ignored for remote proxies)
startupTimeoutMs	20000	Time to wait for auto-started proxy to become healthy

Comparison with lossless-claw

	lossless-claw	headroom
Compaction method	LLM summarization (DAG)	Content-aware compression (zero LLM)
Cost of compaction	Tokens (LLM calls)	Zero
Best for	Long conversations	Tool-heavy agents with large outputs
Retrieval	lcm_grep, lcm_expand	headroom_retrieve (instant)

License

Apache-2.0