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.

docs: add OpenClaw plugin section to main README

JerrettDavisfa99ba785e7f
diff --git a/README.md b/README.md
index 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.json
index 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.ts
index 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.ts
index 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);
});
});