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

Remove localhost-only restriction from proxyUrl validation. Remote URLs
are connect-only: the plugin probes and uses them but never attempts to
spawn a subprocess. Auto-start remains available for local addresses
(127.0.0.1/localhost) only.

- Accept http:// and https:// URLs for any hostname
- Add isLocalProxyUrl() helper to gate auto-start on local addresses
- Remote URLs that fail probe get a clear "Remote proxy not reachable"
error instead of falling through to auto-start
- Update plugin.json schema, network capabilities, and UI hints
- Update plugin README with local vs remote proxy sections
- Add tests: remote connect, remote fail-fast, isLocalProxyUrl

Build: tsc --noEmit clean
Tests: 29 passed (0 skipped)

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
 

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 |

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://*:*"
       ]
     }
   }

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) {

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);