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
docs: add OpenClaw plugin section to main README
JerrettDavisfa99ba785e7f
diff --git a/README.md b/README.mdindex 71f4cdd05..3d416eeb7 100644--- a/README.md+++ b/README.md@@ -164,7 +164,7 @@ Gives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `h| **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` || **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` || **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` |-| **OpenClaw** | ContextEngine plugin | `openclaw plugins install headroom-openclaw` |+| **OpenClaw** | ContextEngine plugin | [See OpenClaw plugin](#openclaw-plugin) || **Claude Code** | Wrap | `headroom wrap claude` || **Codex / Aider** | Wrap | `headroom wrap codex` or `headroom wrap aider` |@@ -363,6 +363,35 @@ Context compression is a new space. Here's how the approaches differ:| MCP (Claude Code, Cursor, etc.) | **Stable** | [MCP Guide](docs/mcp.md) || Strands | **Stable** | [Strands Guide](docs/strands.md) || LangChain | **Stable** | [LangChain Guide](docs/langchain.md) |+| **OpenClaw** | **Stable** | [OpenClaw plugin](#openclaw-plugin) |++---++## OpenClaw Plugin++The [`@headroom-ai/openclaw`](plugins/openclaw) plugin integrates Headroom as a ContextEngine for [OpenClaw](https://github.com/openclaw/openclaw). It compresses tool outputs, code, logs, and structured data inline — 70-90% token savings with zero LLM calls.++### Install++```bash+pip install "headroom-ai[proxy]"+openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw+```++> **Why `--dangerously-force-unsafe-install`?** The plugin auto-starts `headroom proxy` as a subprocess when no running proxy is detected. OpenClaw blocks process-launching plugins by default, so this flag is required to permit that behavior.++Once installed, assign Headroom as the context engine in your OpenClaw config:++```json+{+ "plugins": {+ "entries": { "headroom": { "enabled": true } },+ "slots": { "contextEngine": "headroom" }+ }+}+```++The plugin auto-detects and auto-starts the proxy — no manual proxy management needed. See the [plugin README](plugins/openclaw/README.md) for full configuration options, local development setup, and launcher details.---diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.jsonindex a20dffe67..2ef1be2d7 100644--- a/plugins/openclaw/openclaw.plugin.json+++ b/plugins/openclaw/openclaw.plugin.json@@ -23,7 +23,7 @@},"proxyUrl": {"type": "string",- "pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?$"+ "pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?\\/?$"},"proxyPort": {"type": "integer",diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.tsindex d4e15384a..1eaff47de 100644--- a/plugins/openclaw/src/proxy-manager.ts+++ b/plugins/openclaw/src/proxy-manager.ts@@ -1,5 +1,5 @@/**- * Manages connectivity to an externally managed Headroom proxy.+ * Manages connectivity to a local Headroom proxy.** Security model:* - Optional local process execution to auto-start Headroom proxy@@ -59,13 +59,13 @@ export class ProxyManager {}/**- * Ensure a proxy is available. Returns the normalized URL origin.+ * Ensure a proxy is available. Returns the normalized URL origin.*/async start(): Promise<string> {const port = this.getProxyPort();const explicitUrl =typeof this.config.proxyUrl === "string" && this.config.proxyUrl.trim().length > 0- ? normalizeAndValidateProxyUrl(this.config.proxyUrl)+ ? withDefaultPort(normalizeAndValidateProxyUrl(this.config.proxyUrl), port): null;const defaultCandidates = this.getDefaultProxyCandidates(port);const candidateUrls = explicitUrl ? [explicitUrl] : [...defaultCandidates];@@ -102,7 +102,7 @@ export class ProxyManager {this.logger.info(`No Headroom proxy detected${explicitUrl ? ` at ${startupUrl}` : " on default local endpoints"}; attempting to auto-start...`,);- await this.startHeadroomProxy(startupUrl);+ await this.startHeadroomProxy(startupUrl, port);const startedProbe = await waitForHeadroomProxy(startupUrl,@@ -144,7 +144,7 @@ export class ProxyManager {}/**- * No-op: plugin never starts or manages external processes.+ * Stop manager state. Spawned proxy processes are detached and externally managed.*/async stop(): Promise<void> {this.proxyUrl = null;@@ -156,10 +156,10 @@ export class ProxyManager {// --- Internal ---- private async startHeadroomProxy(proxyUrl: string): Promise<void> {+ private async startHeadroomProxy(proxyUrl: string, defaultPort: number): Promise<void> {const parsed = new URL(proxyUrl);const host = parsed.hostname;- const port = parsed.port || "80";+ const port = parsed.port || String(defaultPort);const specs = this.buildLaunchSpecs(host, port);const errors: string[] = [];@@ -319,6 +319,14 @@ export function normalizeAndValidateProxyUrl(proxyUrl: string): string {return parsed.origin;}+function withDefaultPort(proxyUrl: string, defaultPort: number): string {+ const parsed = new URL(proxyUrl);+ if (!parsed.port) {+ parsed.port = String(defaultPort);+ }+ return parsed.origin;+}+/*** Probe a configured URL and verify whether it is a running Headroom proxy.*/diff --git a/plugins/openclaw/test/proxy-manager.test.ts b/plugins/openclaw/test/proxy-manager.test.tsindex 4cb8bde2e..0976362f7 100644--- a/plugins/openclaw/test/proxy-manager.test.ts+++ b/plugins/openclaw/test/proxy-manager.test.ts@@ -104,6 +104,22 @@ describe("ProxyManager.start", () => {await expect(manager.start()).rejects.toThrow(/does not appear to be a Headroom proxy/);});+ it("applies default proxyPort when explicit proxyUrl omits port", async () => {+ const manager = new ProxyManager({ proxyUrl: "http://127.0.0.1", autoStart: true });+ const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);++ const fetchMock = vi+ .fn()+ .mockRejectedValueOnce(new Error("down"))+ .mockResolvedValueOnce({ ok: true, status: 200 })+ .mockResolvedValueOnce({ ok: true, status: 200 });+ vi.stubGlobal("fetch", fetchMock);++ const url = await manager.start();+ expect(url).toBe("http://127.0.0.1:8787");+ expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787", 8787);+ });+it("auto-starts when nothing is detected", async () => {const manager = new ProxyManager({ autoStart: true });const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);@@ -119,7 +135,7 @@ describe("ProxyManager.start", () => {const url = await manager.start();expect(url).toBe("http://127.0.0.1:8787");- expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787");+ expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787", 8787);});});