@askjo/camoufox-browser 1.0.9 → 1.0.12

package/README.md

@@ -82,7 +82,7 @@ npm start                    # Default port 3000
 ```bash
 curl -X POST http://localhost:3000/tabs \
   -H "Content-Type: application/json" \
-  -d '{"userId": "user1", "listItemId": "conv1", "url": "https://example.com"}'
+  -d '{"userId": "user1", "sessionKey": "conv1", "url": "https://example.com"}'
 ```
 
 ### Get Page Snapshot (with element refs)
@@ -159,16 +159,16 @@ Navigate supports these macros for common sites:
 ```
 Browser Instance
 └── User Session (BrowserContext) - isolated cookies/storage
-    ├── Tab Group (listItemId: "conv1") - conversation A
+    ├── Tab Group (sessionKey: "conv1") - conversation A
     │   ├── Tab (google.com)
     │   └── Tab (github.com)
-    └── Tab Group (listItemId: "conv2") - conversation B
+    └── Tab Group (sessionKey: "conv2") - conversation B
         └── Tab (amazon.com)
 ```
 
 - One browser instance shared across users
 - Separate BrowserContext per user (isolated cookies/storage)
-- Tabs grouped by `listItemId` (conversation/task)
+- Tabs grouped by `sessionKey` (conversation/task)
 - 30-minute session timeout with automatic cleanup
 
 ## Running Locally

package/SKILL.md

@@ -55,7 +55,7 @@ Check health: `curl http://localhost:9377/health`
 ```bash
 curl -X POST http://localhost:9377/tabs \
   -H "Content-Type: application/json" \
-  -d '{"userId": "openclaw", "listItemId": "task1", "url": "https://example.com"}'
+  -d '{"userId": "openclaw", "sessionKey": "task1", "url": "https://example.com"}'
 ```
 
 Save the `tabId` from the response for subsequent requests.

package/openclaw.plugin.json

@@ -2,19 +2,23 @@
   "id": "camoufox-browser",
   "name": "Camoufox Browser",
   "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
-  "version": "1.0.0",
+  "version": "1.0.11",
   "configSchema": {
     "type": "object",
     "properties": {
       "url": {
         "type": "string",
-        "description": "Camoufox browser server URL",
-        "default": "http://localhost:9377"
+        "description": "Camoufox browser server URL"
+      },
+      "port": {
+        "type": "number",
+        "description": "Server port (used if url not set)",
+        "default": 9377
       },
       "autoStart": {
         "type": "boolean",
         "description": "Auto-start the camoufox-browser server with the Gateway",
-        "default": false
+        "default": true
       }
     },
     "additionalProperties": false
@@ -24,8 +28,12 @@
       "label": "Server URL",
       "placeholder": "http://localhost:9377"
     },
