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
Auto-detect proxyUrl by default and keep explicit override
JerrettDavise4c7c47e34ce
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.mdindex 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.jsonindex 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.tsindex 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.tsindex 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.",+ );}/**