OpenClaw

OpenClaw is an open-source terminal agent gateway. Compresh integrates as a Plugin SDK hook that fires before every model call — your agent's context is compressed transparently without any agent-side discipline.

Hook (Plugin SDK) TESTED

@compresh/openclaw-hook registers on OpenClaw's before_prompt_build Plugin SDK event. Every turn, your conversation history is sent to a locally-running compresh-mcp server which applies Compresh compression and returns a Compresh-compressed view appended to the system prompt. The protection-zone tail (last 2/4/8 turns) stays raw in the message list.

Requirements

OpenClaw 2026.5.0 or later
Node.js 18+ (OpenClaw's runtime)
Python 3.10+ with compresh-mcp installed via pipx
A Compresh API key — optional: without one, compression runs locally and free (open-source tulbase). To unlock TUL 2.0: compresh-mcp login --google (or --github), or sign up at compre.sh/signup

Install

1. Install compresh-mcp (the Python MCP server that does the compression work):

pipx install compresh-mcp
# verify it's on PATH:
which compresh-mcp

2. Install the OpenClaw plugin:

openclaw plugins install npm:@compresh/openclaw-hook

3. Add Compresh config to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "compresh": {
        "hooks": { "allowConversationAccess": true },
        "config": {
          "apiKey": "sk-comp_...",
          "protectionMode": "balanced",
          "minMessages": 6
        }
      }
    }
  }
}

The hooks.allowConversationAccess: true line is required. Non-bundled plugins cannot register raw conversation hooks without it. apiKey is optional — leave it out and the plugin compresses locally with free tulbase.

4. Restart the gateway so the plugin's register() runs:

openclaw gateway restart

(One command on every platform — it drives the installed launchd/systemd/Scheduled-Task service. Don't chain stop + start as a restart substitute.)

Config hot-reload alone is not enough — the plugin's register() function only runs at gateway startup. This is the most common install pitfall.

Verify

Start a session with openclaw tui and have a conversation that goes past the minMessages threshold (default 6):

openclaw tui
# ...have at least 6 turns of conversation, then check the runtime log.
# The gateway's per-turn log lives under /tmp/openclaw/, NOT
# ~/Library/Logs/openclaw/gateway.log (that file only holds the boot +
# plugin-register lines).

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep '\[compresh\]'

# expected (one before_prompt_build + one llm_output per turn):
# [compresh] register v0.3.8 transport=mcp logger=present
# [compresh] mcp-connected bin=compresh-mcp
# [compresh] before_prompt_build sid=agent:main:main applied tier=trial \
#            compressed=122/126 saving=75513chars
# [compresh] llm_output sid=agent:main:main input=10 output=192 \
#            cacheRead=0 cacheWrite=62679 total=62881 budget=200000

Use openclaw tui, not openclaw chat

OpenClaw's chat command currently double-renders each assistant reply in the scrollback (upstream issue, unrelated to Compresh — the server transcript is correct, only the display repeats). openclaw tui renders cleanly. Either way Compresh runs exactly one compression call per turn.

Config options

Key	Default	Notes
`apiKey`	—	Compresh API key (`sk-comp_…`). Optional — without it compression is free local tulbase; with it, paid models get TUL 2.0.
`protectionMode`	`balanced`	`aggressive` (2 raw turns), `balanced` (4), `conservative` (8).
`minMessages`	`6`	Skip compression below this turn count. Saves bandwidth on short chats.
`binPath`	`compresh-mcp`	Override path to the `compresh-mcp` binary (rarely needed).
`providerHint`	from context	Provider name for telemetry. Default: derived from the active model.
`modelHint`	from context	Model name for telemetry.
`timeoutMs`	`10000`	Max time the hook waits for compression before passing through.

MCP (compresh-mcp via stdio) TESTED

The hook above already uses MCP under the hood — the plugin starts compresh-mcp as a subprocess and calls the compress tool. If you'd rather register compresh-mcp as a regular agent-callable MCP tool (so the model decides when to compress), add it to OpenClaw's MCP section instead of using the hook.

For most use cases the hook path is preferred — it's deterministic and doesn't depend on the model choosing to call a tool.

Proxy SOON

Direct base-URL swap to api.compre.sh is blocked inside OpenClaw by the SSRF allowlist in extensions/anthropic/openclaw.plugin.json. A custom Compresh provider plugin is under investigation but not yet shipped.

Why a hook (not a proxy)?

Your provider API key (Claude / GPT / etc.) stays inside OpenClaw and is never sent to Compresh. Only the conversation transcript reaches Compresh — and only when an API key is configured. Hooks fit teams that don't want to route provider keys through a third party.

Pricing

Compresh's free tier covers small conversations without budget; the paid TUL 2.0 enhancement (query-aware retrieval) runs server-side at api.compre.sh/v1/tul2 with a savings-share rate (Starter 30%, Pro Quarterly 20%, Pro Semi-Annual 16%, Pro Annual 12%). New signups get $30 free credit. See compre.sh/pricing.

Troubleshooting

The hook installs but never fires

You probably hot-reloaded the config without restarting the gateway. register() only runs at gateway startup — see the install step 4 above.

compresh-mcp shows an onboarding screen instead of compressing

The plugin couldn't pass COMPRESH_API_KEY to the subprocess. Confirm your apiKey is in plugins.entries.compresh.config in ~/.openclaw/openclaw.json, then restart the gateway.

Log lines from compresh-mcp leak into the chat TUI

Fixed in compresh-mcp ≥ 0.3.3 — logs now default to WARNING (INFO sits behind --verbose). Upgrade with pipx upgrade compresh-mcp and restart the gateway. Functionality was never affected.