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.

Auto-detect proxyUrl by default and keep explicit override

JerrettDavise4c7c47e34ce
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index 04af3629e..b3960ed9f 100644
--- a/plugins/openclaw/README.md
+++ b/plugins/openclaw/README.md
@@ -32,6 +32,12 @@ This plugin auto-starts `headroom proxy` when needed. OpenClaw treats process-la
```
`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:
+- `http://127.0.0.1:8787`
+- `http://localhost:8787`
+If no proxy is found, it will auto-start on `http://127.0.0.1:8787` (when `autoStart` is enabled).
+
+If set, `proxyUrl` must be localhost (`127.0.0.1` or `localhost`). If that proxy is not running, the plugin will try to start it with `headroom proxy --host ... --port ...`.
Auto-start launch order is:
1. `headroom` from `PATH`
2. local npm bin (`node_modules/.bin/headroom`)
@@ -71,7 +77,7 @@ 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>`) |
+| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy (`http://127.0.0.1:<port>` or `http://localhost:<port>`). Defaults to probing `:8787`. |
| `autoStart` | `true` | Auto-start `headroom proxy` if not already running |
| `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json
index 71ff11da1..bc63d63d5 100644
--- a/plugins/openclaw/openclaw.plugin.json
+++ b/plugins/openclaw/openclaw.plugin.json
@@ -3,7 +3,7 @@
"uiHints": {
"proxyUrl": {
"label": "Proxy URL",
- "help": "Required. URL of an already running Headroom proxy on localhost (example: http://127.0.0.1:8787)"
+ "help": "Optional. URL of a Headroom proxy on localhost (example: http://127.0.0.1:8787). If omitted, plugin auto-detects defaults."
}
},
"configSchema": {
diff --git a/plugins/openclaw/src/plugin/index.ts b/plugins/openclaw/src/plugin/index.ts
index 1c81f0e68..2c908f685 100644
--- a/plugins/openclaw/src/plugin/index.ts
+++ b/plugins/openclaw/src/plugin/index.ts
@@ -23,12 +23,10 @@ export default function headroomPlugin(api: any) {
const config = api.config?.plugins?.entries?.headroom?.config ?? {};
const logger = api.logger ?? console;
const rawProxyUrl = config.proxyUrl;
- if (!rawProxyUrl || typeof rawProxyUrl !== "string") {
- throw new Error(
- '[headroom] Missing required config: plugins.entries.headroom.config.proxyUrl (example: "http://127.0.0.1:8787")',
- );
- }
- const proxyUrl = normalizeAndValidateProxyUrl(rawProxyUrl);
+ const proxyUrl =
+ typeof rawProxyUrl === "string" && rawProxyUrl.trim().length > 0
+ ? normalizeAndValidateProxyUrl(rawProxyUrl)
+ : undefined;
const engine = new HeadroomContextEngine({ ...config, proxyUrl }, {
info: (m: string) => logger.info(m),
@@ -43,6 +41,7 @@ export default function headroomPlugin(api: any) {
// Register CCR retrieval tool (active once proxy is running)
api.registerTool((ctx: any) => {
const activeProxyUrl = engine.getProxyUrl() ?? proxyUrl;
+ if (!activeProxyUrl) return null;
return createHeadroomRetrieveTool({ proxyUrl: activeProxyUrl });
});
diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.ts
index 80fa2a7ad..40bff44c4 100644
--- a/plugins/openclaw/src/proxy-manager.ts
+++ b/plugins/openclaw/src/proxy-manager.ts
@@ -39,6 +39,11 @@ interface LaunchSpec {
checkArgs: string[];
}
+const DEFAULT_PROXY_CANDIDATES = [
+ "http://127.0.0.1:8787",
+ "http://localhost:8787",
+];
+
const defaultLogger: ProxyManagerLogger = {
info: (m) => console.log(`[headroom] ${m}`),
warn: (m) => console.warn(`[headroom] ${m}`),
@@ -60,47 +65,70 @@ export class ProxyManager {
* Ensure a proxy is available. Returns the normalized URL origin.
*/
async start(): Promise<string> {
- if (!this.config.proxyUrl) {
- throw new Error(
- "Headroom proxy URL is required. Configure plugins.entries.headroom.config.proxyUrl " +
- '(example: "http://127.0.0.1:8787").',
- );
- }
-
- const url = normalizeAndValidateProxyUrl(this.config.proxyUrl);
- const probe = await probeHeadroomProxy(url);
-
- if (probe.reachable && probe.isHeadroom) {
- this.proxyUrl = url;
- this.logger.info(`Headroom proxy already running at ${url}`);
- return url;
+ const explicitUrl =
+ typeof this.config.proxyUrl === "string" && this.config.proxyUrl.trim().length > 0
+ ? normalizeAndValidateProxyUrl(this.config.proxyUrl)
+ : null;
+ const candidateUrls = explicitUrl ? [explicitUrl] : [...DEFAULT_PROXY_CANDIDATES];
+ const probeByUrl = new Map<string, ProxyProbeResult>();
+
+ for (const url of candidateUrls) {
+ const probe = await probeHeadroomProxy(url);
+ probeByUrl.set(url, probe);
+ if (probe.reachable && probe.isHeadroom) {
+ this.proxyUrl = url;
+ this.logger.info(`Headroom proxy already running at ${url}`);
+ return url;
+ }
}
- if (probe.reachable && !probe.isHeadroom) {
- throw new Error(
- `Service reachable at ${url}, but it does not appear to be a Headroom proxy (${probe.reason ?? "unknown service"}).`,
- );
+ if (explicitUrl) {
+ const explicitProbe = probeByUrl.get(explicitUrl);
+ if (explicitProbe?.reachable && !explicitProbe.isHeadroom) {
+ throw new Error(
+ `Service reachable at ${explicitUrl}, but it does not appear to be a Headroom proxy (${explicitProbe.reason ?? "unknown service"}).`,
+ );
+ }
}
if (this.config.autoStart !== false) {
- this.logger.info(`No proxy detected at ${url}; attempting to auto-start Headroom proxy...`);
- await this.startHeadroomProxy(url);
+ const startupUrl = explicitUrl ?? DEFAULT_PROXY_CANDIDATES[0];
+ const startupProbe = probeByUrl.get(startupUrl);
+ if (startupProbe?.reachable && !startupProbe.isHeadroom) {
+ throw new Error(
+ `Cannot auto-start Headroom at ${startupUrl}: port is in use by a non-Headroom service (${startupProbe.reason ?? "unknown service"}).`,
+ );
+ }
+
+ this.logger.info(
+ `No Headroom proxy detected${explicitUrl ? ` at ${startupUrl}` : " on default local endpoints"}; attempting to auto-start...`,
+ );
+ await this.startHeadroomProxy(startupUrl);
const startedProbe = await waitForHeadroomProxy(
- url,
+ startupUrl,
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;
+ this.proxyUrl = startupUrl;
+ this.logger.info(`Headroom proxy started and reachable at ${startupUrl}`);
+ return startupUrl;
}
throw new Error(
- `Attempted to start Headroom proxy, but it was not reachable at ${url} (${startedProbe.reason ?? "unknown"}).`,
+ `Attempted to start Headroom proxy, but it was not reachable at ${startupUrl} (${startedProbe.reason ?? "unknown"}).`,
);
}
- throw new Error(`Headroom proxy not reachable at ${url}. Ensure the proxy is running first.`);
+ if (explicitUrl) {
+ throw new Error(
+ `Headroom proxy not reachable at ${explicitUrl}. Ensure the proxy is running first.`,
+ );
+ }
+
+ throw new Error(
+ `Headroom proxy not detected on default endpoints (${DEFAULT_PROXY_CANDIDATES.join(", ")}). ` +
+ "Set proxyUrl explicitly or enable autoStart.",
+ );
}
/**