Skip to content

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.

Add controlled proxy autostart and unsafe-install guidance

JerrettDavis777ffeb716bb
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index 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).
```bash
pip 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-claw
diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json
index 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.json
index 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.json
index 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.ts
index 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.json
index 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,