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.

Restore pythonPath and proxyPort config support

JerrettDavis593f1b782930
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index 816810ae7..af91ec6e8 100644
--- a/plugins/openclaw/README.md
+++ b/plugins/openclaw/README.md
@@ -50,16 +50,17 @@ 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:
-- `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).
+- `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`). If that proxy is not running, the plugin will try to start it with `headroom proxy --host ... --port ...`.
+If set, `proxyUrl` must be localhost (`127.0.0.1` or `localhost`).
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 ...`)
+If `pythonPath` is set, it is tried first in the Python fallback step.
## Required Proxy Setup
@@ -94,7 +95,9 @@ 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>`). Defaults to probing `:8787`. |
+| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy (`http://127.0.0.1:<port>` or `http://localhost:<port>`). |
+| `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 |
| `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 bc63d63d5..a20dffe67 100644
--- a/plugins/openclaw/openclaw.plugin.json
+++ b/plugins/openclaw/openclaw.plugin.json
@@ -4,6 +4,14 @@
"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."
+ },
+ "proxyPort": {
+ "label": "Proxy Port",
+ "help": "Default port used for auto-detect/auto-start when proxyUrl is not set (default: 8787)."
+ },
+ "pythonPath": {
+ "label": "Python Path",
+ "help": "Optional explicit python executable for python fallback launcher (for example: python, python3, py, or full path)."
}
},
"configSchema": {
@@ -17,6 +25,15 @@
"type": "string",
"pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?$"
},
+ "proxyPort": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 65535,
+ "default": 8787
+ },
+ "pythonPath": {
+ "type": "string"
+ },
"autoStart": {
"type": "boolean",
"default": true
diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.ts
index 40bff44c4..d4e15384a 100644
--- a/plugins/openclaw/src/proxy-manager.ts
+++ b/plugins/openclaw/src/proxy-manager.ts
@@ -14,6 +14,8 @@ import { fileURLToPath } from "node:url";
export interface ProxyManagerConfig {
proxyUrl?: string;
+ proxyPort?: number;
+ pythonPath?: string;
autoStart?: boolean;
startupTimeoutMs?: number;
}
@@ -39,11 +41,6 @@ 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}`),
@@ -65,11 +62,13 @@ export class ProxyManager {
* Ensure a proxy is available. Returns the normalized URL origin.
*/
async start(): Promise<string> {
+ const port = this.getProxyPort();
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 defaultCandidates = this.getDefaultProxyCandidates(port);
+ const candidateUrls = explicitUrl ? [explicitUrl] : [...defaultCandidates];
const probeByUrl = new Map<string, ProxyProbeResult>();
for (const url of candidateUrls) {
@@ -92,7 +91,7 @@ export class ProxyManager {
}
if (this.config.autoStart !== false) {
- const startupUrl = explicitUrl ?? DEFAULT_PROXY_CANDIDATES[0];
+ const startupUrl = explicitUrl ?? defaultCandidates[0];
const startupProbe = probeByUrl.get(startupUrl);
if (startupProbe?.reachable && !startupProbe.isHeadroom) {
throw new Error(
@@ -126,11 +125,24 @@ export class ProxyManager {
}
throw new Error(
- `Headroom proxy not detected on default endpoints (${DEFAULT_PROXY_CANDIDATES.join(", ")}). ` +
+ `Headroom proxy not detected on default endpoints (${defaultCandidates.join(", ")}). ` +
"Set proxyUrl explicitly or enable autoStart.",
);
}
+ private getProxyPort(): number {
+ const rawPort = this.config.proxyPort;
+ if (!Number.isInteger(rawPort) || rawPort === undefined) return 8787;
+ if (rawPort < 1 || rawPort > 65535) {
+ throw new Error("proxyPort must be an integer between 1 and 65535");
+ }
+ return rawPort;
+ }
+
+ private getDefaultProxyCandidates(port: number): string[] {
+ return [`http://127.0.0.1:${port}`, `http://localhost:${port}`];
+ }
+
/**
* No-op: plugin never starts or manages external processes.
*/
@@ -228,7 +240,8 @@ export class ProxyManager {
}
// 4) Python module fallback
- for (const pyCmd of ["python", "python3", "py"]) {
+ const pythonCommands = this.getPythonCommands();
+ for (const pyCmd of pythonCommands) {
specs.push({
label: `Python: ${pyCmd} -m headroom.cli`,
command: pyCmd,
@@ -241,6 +254,20 @@ export class ProxyManager {
return specs;
}
+ private getPythonCommands(): string[] {
+ const commands: string[] = [];
+ const configured = typeof this.config.pythonPath === "string"
+ ? this.config.pythonPath.trim()
+ : "";
+ if (configured.length > 0) {
+ commands.push(configured);
+ }
+ for (const fallback of ["python", "python3", "py"]) {
+ if (!commands.includes(fallback)) commands.push(fallback);
+ }
+ return commands;
+ }
+
private canExecute(command: string, args: string[]): boolean {
try {
const result = spawnSync(command, args, {