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.

feat(openclaw): support remote Headroom proxy (connect-only)

JerrettDavis4c3d9c4e28bd
diff --git a/README.md b/README.md
index 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.
### Install
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index 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 bin
4. 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 Setup
Optional: 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.json
index 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.ts
index 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 proxies
if (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.ts
index 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);