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
feat(openclaw): support remote Headroom proxy (connect-only)
JerrettDavis4c3d9c4e28bd
diff --git a/README.md b/README.mdindex 3d416eeb7..d90d2bd0e 100644--- a/README.md+++ b/README.md@@ -369,7 +369,7 @@ Context compression is a new space. Here's how the approaches differ:## 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.+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. The plugin can connect to a local or remote Headroom proxy and will auto-start one locally if needed.### Installdiff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.mdindex af91ec6e8..9d24f62da 100644--- a/plugins/openclaw/README.md+++ b/plugins/openclaw/README.md@@ -9,7 +9,7 @@ pip install "headroom-ai[proxy]"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.+This plugin can auto-start a local `headroom proxy` when needed. OpenClaw treats process-launching plugins as unsafe by default, so `--dangerously-force-unsafe-install` is required even if you plan to use a remote proxy (the capability is declared at install time).## Local Development Install (Detection-Friendly)@@ -48,20 +48,36 @@ Why this matters:}```-`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 ...`.-`proxyUrl` is optional. If omitted, the plugin auto-detects on:+`proxyUrl` is optional. If omitted, the plugin auto-detects on localhost:- `http://127.0.0.1:<proxyPort>`- `http://localhost:<proxyPort>`+Default `proxyPort` is `8787`.-If set, `proxyUrl` must be localhost (`127.0.0.1` or `localhost`).-Auto-start launch order is:+### Local proxy (auto-start)++When `proxyUrl` points to localhost (or is omitted), the plugin will auto-start `headroom proxy` if no running proxy is detected. Launch order:1. `headroom` from `PATH`2. local npm bin (`node_modules/.bin/headroom`)3. global npm bin4. Python module (`python -m headroom.cli proxy ...`)+If `pythonPath` is set, it is tried first in the Python fallback step.+### Remote proxy (connect-only)++Point `proxyUrl` to any reachable Headroom instance:++```json+{+ "config": {+ "proxyUrl": "https://headroom.example.com:8787"+ }+}+```++Remote URLs are **connect-only** — the plugin probes the URL at startup and fails fast if the proxy is not reachable. No subprocess is spawned for remote addresses.+## Required Proxy SetupOptional: run Headroom proxy yourself before launching OpenClaw.@@ -95,7 +111,7 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored| Option | Default | Description ||--------|---------|-------------|-| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy (`http://127.0.0.1:<port>` or `http://localhost:<port>`). |+| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy. Local addresses (`http://127.0.0.1:<port>`, `http://localhost:<port>`) enable auto-start; remote URLs (`https://headroom.example.com`) are connect-only. || `proxyPort` | `8787` | Port used for default auto-detect/auto-start when `proxyUrl` is not set. || `pythonPath` | auto-detected | Optional Python executable override for Python fallback launcher. || `autoStart` | `true` | Auto-start `headroom proxy` if not already running |diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.jsonindex 2ef1be2d7..dc81baf22 100644--- a/plugins/openclaw/openclaw.plugin.json+++ b/plugins/openclaw/openclaw.plugin.json@@ -3,7 +3,7 @@"uiHints": {"proxyUrl": {"label": "Proxy URL",- "help": "Optional. URL of a Headroom proxy on localhost (example: http://127.0.0.1:8787). If omitted, plugin auto-detects defaults."+ "help": "Optional. URL of a Headroom proxy (example: http://127.0.0.1:8787 or https://headroom.example.com). If omitted, plugin auto-detects on localhost. Auto-start only works for local addresses."},"proxyPort": {"label": "Proxy Port",@@ -23,7 +23,7 @@},"proxyUrl": {"type": "string",- "pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?\\/?$"+ "pattern": "^https?:\\/\\/.+(:\\d+)?\\/?$"},"proxyPort": {"type": "integer",@@ -50,7 +50,9 @@"network": {"allow": ["http://localhost:*",- "http://127.0.0.1:*"+ "http://127.0.0.1:*",+ "http://*:*",+ "https://*:*"]}}diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.tsindex 1eaff47de..b5ea499c6 100644--- a/plugins/openclaw/src/proxy-manager.ts+++ b/plugins/openclaw/src/proxy-manager.ts@@ -1,10 +1,10 @@/**- * Manages connectivity to a local Headroom proxy.+ * Manages connectivity to a Headroom proxy (local or remote).** Security model:- * - Optional local process execution to auto-start Headroom proxy+ * - Local proxies (127.0.0.1 / localhost) can be auto-started via subprocess+ * - Remote proxies are connect-only: probe and use, never launch* - No environment variable access- * - Localhost-only network access (127.0.0.1 / localhost)*/import { spawn } from "node:child_process";import { spawnSync } from "node:child_process";@@ -90,6 +90,14 @@ export class ProxyManager {}}+ // Remote URLs are connect-only — never auto-start a subprocess for them+ if (explicitUrl && !isLocalProxyUrl(explicitUrl)) {+ throw new Error(+ `Remote Headroom proxy not reachable at ${explicitUrl}. Ensure the proxy is running at that address.`,+ );+ }++ // Auto-start is only available for local proxiesif (this.config.autoStart !== false) {const startupUrl = explicitUrl ?? defaultCandidates[0];const startupProbe = probeByUrl.get(startupUrl);@@ -305,11 +313,8 @@ export function normalizeAndValidateProxyUrl(proxyUrl: string): string {throw new Error(`Invalid proxyUrl: "${proxyUrl}"`);}- if (parsed.protocol !== "http:") {- throw new Error("proxyUrl must use http://");- }- if (parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") {- throw new Error("proxyUrl host must be localhost or 127.0.0.1");+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {+ throw new Error("proxyUrl must use http:// or https://");}if (parsed.pathname !== "/" || parsed.search || parsed.hash) {@@ -319,6 +324,16 @@ export function normalizeAndValidateProxyUrl(proxyUrl: string): string {return parsed.origin;}+/** Returns true if the URL points to a local address (localhost or 127.0.0.1). */+export function isLocalProxyUrl(proxyUrl: string): boolean {+ try {+ const parsed = new URL(proxyUrl);+ return parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost";+ } catch {+ return false;+ }+}+function withDefaultPort(proxyUrl: string, defaultPort: number): string {const parsed = new URL(proxyUrl);if (!parsed.port) {diff --git a/plugins/openclaw/test/proxy-manager.test.ts b/plugins/openclaw/test/proxy-manager.test.tsindex 0976362f7..383c8bb2b 100644--- a/plugins/openclaw/test/proxy-manager.test.ts+++ b/plugins/openclaw/test/proxy-manager.test.ts@@ -2,6 +2,7 @@ import { describe, it, expect, afterEach, vi } from "vitest";import {ProxyManager,normalizeAndValidateProxyUrl,+ isLocalProxyUrl,probeHeadroomProxy,} from "../src/proxy-manager.js";@@ -15,19 +16,38 @@ describe("normalizeAndValidateProxyUrl", () => {expect(normalizeAndValidateProxyUrl("http://localhost:8787")).toBe("http://localhost:8787");});- it("rejects non-local and malformed URLs", () => {- expect(() => normalizeAndValidateProxyUrl("https://localhost:8787")).toThrow(+ it("accepts remote URLs", () => {+ expect(normalizeAndValidateProxyUrl("http://example.com:8787")).toBe("http://example.com:8787");+ expect(normalizeAndValidateProxyUrl("https://headroom.example.com")).toBe("https://headroom.example.com");+ expect(normalizeAndValidateProxyUrl("https://headroom.example.com:9090")).toBe("https://headroom.example.com:9090");+ });++ it("rejects malformed URLs", () => {+ expect(() => normalizeAndValidateProxyUrl("ftp://localhost:8787")).toThrow(/must use http/,);- expect(() => normalizeAndValidateProxyUrl("http://example.com:8787")).toThrow(- /must be localhost/,- );expect(() => normalizeAndValidateProxyUrl("http://localhost:8787/path")).toThrow(/must not include a path/,);});});+describe("isLocalProxyUrl", () => {+ it("returns true for localhost addresses", () => {+ expect(isLocalProxyUrl("http://127.0.0.1:8787")).toBe(true);+ expect(isLocalProxyUrl("http://localhost:8787")).toBe(true);+ });++ it("returns false for remote addresses", () => {+ expect(isLocalProxyUrl("http://example.com:8787")).toBe(false);+ expect(isLocalProxyUrl("https://headroom.example.com")).toBe(false);+ });++ it("returns false for invalid URLs", () => {+ expect(isLocalProxyUrl("not-a-url")).toBe(false);+ });+});+describe("probeHeadroomProxy", () => {it("returns reachable+isHeadroom when both endpoints succeed", async () => {const fetchMock = vi@@ -120,6 +140,33 @@ describe("ProxyManager.start", () => {expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787", 8787);});+ it("connects to remote proxy without auto-start", async () => {+ const manager = new ProxyManager({ proxyUrl: "http://headroom.remote.example:8787", autoStart: true });+ const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);++ // Remote probe succeeds+ const fetchMock = vi+ .fn()+ .mockResolvedValueOnce({ ok: true, status: 200 }) // /health+ .mockResolvedValueOnce({ ok: true, status: 200 }); // /v1/retrieve/stats+ vi.stubGlobal("fetch", fetchMock);++ const url = await manager.start();+ expect(url).toBe("http://headroom.remote.example:8787");+ expect(startSpy).not.toHaveBeenCalled();+ });++ it("fails fast for unreachable remote proxy without attempting auto-start", async () => {+ const manager = new ProxyManager({ proxyUrl: "https://headroom.remote.example:8787", autoStart: true });+ const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);++ const fetchMock = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));+ vi.stubGlobal("fetch", fetchMock);++ await expect(manager.start()).rejects.toThrow(/Remote Headroom proxy not reachable/);+ expect(startSpy).not.toHaveBeenCalled();+ });+it("auto-starts when nothing is detected", async () => {const manager = new ProxyManager({ autoStart: true });const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);