Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Add controlled proxy autostart and unsafe-install guidance
JerrettDavis777ffeb716bb
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.mdindex e4249446e..be929a535 100644--- a/plugins/openclaw/README.md+++ b/plugins/openclaw/README.md@@ -6,9 +6,11 @@ Context compression plugin for [OpenClaw](https://github.com/openclaw/openclaw).```bashpip install "headroom-ai[proxy]"-openclaw plugins install headroom-ai/openclaw+openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw```+This plugin auto-starts `headroom proxy` when needed. OpenClaw treats process-launching plugins as unsafe by default, so `--dangerously-force-unsafe-install` is required.+## Configure```json@@ -29,11 +31,11 @@ openclaw plugins install headroom-ai/openclaw}```-`proxyUrl` is required and must be localhost (`127.0.0.1` or `localhost`). The plugin never starts processes and only connects to the configured local proxy.+`proxyUrl` must be localhost (`127.0.0.1` or `localhost`). If the proxy is not running, the plugin will try to start it with `headroom proxy --host ... --port ...`.## Required Proxy Setup-Run Headroom proxy yourself before launching OpenClaw.+Optional: run Headroom proxy yourself before launching OpenClaw.Python install:@@ -65,6 +67,8 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored| Option | Default | Description ||--------|---------|-------------|| `proxyUrl` | required | URL of an already running Headroom proxy (`http://127.0.0.1:<port>` or `http://localhost:<port>`) |+| `autoStart` | `true` | Auto-start `headroom proxy` if not already running |+| `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |## Comparison with lossless-clawdiff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.jsonindex 3a0dd76db..71ff11da1 100644--- a/plugins/openclaw/openclaw.plugin.json+++ b/plugins/openclaw/openclaw.plugin.json@@ -16,6 +16,16 @@"proxyUrl": {"type": "string","pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?$"+ },+ "autoStart": {+ "type": "boolean",+ "default": true+ },+ "startupTimeoutMs": {+ "type": "integer",+ "minimum": 1000,+ "maximum": 120000,+ "default": 20000}}},diff --git a/plugins/openclaw/package-lock.json b/plugins/openclaw/package-lock.jsonindex f0b7e2281..fff7c48d9 100644--- a/plugins/openclaw/package-lock.json+++ b/plugins/openclaw/package-lock.json@@ -12,13 +12,11 @@"headroom-ai": "^0.1.0"},"devDependencies": {+ "@types/node": "^22.10.0","tsup": "^8.0.0","typescript": "^5.5.0","vitest": "^2.0.0"},- "engines": {- "node": ">=20"- },"peerDependencies": {"openclaw": "*"},@@ -866,6 +864,16 @@"dev": true,"license": "MIT"},+ "node_modules/@types/node": {+ "version": "22.19.15",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.15.tgz",+ "integrity": "sha512-F0R/h2+dsy5wJAUe3tAU6oqa2qbWY5TpNfL/RGmo1y38hiyO1w3x2jPtt76wmuaJI4DQnOBu21cNXQ2STIUUWg==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "undici-types": "~6.21.0"+ }+ },"node_modules/@vitest/expect": {"version": "2.1.9","resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.1.9.tgz",@@ -1847,6 +1855,13 @@"dev": true,"license": "MIT"},+ "node_modules/undici-types": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",+ "dev": true,+ "license": "MIT"+ },"node_modules/vite": {"version": "5.4.21","resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",diff --git a/plugins/openclaw/package.json b/plugins/openclaw/package.jsonindex b1b348299..a1229e2b4 100644--- a/plugins/openclaw/package.json+++ b/plugins/openclaw/package.json@@ -28,6 +28,7 @@}},"devDependencies": {+ "@types/node": "^22.10.0","tsup": "^8.0.0","typescript": "^5.5.0","vitest": "^2.0.0"diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.tsindex f8b5be8aa..cba6f88f9 100644--- a/plugins/openclaw/src/proxy-manager.ts+++ b/plugins/openclaw/src/proxy-manager.ts@@ -2,13 +2,16 @@* Manages connectivity to an externally managed Headroom proxy.** Security model:- * - No process execution+ * - Optional local process execution to auto-start Headroom proxy* - No environment variable access* - Localhost-only network access (127.0.0.1 / localhost)*/+import { spawn } from "node:child_process";export interface ProxyManagerConfig {proxyUrl?: string;+ autoStart?: boolean;+ startupTimeoutMs?: number;}export interface ProxyManagerLogger {@@ -67,6 +70,24 @@ export class ProxyManager {);}+ if (this.config.autoStart !== false) {+ this.logger.info(`No proxy detected at ${url}; attempting to auto-start Headroom proxy...`);+ await this.startHeadroomProxy(url);++ const startedProbe = await waitForHeadroomProxy(+ url,+ this.config.startupTimeoutMs ?? 20_000,+ );+ if (startedProbe.reachable && startedProbe.isHeadroom) {+ this.proxyUrl = url;+ this.logger.info(`Headroom proxy started and reachable at ${url}`);+ return url;+ }+ throw new Error(+ `Attempted to start Headroom proxy, but it was not reachable at ${url} (${startedProbe.reason ?? "unknown"}).`,+ );+ }+throw new Error(`Headroom proxy not reachable at ${url}. Ensure the proxy is running first.`);}@@ -82,6 +103,24 @@ export class ProxyManager {}// --- Internal ---++ private async startHeadroomProxy(proxyUrl: string): Promise<void> {+ const parsed = new URL(proxyUrl);+ const host = parsed.hostname;+ const port = parsed.port || "80";++ try {+ const child = spawn("headroom", ["proxy", "--host", host, "--port", port], {+ detached: true,+ stdio: "ignore",+ });+ child.unref();+ } catch (error) {+ throw new Error(+ `Failed to spawn headroom proxy command. Ensure "headroom" is installed and on PATH. (${String(error)})`,+ );+ }+ }}export function normalizeAndValidateProxyUrl(proxyUrl: string): string {@@ -143,3 +182,15 @@ export async function probeHeadroomProxy(proxyUrl: string): Promise<ProxyProbeRe};}}++async function waitForHeadroomProxy(proxyUrl: string, timeoutMs: number): Promise<ProxyProbeResult> {+ const start = Date.now();+ while (Date.now() - start < timeoutMs) {+ const result = await probeHeadroomProxy(proxyUrl);+ if (result.reachable && result.isHeadroom) {+ return result;+ }+ await new Promise((resolve) => setTimeout(resolve, 500));+ }+ return probeHeadroomProxy(proxyUrl);+}diff --git a/plugins/openclaw/tsconfig.json b/plugins/openclaw/tsconfig.jsonindex 2095c82f5..c745b7b2d 100644--- a/plugins/openclaw/tsconfig.json+++ b/plugins/openclaw/tsconfig.json@@ -4,6 +4,7 @@"module": "ESNext","moduleResolution": "bundler","lib": ["ES2022", "DOM"],+ "types": ["node"],"strict": true,"esModuleInterop": true,"skipLibCheck": true,