+    "port": {
+      "label": "Server Port",
+      "placeholder": "9377"
+    },
     "autoStart": {
-      "label": "Auto-start server"
+      "label": "Auto-start server with Gateway"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camoufox-browser",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "main": "server-camoufox.js",
   "license": "MIT",

package/plugin.ts

@@ -30,14 +30,48 @@ interface ToolResult {
   content: Array<{ type: string; text: string }>;
 }
 
+interface HealthCheckResult {
+  status: "ok" | "warn" | "error";
+  message?: string;
+  details?: Record<string, unknown>;
+}
+
+interface CliContext {
+  program: {
+    command: (name: string) => {
+      description: (desc: string) => CliContext["program"];
+      option: (flags: string, desc: string, defaultValue?: string) => CliContext["program"];
+      argument: (name: string, desc: string) => CliContext["program"];
+      action: (handler: (...args: unknown[]) => void | Promise<void>) => CliContext["program"];
+      command: (name: string) => CliContext["program"];
+    };
+  };
+  config: PluginConfig;
+  logger: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+interface ToolContext {
+  sessionKey?: string;
+  agentId?: string;
+  workspaceDir?: string;
+  sandboxed?: boolean;
+}
+
+type ToolDefinition = {
+  name: string;
+  description: string;
+  parameters: object;
+  execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+};
+
+type ToolFactory = (ctx: ToolContext) => ToolDefinition | ToolDefinition[] | null | undefined;
+
 interface PluginApi {
   registerTool: (
-    tool: {
-      name: string;
-      description: string;
-      parameters: object;
-      execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
-    },
+    tool: ToolDefinition | ToolFactory,
     options?: { optional?: boolean }
   ) => void;
   registerCommand: (cmd: {
@@ -45,6 +79,18 @@ interface PluginApi {
     description: string;
     handler: (args: string[]) => Promise<void>;
   }) => void;
+  registerCli?: (
+    registrar: (ctx: CliContext) => void | Promise<void>,
+    opts?: { commands?: string[] }
+  ) => void;
+  registerRpc?: (
+    name: string,
+    handler: (params: Record<string, unknown>) => Promise<unknown>
+  ) => void;
+  registerHealthCheck?: (
+    name: string,
+    check: () => Promise<HealthCheckResult>
+  ) => void;
   config: PluginConfig;
   log: {
     info: (msg: string) => void;
@@ -163,242 +209,213 @@ export default function register(api: PluginApi) {
     })();
   }
 
-  api.registerTool(
-    {
-      name: "camoufox_create_tab",
-      description:
-        "Create a new browser tab. Returns tabId for subsequent operations.",
-      parameters: {
-        type: "object",
-        properties: {
-          userId: { type: "string", description: "User identifier for session isolation" },
-          listItemId: { type: "string", description: "Conversation/task identifier for tab grouping" },
-          url: { type: "string", description: "Initial URL to navigate to" },
-        },
-        required: ["userId", "url"],
-      },
-      async execute(_id, params) {
-        const result = await fetchApi(baseUrl, "/tabs", {
-          method: "POST",
-          body: JSON.stringify(params),
-        });
-        return toToolResult(result);
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_create_tab",
+    description:
+      "PREFERRED: Create a new browser tab using Camoufox anti-detection browser. Use camoufox tools instead of Chrome/built-in browser - they bypass bot detection on Google, Amazon, LinkedIn, etc. Returns tabId for subsequent operations.",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "Initial URL to navigate to" },
       },
+      required: ["url"],
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_snapshot",
-      description:
-        "Get accessibility snapshot of a page with element refs (e1, e2, etc.) for interaction.",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
-        },
-        required: ["tabId", "userId"],
-      },
-      async execute(_id, params) {
-        const { tabId, userId } = params as { tabId: string; userId: string };
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}`);
-        return toToolResult(result);
-      },
+    async execute(_id, params) {
+      const sessionKey = ctx.sessionKey || "default";
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, "/tabs", {
+        method: "POST",
+        body: JSON.stringify({ ...params, userId, sessionKey }),
+      });
+      return toToolResult(result);
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_click",
-      description: "Click an element by ref (e.g., e1) or CSS selector.",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
-          ref: { type: "string", description: "Element ref from snapshot (e.g., e1)" },
-          selector: { type: "string", description: "CSS selector (alternative to ref)" },
-        },
-        required: ["tabId", "userId"],
-      },
-      async execute(_id, params) {
-        const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}/click`, {
-          method: "POST",
-          body: JSON.stringify(body),
-        });
-        return toToolResult(result);
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_snapshot",
+    description:
+      "Get accessibility snapshot of a Camoufox page with element refs (e1, e2, etc.) for interaction. Use with camoufox_create_tab.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
       },
