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.

Add ordered launcher fallback for headroom proxy startup

JerrettDavis74ca68888faf
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index be929a535..04af3629e 100644
--- a/plugins/openclaw/README.md
+++ b/plugins/openclaw/README.md
@@ -32,6 +32,11 @@ 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 ...`.
+Auto-start launch order is:
+1. `headroom` from `PATH`
+2. local npm bin (`node_modules/.bin/headroom`)
+3. global npm bin
+4. Python module (`python -m headroom.cli proxy ...`)
## Required Proxy Setup
diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.ts
index cba6f88f9..80fa2a7ad 100644
--- a/plugins/openclaw/src/proxy-manager.ts
+++ b/plugins/openclaw/src/proxy-manager.ts
@@ -7,6 +7,10 @@
* - Localhost-only network access (127.0.0.1 / localhost)
*/
import { spawn } from "node:child_process";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
export interface ProxyManagerConfig {
proxyUrl?: string;
@@ -27,6 +31,14 @@ export interface ProxyProbeResult {
reason?: string;
}
+interface LaunchSpec {
+ label: string;
+ command: string;
+ args: string[];
+ checkCommand: string;
+ checkArgs: string[];
+}
+
const defaultLogger: ProxyManagerLogger = {
info: (m) => console.log(`[headroom] ${m}`),
warn: (m) => console.warn(`[headroom] ${m}`),
@@ -108,17 +120,124 @@ export class ProxyManager {
const parsed = new URL(proxyUrl);
const host = parsed.hostname;
const port = parsed.port || "80";
+ const specs = this.buildLaunchSpecs(host, port);
+ const errors: string[] = [];
+
+ for (const spec of specs) {
+ if (!this.canExecute(spec.checkCommand, spec.checkArgs)) {
+ this.logger.debug(`Launcher unavailable: ${spec.label}`);
+ continue;
+ }
+
+ try {
+ const child = spawn(spec.command, spec.args, {
+ detached: true,
+ stdio: "ignore",
+ });
+ child.unref();
+ this.logger.info(`Auto-start launcher selected: ${spec.label}`);
+ return;
+ } catch (error) {
+ errors.push(`${spec.label}: ${String(error)}`);
+ }
+ }
+
+ throw new Error(
+ "No usable Headroom launcher found. Tried PATH, local npm, global npm, and Python. " +
+ "Install headroom-ai (npm or pip) and ensure one launcher is available.\n" +
+ (errors.length > 0 ? `Launch errors: ${errors.join("; ")}` : ""),
+ );
+ }
+
+ private buildLaunchSpecs(host: string, port: string): LaunchSpec[] {
+ const commonArgs = ["proxy", "--host", host, "--port", port];
+ const specs: LaunchSpec[] = [];
+
+ // 1) PATH
+ specs.push({
+ label: "PATH: headroom",
+ command: "headroom",
+ args: commonArgs,
+ checkCommand: "headroom",
+ checkArgs: ["--version"],
+ });
+
+ // 2) Local npm install (inside plugin install path)
+ const moduleDir = dirname(fileURLToPath(import.meta.url)); // .../dist
+ const packageRoot = dirname(moduleDir);
+ const localBinDir = join(packageRoot, "node_modules", ".bin");
+ const localBins = process.platform === "win32"
+ ? [join(localBinDir, "headroom.cmd"), join(localBinDir, "headroom")]
+ : [join(localBinDir, "headroom")];
+ for (const localBin of localBins) {
+ if (!existsSync(localBin)) continue;
+ specs.push({
+ label: `Local npm: ${localBin}`,
+ command: localBin,
+ args: commonArgs,
+ checkCommand: localBin,
+ checkArgs: ["--version"],
+ });
+ }
+
+ // 3) Global npm install
+ const npmPrefix = this.getNpmGlobalPrefix();
+ if (npmPrefix) {
+ const globalBins = process.platform === "win32"
+ ? [join(npmPrefix, "headroom.cmd"), join(npmPrefix, "headroom")]
+ : [join(npmPrefix, "bin", "headroom"), join(npmPrefix, "headroom")];
+ for (const globalBin of globalBins) {
+ if (!existsSync(globalBin)) continue;
+ specs.push({
+ label: `Global npm: ${globalBin}`,
+ command: globalBin,
+ args: commonArgs,
+ checkCommand: globalBin,
+ checkArgs: ["--version"],
+ });
+ }
+ }
+
+ // 4) Python module fallback
+ for (const pyCmd of ["python", "python3", "py"]) {
+ specs.push({
+ label: `Python: ${pyCmd} -m headroom.cli`,
+ command: pyCmd,
+ args: ["-m", "headroom.cli", ...commonArgs],
+ checkCommand: pyCmd,
+ checkArgs: ["-c", "import headroom"],
+ });
+ }
+
+ return specs;
+ }
+
+ private canExecute(command: string, args: string[]): boolean {
try {
- const child = spawn("headroom", ["proxy", "--host", host, "--port", port], {
- detached: true,
+ const result = spawnSync(command, args, {
stdio: "ignore",
+ timeout: 5000,
});
- child.unref();
- } catch (error) {
- throw new Error(
- `Failed to spawn headroom proxy command. Ensure "headroom" is installed and on PATH. (${String(error)})`,
- );
+ if (result.error) return false;
+ return result.status === 0;
+ } catch {
+ return false;
+ }
+ }
+
+ private getNpmGlobalPrefix(): string | null {
+ try {
+ const result = spawnSync("npm", ["prefix", "-g"], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ timeout: 5000,
+ });
+ if (result.error || result.status !== 0) return null;
+ const prefix = (result.stdout ?? "").trim();
+ return prefix.length > 0 ? prefix : null;
+ } catch {
+ return null;
}
}
}