docs: add OpenClaw plugin section to main README

Add dedicated OpenClaw plugin section with install instructions,
explanation of --dangerously-force-unsafe-install requirement (proxy
subprocess spawning), and quick config example. Links to plugin README
for full details. Update integration tables to reference new section.

Also fix proxy port handling: apply default proxyPort when explicit
proxyUrl omits port, and allow trailing slash in proxyUrl validation
pattern. Add test coverage for port defaulting behavior.

README.md

@@ -164,7 +164,7 @@ Gives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `h
 | **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |
 | **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` |
 | **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` |
-| **OpenClaw** | ContextEngine plugin | `openclaw plugins install headroom-openclaw` |
+| **OpenClaw** | ContextEngine plugin | [See OpenClaw plugin](#openclaw-plugin) |
 | **Claude Code** | Wrap | `headroom wrap claude` |
 | **Codex / Aider** | Wrap | `headroom wrap codex` or `headroom wrap aider` |
 
@@ -363,6 +363,35 @@ Context compression is a new space. Here's how the approaches differ:
 | MCP (Claude Code, Cursor, etc.) | **Stable** | [MCP Guide](docs/mcp.md) |
 | Strands | **Stable** | [Strands Guide](docs/strands.md) |
 | LangChain | **Stable** | [LangChain Guide](docs/langchain.md) |
+| **OpenClaw** | **Stable** | [OpenClaw plugin](#openclaw-plugin) |
+
+---
+
+## 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.
+
+### Install
+
+```bash
+pip install "headroom-ai[proxy]"
+openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
+```
+
+> **Why `--dangerously-force-unsafe-install`?** The plugin auto-starts `headroom proxy` as a subprocess when no running proxy is detected. OpenClaw blocks process-launching plugins by default, so this flag is required to permit that behavior.
+
+Once installed, assign Headroom as the context engine in your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "entries": { "headroom": { "enabled": true } },
+    "slots": { "contextEngine": "headroom" }
+  }
+}
+```
+
+The plugin auto-detects and auto-starts the proxy — no manual proxy management needed. See the [plugin README](plugins/openclaw/README.md) for full configuration options, local development setup, and launcher details.
 
 ---
 

plugins/openclaw/openclaw.plugin.json

@@ -23,7 +23,7 @@
       },
       "proxyUrl": {
         "type": "string",
-        "pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?$"
+        "pattern": "^http:\\/\\/(localhost|127\\.0\\.0\\.1)(:\\d+)?\\/?$"
       },
       "proxyPort": {
         "type": "integer",

plugins/openclaw/src/proxy-manager.ts

@@ -1,5 +1,5 @@
 /**
- * Manages connectivity to an externally managed Headroom proxy.
+ * Manages connectivity to a local Headroom proxy.
  *
  * Security model:
  * - Optional local process execution to auto-start Headroom proxy
@@ -59,13 +59,13 @@ export class ProxyManager {
   }
 
   /**
-   * Ensure a proxy is available. Returns the normalized URL origin.
+ * 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)
+        ? withDefaultPort(normalizeAndValidateProxyUrl(this.config.proxyUrl), port)
         : null;
     const defaultCandidates = this.getDefaultProxyCandidates(port);
     const candidateUrls = explicitUrl ? [explicitUrl] : [...defaultCandidates];
@@ -102,7 +102,7 @@ export class ProxyManager {
       this.logger.info(
         `No Headroom proxy detected${explicitUrl ? ` at ${startupUrl}` : " on default local endpoints"}; attempting to auto-start...`,
       );
-      await this.startHeadroomProxy(startupUrl);
+      await this.startHeadroomProxy(startupUrl, port);
 
       const startedProbe = await waitForHeadroomProxy(
         startupUrl,
@@ -144,7 +144,7 @@ export class ProxyManager {
   }
 
   /**
-   * No-op: plugin never starts or manages external processes.
+   * Stop manager state. Spawned proxy processes are detached and externally managed.
    */
   async stop(): Promise<void> {
     this.proxyUrl = null;
@@ -156,10 +156,10 @@ export class ProxyManager {
 
   // --- Internal ---
 
-  private async startHeadroomProxy(proxyUrl: string): Promise<void> {
+  private async startHeadroomProxy(proxyUrl: string, defaultPort: number): Promise<void> {
     const parsed = new URL(proxyUrl);
     const host = parsed.hostname;
-    const port = parsed.port || "80";
+    const port = parsed.port || String(defaultPort);
     const specs = this.buildLaunchSpecs(host, port);
     const errors: string[] = [];
 
@@ -319,6 +319,14 @@ export function normalizeAndValidateProxyUrl(proxyUrl: string): string {
   return parsed.origin;
 }
 
+function withDefaultPort(proxyUrl: string, defaultPort: number): string {
+  const parsed = new URL(proxyUrl);
+  if (!parsed.port) {
+    parsed.port = String(defaultPort);
+  }
+  return parsed.origin;
+}
+
 /**
  * Probe a configured URL and verify whether it is a running Headroom proxy.
  */

plugins/openclaw/test/proxy-manager.test.ts

@@ -104,6 +104,22 @@ describe("ProxyManager.start", () => {
     await expect(manager.start()).rejects.toThrow(/does not appear to be a Headroom proxy/);
   });
 
+  it("applies default proxyPort when explicit proxyUrl omits port", async () => {
+    const manager = new ProxyManager({ proxyUrl: "http://127.0.0.1", autoStart: true });
+    const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);
+
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("down"))
+      .mockResolvedValueOnce({ ok: true, status: 200 })
+      .mockResolvedValueOnce({ ok: true, status: 200 });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const url = await manager.start();
+    expect(url).toBe("http://127.0.0.1:8787");
+    expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787", 8787);
+  });
+
   it("auto-starts when nothing is detected", async () => {
     const manager = new ProxyManager({ autoStart: true });
     const startSpy = vi.spyOn(manager as any, "startHeadroomProxy").mockResolvedValue(undefined);
@@ -119,7 +135,7 @@ describe("ProxyManager.start", () => {
 
     const url = await manager.start();
     expect(url).toBe("http://127.0.0.1:8787");
-    expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787");
+    expect(startSpy).toHaveBeenCalledWith("http://127.0.0.1:8787", 8787);
   });
 });