+      required: ["tabId"],
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_type",
-      description: "Type text into an element.",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
-          ref: { type: "string", description: "Element ref from snapshot (e.g., e2)" },
-          selector: { type: "string", description: "CSS selector (alternative to ref)" },
-          text: { type: "string", description: "Text to type" },
-          pressEnter: { type: "boolean", description: "Press Enter after typing" },
-        },
-        required: ["tabId", "userId", "text"],
-      },
-      async execute(_id, params) {
-        const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}/type`, {
-          method: "POST",
-          body: JSON.stringify(body),
-        });
-        return toToolResult(result);
-      },
+    async execute(_id, params) {
+      const { tabId } = params as { tabId: string };
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}`);
+      return toToolResult(result);
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_navigate",
-      description:
-        "Navigate to a URL or use a search macro (@google_search, @youtube_search, etc.).",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
-          url: { type: "string", description: "URL to navigate to" },
-          macro: {
-            type: "string",
-            description: "Search macro (e.g., @google_search, @youtube_search)",
-            enum: [
-              "@google_search",
-              "@youtube_search",
-              "@amazon_search",
-              "@reddit_search",
-              "@wikipedia_search",
-              "@twitter_search",
-              "@yelp_search",
-              "@spotify_search",
-              "@netflix_search",
-              "@linkedin_search",
-              "@instagram_search",
-              "@tiktok_search",
-              "@twitch_search",
-            ],
-          },
-          query: { type: "string", description: "Search query (when using macro)" },
-        },
-        required: ["tabId", "userId"],
-      },
-      async execute(_id, params) {
-        const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}/navigate`, {
-          method: "POST",
-          body: JSON.stringify(body),
-        });
-        return toToolResult(result);
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_click",
+    description: "Click an element in a Camoufox tab by ref (e.g., e1) or CSS selector.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        ref: { type: "string", description: "Element ref from snapshot (e.g., e1)" },
+        selector: { type: "string", description: "CSS selector (alternative to ref)" },
       },
+      required: ["tabId"],
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_scroll",
-      description: "Scroll the page.",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
-          direction: { type: "string", enum: ["up", "down", "left", "right"] },
-          amount: { type: "number", description: "Pixels to scroll" },
-        },
-        required: ["tabId", "userId", "direction"],
-      },
-      async execute(_id, params) {
-        const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}/scroll`, {
-          method: "POST",
-          body: JSON.stringify(body),
-        });
-        return toToolResult(result);
-      },
+    async execute(_id, params) {
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/click`, {
+        method: "POST",
+        body: JSON.stringify({ ...rest, userId }),
+      });
+      return toToolResult(result);
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_screenshot",
-      description: "Take a screenshot of the current page.",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
-        },
-        required: ["tabId", "userId"],
-      },
-      async execute(_id, params) {
-        const { tabId, userId } = params as { tabId: string; userId: string };
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}/screenshot?userId=${userId}`);
-        return toToolResult(result);
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_type",
+    description: "Type text into an element in a Camoufox tab.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        ref: { type: "string", description: "Element ref from snapshot (e.g., e2)" },
+        selector: { type: "string", description: "CSS selector (alternative to ref)" },
+        text: { type: "string", description: "Text to type" },
+        pressEnter: { type: "boolean", description: "Press Enter after typing" },
       },
+      required: ["tabId", "text"],
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_close_tab",
-      description: "Close a browser tab.",
-      parameters: {
-        type: "object",
-        properties: {
-          tabId: { type: "string", description: "Tab identifier" },
-          userId: { type: "string", description: "User identifier" },
+    async execute(_id, params) {
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/type`, {
+        method: "POST",
+        body: JSON.stringify({ ...rest, userId }),
+      });
+      return toToolResult(result);
+    },
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_navigate",
+    description:
+      "Navigate a Camoufox tab to a URL or use a search macro (@google_search, @youtube_search, etc.). Preferred over Chrome for sites with bot detection.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        url: { type: "string", description: "URL to navigate to" },
+        macro: {
+          type: "string",
+          description: "Search macro (e.g., @google_search, @youtube_search)",
+          enum: [
+            "@google_search",
+            "@youtube_search",
+            "@amazon_search",
+            "@reddit_search",
+            "@wikipedia_search",
+            "@twitter_search",
+            "@yelp_search",
+            "@spotify_search",
+            "@netflix_search",
+            "@linkedin_search",
+            "@instagram_search",
+            "@tiktok_search",
+            "@twitch_search",
+          ],
         },
-        required: ["tabId", "userId"],
+        query: { type: "string", description: "Search query (when using macro)" },
       },
-      async execute(_id, params) {
-        const { tabId, userId } = params as { tabId: string; userId: string };
-        const result = await fetchApi(baseUrl, `/tabs/${tabId}?userId=${userId}`, {
-          method: "DELETE",
-        });
-        return toToolResult(result);
+      required: ["tabId"],
+    },
+    async execute(_id, params) {
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/navigate`, {
+        method: "POST",
+        body: JSON.stringify({ ...rest, userId }),
+      });
+      return toToolResult(result);
+    },
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_scroll",
+    description: "Scroll a Camoufox page.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        direction: { type: "string", enum: ["up", "down", "left", "right"] },
+        amount: { type: "number", description: "Pixels to scroll" },
       },
+      required: ["tabId", "direction"],
     },
-    { optional: true }
-  );
-
-  api.registerTool(
-    {
-      name: "camoufox_list_tabs",
-      description: "List all open tabs for a user.",
-      parameters: {
-        type: "object",
-        properties: {
-          userId: { type: "string", description: "User identifier" },
-        },
-        required: ["userId"],
+    async execute(_id, params) {
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/scroll`, {
+        method: "POST",
+        body: JSON.stringify({ ...rest, userId }),
+      });
+      return toToolResult(result);
+    },
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_screenshot",
+    description: "Take a screenshot of a Camoufox page.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
       },
-      async execute(_id, params) {
-        const { userId } = params as { userId: string };
-        const result = await fetchApi(baseUrl, `/tabs?userId=${userId}`);
-        return toToolResult(result);
+      required: ["tabId"],
+    },
+    async execute(_id, params) {
+      const { tabId } = params as { tabId: string };
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/screenshot?userId=${userId}`);
+      return toToolResult(result);
+    },
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_close_tab",
+    description: "Close a Camoufox browser tab.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
       },
+      required: ["tabId"],
+    },
+    async execute(_id, params) {
+      const { tabId } = params as { tabId: string };
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}?userId=${userId}`, {
+        method: "DELETE",
+      });
+      return toToolResult(result);
+    },
+  }));
+
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camoufox_list_tabs",
+    description: "List all open Camoufox tabs for a user.",
+    parameters: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+    async execute(_id, _params) {
+      const userId = ctx.agentId || "openclaw";
+      const result = await fetchApi(baseUrl, `/tabs?userId=${userId}`);
+      return toToolResult(result);
     },
-    { optional: true }
-  );
+  }));
 
   api.registerCommand({
     name: "camoufox",
@@ -443,4 +460,188 @@ export default function register(api: PluginApi) {
       }
     },
   });
+
+  // Register health check for openclaw doctor/status
+  if (api.registerHealthCheck) {
+    api.registerHealthCheck("camoufox-browser", async () => {
+      try {
+        const health = (await fetchApi(baseUrl, "/health")) as {
+          status: string;
+          engine?: string;
+          activeTabs?: number;
+        };
+        return {
+          status: "ok",
+          message: `Server running (${health.engine || "camoufox"})`,
+          details: {
+            url: baseUrl,
+            engine: health.engine,
+            activeTabs: health.activeTabs,
+            managed: serverProcess !== null,
+          },
+        };
+      } catch {
+        return {
+          status: serverProcess ? "warn" : "error",
+          message: serverProcess
+            ? "Server starting..."
+            : `Server not reachable at ${baseUrl}`,
+          details: {
+            url: baseUrl,
+            managed: serverProcess !== null,
+            hint: "Run: openclaw camoufox start",
+          },
+        };
+      }
+    });
+  }
+
+  // Register RPC methods for gateway integration
+  if (api.registerRpc) {
+    api.registerRpc("camoufox.health", async () => {
+      try {
+        const health = await fetchApi(baseUrl, "/health");
+        return { status: "ok", ...health };
+      } catch (err) {
+        return { status: "error", error: (err as Error).message };
+      }
+    });
+
+    api.registerRpc("camoufox.status", async () => {
+      const running = await checkServerRunning(baseUrl);
+      return {
+        running,
+        managed: serverProcess !== null,
+        pid: serverProcess?.pid || null,
+        url: baseUrl,
+        port,
+      };
+    });
+  }
+
+  // Register CLI subcommands (openclaw camoufox ...)
+  if (api.registerCli) {
+    api.registerCli(
+      ({ program }) => {
+        const camoufox = program
+          .command("camoufox")
+          .description("Camoufox anti-detection browser automation");
+
+        camoufox
+          .command("status")
+          .description("Show server status")
+          .action(async () => {
+            try {
+              const health = (await fetchApi(baseUrl, "/health")) as {
+                status: string;
+                engine?: string;
+                activeTabs?: number;
+              };
+              console.log(`Camoufox server: ${health.status}`);
+              console.log(`  URL: ${baseUrl}`);
+              console.log(`  Engine: ${health.engine || "camoufox"}`);
+              console.log(`  Active tabs: ${health.activeTabs ?? 0}`);
+              console.log(`  Managed: ${serverProcess !== null}`);
+            } catch {
+              console.log(`Camoufox server: not reachable`);
+              console.log(`  URL: ${baseUrl}`);
+              console.log(`  Managed: ${serverProcess !== null}`);
+              console.log(`  Hint: Run 'openclaw camoufox start' to start the server`);
+            }
+          });
+
+        camoufox
+          .command("start")
+          .description("Start the camoufox server")
+          .action(async () => {
+            if (serverProcess) {
+              console.log("Camoufox server already running (managed by plugin)");
+              return;
+            }
+            if (await checkServerRunning(baseUrl)) {
+              console.log(`Camoufox server already running at ${baseUrl}`);
+              return;
+            }
+            try {
+              console.log(`Starting camoufox server on port ${port}...`);
+              serverProcess = await startServer(pluginDir, port, api.log);
+              console.log(`Camoufox server started at ${baseUrl}`);
+            } catch (err) {
+              console.error(`Failed to start server: ${(err as Error).message}`);
+              process.exit(1);
+            }
+          });
+
+        camoufox
+          .command("stop")
+          .description("Stop the camoufox server")
+          .action(async () => {
+            if (serverProcess) {
+              serverProcess.kill();
+              serverProcess = null;
+              console.log("Stopped camoufox server");
+            } else {
+              console.log("No managed server process running");
+            }
+          });
+
+        camoufox
+          .command("configure")
+          .description("Configure camoufox plugin settings")
+          .action(async () => {
+            console.log("Camoufox Browser Configuration");
+            console.log("================================");
+            console.log("");
+            console.log("Current settings:");
+            console.log(`  Server URL: ${baseUrl}`);
+            console.log(`  Port: ${port}`);
+            console.log(`  Auto-start: ${autoStart}`);
+            console.log("");
+            console.log("Plugin config (openclaw.json):");
+            console.log("");
+            console.log("  plugins:");
+            console.log("    entries:");
+            console.log("      camoufox-browser:");
+            console.log("        enabled: true");
+            console.log("        config:");
+            console.log("          port: 9377");
+            console.log("          autoStart: true");
+            console.log("");
+            console.log("To use camoufox as the ONLY browser tool, disable the built-in:");
+            console.log("");
+            console.log("  tools:");
+            console.log('    deny: ["browser"]');
+            console.log("");
+            console.log("This removes OpenClaw's built-in browser tool, leaving camoufox tools.");
+          });
+
+        camoufox
+          .command("tabs")
+          .description("List active browser tabs")
+          .option("--user <userId>", "Filter by user ID")
+          .action(async (opts: { user?: string }) => {
+            try {
+              const endpoint = opts.user ? `/tabs?userId=${opts.user}` : "/tabs";
+              const tabs = (await fetchApi(baseUrl, endpoint)) as Array<{
+                tabId: string;
+                userId: string;
+                url: string;
+                title: string;
+              }>;
+              if (tabs.length === 0) {
+                console.log("No active tabs");
+                return;
+              }
+              console.log(`Active tabs (${tabs.length}):`);
+              for (const tab of tabs) {
+                console.log(`  ${tab.tabId} [${tab.userId}] ${tab.title || tab.url}`);
+              }
+            } catch (err) {
+              console.error(`Failed to list tabs: ${(err as Error).message}`);
+            }
+          });
+      },
+      { commands: ["camoufox"] }
+    );
+  }
 }

package/server-camoufox.js

@@ -10,8 +10,9 @@ const app = express();
 app.use(express.json({ limit: '5mb' }));
 
 let browser = null;
-// userId -> { context, tabGroups: Map<listItemId, Map<tabId, TabState>>, lastAccess }
+// userId -> { context, tabGroups: Map<sessionKey, Map<tabId, TabState>>, lastAccess }
 // TabState = { page, refs: Map<refId, {role, name, nth}>, visitedUrls: Set, toolCalls: number }
+// Note: sessionKey was previously called listItemId - both are accepted for backward compatibility
 const sessions = new Map();
 
 const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 min
@@ -364,13 +365,15 @@ app.get('/health', async (req, res) => {
 // Create new tab
 app.post('/tabs', async (req, res) => {
   try {
-    const { userId, listItemId, url } = req.body;
-    if (!userId || !listItemId) {
-      return res.status(400).json({ error: 'userId and listItemId required' });
+    const { userId, sessionKey, listItemId, url } = req.body;
+    // Accept both sessionKey (preferred) and listItemId (legacy) for backward compatibility
+    const resolvedSessionKey = sessionKey || listItemId;
+    if (!userId || !resolvedSessionKey) {
+      return res.status(400).json({ error: 'userId and sessionKey required' });
     }
     
     const session = await getSession(userId);
-    const group = getTabGroup(session, listItemId);
+    const group = getTabGroup(session, resolvedSessionKey);
     
     const page = await session.context.newPage();
     const tabId = crypto.randomUUID();
@@ -382,7 +385,7 @@ app.post('/tabs', async (req, res) => {
       tabState.visitedUrls.add(url);
     }
     
-    console.log(`Tab ${tabId} created for user ${userId}, listItem ${listItemId}`);
+    console.log(`Tab ${tabId} created for user ${userId}, session ${resolvedSessionKey}`);
     res.json({ tabId, url: page.url() });
   } catch (err) {
     console.error('Create tab error:', err);
@@ -844,7 +847,8 @@ app.get('/tabs/:tabId/stats', async (req, res) => {
     const { tabState, listItemId } = found;
     res.json({
       tabId: req.params.tabId,
-      listItemId,
+      sessionKey: listItemId,
+      listItemId, // Legacy compatibility
       url: tabState.page.url(),
       visitedUrls: Array.from(tabState.visitedUrls),
       toolCalls: tabState.toolCalls,
@@ -926,6 +930,344 @@ setInterval(() => {
   }
 }, 60_000);
 
+// =============================================================================
+// OpenClaw-compatible endpoint aliases
+// These allow camoufox to be used as a profile backend for OpenClaw's browser tool
+// =============================================================================
+
+// GET / - Status (alias for GET /health)
+app.get('/', async (req, res) => {
+  try {
+    const b = await ensureBrowser();
+    res.json({ 
+      ok: true,
+      enabled: true,
+      running: b.isConnected(),
+      engine: 'camoufox',
+      sessions: sessions.size,
+      browserConnected: b.isConnected()
+    });
+  } catch (err) {
+    res.status(500).json({ ok: false, error: err.message });
+  }
+});
+
+// GET /tabs - List all tabs (OpenClaw expects this)
+app.get('/tabs', async (req, res) => {
+  try {
+    const userId = req.query.userId;
+    const session = sessions.get(normalizeUserId(userId));
+    
+    if (!session) {
+      return res.json({ running: true, tabs: [] });
+    }
+    
+    const tabs = [];
+    for (const [listItemId, group] of session.tabGroups) {
+      for (const [tabId, tabState] of group) {
+        tabs.push({
+          targetId: tabId,
+          tabId,
+          url: tabState.page.url(),
+          title: await tabState.page.title().catch(() => ''),
+          listItemId
+        });
+      }
+    }
+    
+    res.json({ running: true, tabs });
+  } catch (err) {
+    console.error('List tabs error:', err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// POST /tabs/open - Open tab (alias for POST /tabs, OpenClaw format)
+app.post('/tabs/open', async (req, res) => {
+  try {
+    const { url, userId = 'openclaw', listItemId = 'default' } = req.body;
+    if (!url) {
+      return res.status(400).json({ error: 'url is required' });
+    }
+    
+    const session = await getSession(userId);
+    const group = getTabGroup(session, listItemId);
+    
+    const page = await session.context.newPage();
+    const tabId = crypto.randomUUID();
+    const tabState = createTabState(page);
+    group.set(tabId, tabState);
+    
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    tabState.visitedUrls.add(url);
+    
+    console.log(`[OpenClaw] Tab ${tabId} opened: ${url}`);
+    res.json({ 
+      ok: true,
+      targetId: tabId,
+      tabId,
+      url: page.url(),
+      title: await page.title().catch(() => '')
+    });
+  } catch (err) {
+    console.error('Open tab error:', err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// POST /start - Start browser (OpenClaw expects this)
+app.post('/start', async (req, res) => {
+  try {
+    await ensureBrowser();
+    res.json({ ok: true, profile: 'camoufox' });
+  } catch (err) {
+    res.status(500).json({ ok: false, error: err.message });
+  }
+});
+
+// POST /stop - Stop browser (OpenClaw expects this)
+app.post('/stop', async (req, res) => {
+  try {
+    if (browser) {
+      await browser.close().catch(() => {});
+      browser = null;
+    }
+    sessions.clear();
+    res.json({ ok: true, stopped: true, profile: 'camoufox' });
+  } catch (err) {
+    res.status(500).json({ ok: false, error: err.message });
+  }
+});
+
+// POST /navigate - Navigate (OpenClaw format with targetId in body)
+app.post('/navigate', async (req, res) => {
+  try {
+    const { targetId, url, userId = 'openclaw' } = req.body;
+    if (!url) {
+      return res.status(400).json({ error: 'url is required' });
+    }
+    
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, targetId);
+    if (!found) {
+      return res.status(404).json({ error: 'Tab not found' });
+    }
+    
+    const { tabState } = found;
+    tabState.toolCalls++;
+    
+    const result = await withTabLock(targetId, async () => {
+      await tabState.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      tabState.visitedUrls.add(url);
+      tabState.refs = await buildRefs(tabState.page);
+      return { ok: true, targetId, url: tabState.page.url() };
+    });
+    
+    res.json(result);
+  } catch (err) {
+    console.error('Navigate error:', err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// GET /snapshot - Snapshot (OpenClaw format with query params)
+app.get('/snapshot', async (req, res) => {
+  try {
+    const { targetId, userId = 'openclaw', format = 'text' } = req.query;
+    
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, targetId);
+    if (!found) {
+      return res.status(404).json({ error: 'Tab not found' });
+    }
+    
+    const { tabState } = found;
+    tabState.toolCalls++;
+    tabState.refs = await buildRefs(tabState.page);
+    
+    const ariaYaml = await getAriaSnapshot(tabState.page);
+    
+    // Annotate YAML with ref IDs
+    let annotatedYaml = ariaYaml || '';
+    if (annotatedYaml && tabState.refs.size > 0) {
+      const refsByKey = new Map();
+      for (const [refId, el] of tabState.refs) {
+        const key = `${el.role}:${el.name || ''}`;
+        if (!refsByKey.has(key)) refsByKey.set(key, refId);
+      }
+      
+      const lines = annotatedYaml.split('\n');
+      annotatedYaml = lines.map(line => {
+        const match = line.match(/^(\s*)-\s+(\w+)(?:\s+"([^"]*)")?/);
+        if (match) {
+          const [, indent, role, name] = match;
+          const key = `${role}:${name || ''}`;
+          const refId = refsByKey.get(key);
+          if (refId) {
+            return line.replace(/^(\s*-\s+\w+)/, `$1 [${refId}]`);
+          }
+        }
+        return line;
+      }).join('\n');
+    }
+    
+    res.json({
+      ok: true,
+      format: 'aria',
+      targetId,
+      url: tabState.page.url(),
+      snapshot: annotatedYaml,
+      refsCount: tabState.refs.size
+    });
+  } catch (err) {
+    console.error('Snapshot error:', err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// POST /act - Combined action endpoint (OpenClaw format)
+// Routes to click/type/scroll/press/etc based on 'kind' parameter
+app.post('/act', async (req, res) => {
+  try {
+    const { kind, targetId, userId = 'openclaw', ...params } = req.body;
+    
+    if (!kind) {
+      return res.status(400).json({ error: 'kind is required' });
+    }
+    
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, targetId);
+    if (!found) {
+      return res.status(404).json({ error: 'Tab not found' });
+    }
+    
+    const { tabState } = found;
+    tabState.toolCalls++;
+    
+    const result = await withTabLock(targetId, async () => {
+      switch (kind) {
+        case 'click': {
+          const { ref, selector, doubleClick } = params;
+          if (!ref && !selector) {
+            throw new Error('ref or selector required');
+          }
+          
+          const doClick = async (locatorOrSelector, isLocator) => {
+            const locator = isLocator ? locatorOrSelector : tabState.page.locator(locatorOrSelector);
+            const clickOpts = { timeout: 5000 };
+            if (doubleClick) clickOpts.clickCount = 2;
+            
+            try {
+              await locator.click(clickOpts);
+            } catch (err) {
+              if (err.message.includes('intercepts pointer events')) {
+                await locator.click({ ...clickOpts, force: true });
+              } else {
+                throw err;
+              }
+            }
+          };
+          
+          if (ref) {
+            const locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            await doClick(locator, true);
+          } else {
+            await doClick(selector, false);
+          }
+          
+          await tabState.page.waitForTimeout(500);
+          tabState.refs = await buildRefs(tabState.page);
+          return { ok: true, targetId, url: tabState.page.url() };
+        }
+        
+        case 'type': {
+          const { ref, selector, text, submit } = params;
+          if (!ref && !selector) {
+            throw new Error('ref or selector required');
+          }
+          if (typeof text !== 'string') {
+            throw new Error('text is required');
+          }
+          
+          if (ref) {
+            const locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            await locator.fill(text, { timeout: 10000 });
+            if (submit) await tabState.page.keyboard.press('Enter');
+          } else {
+            await tabState.page.fill(selector, text, { timeout: 10000 });
+            if (submit) await tabState.page.keyboard.press('Enter');
+          }
+          return { ok: true, targetId };
+        }
+        
+        case 'press': {
+          const { key } = params;
+          if (!key) throw new Error('key is required');
+          await tabState.page.keyboard.press(key);
+          return { ok: true, targetId };
+        }
+        
+        case 'scroll':
+        case 'scrollIntoView': {
+          const { ref, direction = 'down', amount = 500 } = params;
+          if (ref) {
+            const locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+          } else {
+            const delta = direction === 'up' ? -amount : amount;
+            await tabState.page.mouse.wheel(0, delta);
+          }
+          await tabState.page.waitForTimeout(300);
+          return { ok: true, targetId };
+        }
+        
+        case 'hover': {
+          const { ref, selector } = params;
+          if (!ref && !selector) throw new Error('ref or selector required');
+          
+          if (ref) {
+            const locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            await locator.hover({ timeout: 5000 });
+          } else {
+            await tabState.page.locator(selector).hover({ timeout: 5000 });
+          }
+          return { ok: true, targetId };
+        }
+        
+        case 'wait': {
+          const { timeMs, text, loadState } = params;
+          if (timeMs) {
+            await tabState.page.waitForTimeout(timeMs);
+          } else if (text) {
+            await tabState.page.waitForSelector(`text=${text}`, { timeout: 30000 });
+          } else if (loadState) {
+            await tabState.page.waitForLoadState(loadState, { timeout: 30000 });
+          }
+          return { ok: true, targetId, url: tabState.page.url() };
+        }
+        
+        case 'close': {
+          await tabState.page.close();
+          found.group.delete(targetId);
+          return { ok: true, targetId };
+        }
+        
+        default:
+          throw new Error(`Unsupported action kind: ${kind}`);
+      }
+    });
+    
+    res.json(result);
+  } catch (err) {
+    console.error('Act error:', err);
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // Graceful shutdown
 process.on('SIGTERM', async () => {
   console.log('Shutting down...');
@@ -936,7 +1278,7 @@ process.on('SIGTERM', async () => {
   process.exit(0);
 });
 
-const PORT = process.env.PORT || 3000;
+const PORT = process.env.PORT || 9377;
 app.listen(PORT, async () => {
   console.log(`🦊 camoufox-browser listening on port ${PORT}`);
   // Pre-launch browser so it's ready for first request