Support existing-session browser CDP endpoints (#91736)

lifuyue · codex · web-flow · commit ac21e89c13e4 · 2026-06-10T10:44:35.000-04:00
* Support existing-session browser CDP endpoints

* Fix browser existing-session test fixture type

---------

Co-authored-by: OpenAI Codex &lt;codex@openai.com&gt;
diff --git a/docs/cli/browser.md b/docs/cli/browser.md
@@ -280,10 +280,14 @@ Use the built-in `user` profile, or create your own `existing-session` profile:
 openclaw browser --browser-profile user tabs
 openclaw browser create-profile --name chrome-live --driver existing-session
 openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
+openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222
 openclaw browser --browser-profile chrome-live tabs
 ```
 
-This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
+The default existing-session path is host-only Chrome MCP auto-connect. If the browser is already
+running with a DevTools endpoint, pass `--cdp-url` so Chrome MCP attaches to that endpoint instead.
+For Docker, Browserless, or other remote setups where Chrome MCP semantics are not needed, use a
+CDP profile.
 
 Current existing-session limits:
 
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
@@ -442,12 +442,17 @@ See [Inferred commitments](/concepts/commitments).
   the selected host or through a connected browser node.
 - `existing-session` profiles can set `userDataDir` to target a specific
   Chromium-based browser profile such as Brave or Edge.
+- `existing-session` profiles can set `cdpUrl` when Chrome is already running
+  behind a DevTools HTTP(S) discovery endpoint or direct WS(S) endpoint. In that
+  mode OpenClaw passes the endpoint to Chrome MCP instead of using auto-connect;
+  `userDataDir` is ignored for Chrome MCP launch arguments.
 - `existing-session` profiles keep the current Chrome MCP route limits:
   snapshot/ref-driven actions instead of CSS-selector targeting, one-file upload
   hooks, no dialog timeout overrides, no `wait --load networkidle`, and no
   `responsebody`, PDF export, download interception, or batch actions.
-- Local managed `openclaw` profiles auto-assign `cdpPort` and `cdpUrl`; only
-  set `cdpUrl` explicitly for remote CDP.
+- Local managed `openclaw` profiles auto-assign `cdpPort` and `cdpUrl`; set
+  `cdpUrl` explicitly only for remote CDP profiles or existing-session endpoint
+  attach.
 - Local managed profiles can set `executablePath` to override the global
   `browser.executablePath` for that profile. Use this to run one profile in
   Chrome and another in Brave.
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
@@ -244,7 +244,9 @@ main model can read the screenshot directly.
 <Accordion title="Ports and reachability">
 
 - Control service binds to loopback on a port derived from `gateway.port` (default `18791` = gateway + 2). Overriding `gateway.port` or `OPENCLAW_GATEWAY_PORT` shifts the derived ports in the same family.
-- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl`; set those only for remote CDP. `cdpUrl` defaults to the managed local CDP port when unset.
+- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl`; set those only for
+  remote CDP profiles or existing-session endpoint attach. `cdpUrl` defaults to
+  the managed local CDP port when unset.
 - `remoteCdpTimeoutMs` applies to remote and `attachOnly` CDP HTTP reachability
   checks and tab-opening HTTP requests; `remoteCdpHandshakeTimeoutMs` applies to
   their CDP WebSocket handshakes.
@@ -298,7 +300,7 @@ main model can read the screenshot directly.
 - `color` (top-level and per-profile) tints the browser UI so you can see which profile is active.
 - Default profile is `openclaw` (managed standalone). Use `defaultProfile: "user"` to opt into the signed-in user browser.
 - Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
-- `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do not set `cdpUrl` for that driver.
+- `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. It can attach through Chrome MCP auto-connect, or through `cdpUrl` when you already have a DevTools endpoint for the running browser.
 - Set `browser.profiles.<name>.userDataDir` when an existing-session profile should attach to a non-default Chromium user profile (Brave, Edge, etc.). This path also accepts `~` for your OS home directory.
 
 </Accordion>
@@ -687,6 +689,9 @@ What to check if attach does not work:
 - the target Chromium-based browser is version `144+`
 - remote debugging is enabled in that browser's inspect page
 - the browser showed and you accepted the attach consent prompt
+- if Chrome was started with an explicit `--remote-debugging-port`, set
+  `browser.profiles.<name>.cdpUrl` to that DevTools endpoint instead of relying
+  on Chrome MCP auto-connect
 - `openclaw doctor` migrates old extension-based browser config and checks that
   Chrome is installed locally for default auto-connect profiles, but it cannot
   enable browser-side remote debugging for you
diff --git a/extensions/browser/src/browser/chrome-mcp.test.ts b/extensions/browser/src/browser/chrome-mcp.test.ts
@@ -120,6 +120,25 @@ function createFakeSession(): ChromeMcpSession {
   } as unknown as ChromeMcpSession;
 }
 
+function createToolErrorSession(message: string): ChromeMcpSession {
+  const callTool = vi.fn(async () => ({
+    isError: true,
+    content: [{ type: "text", text: message }],
+  }));
+  return {
+    client: {
+      callTool,
+      listTools: vi.fn().mockResolvedValue({ tools: [{ name: "list_pages" }] }),
+      close: vi.fn().mockResolvedValue(undefined),
+      connect: vi.fn().mockResolvedValue(undefined),
+    },
+    transport: {
+      pid: 123,
+    },
+    ready: Promise.resolve(),
+  } as unknown as ChromeMcpSession;
+}
+
 describe("chrome MCP page parsing", () => {
   beforeEach(async () => {
     await resetChromeMcpSessionsForTest();
@@ -153,6 +172,33 @@ describe("chrome MCP page parsing", () => {
     ]);
   });
 
+  it("suggests cdpUrl when auto-connect cannot read DevToolsActivePort", async () => {
+    setChromeMcpSessionFactoryForTest(async () =>
+      createToolErrorSession(
+        "Could not connect to Chrome in /tmp/chrome-profile. Cause: ENOENT: no such file or directory, open '/tmp/chrome-profile/DevToolsActivePort'",
+      ),
+    );
+
+    await expect(
+      listChromeMcpTabs("chrome-live", { userDataDir: "/tmp/chrome-profile" }),
+    ).rejects.toThrow(/set browser\.profiles\.chrome-live\.cdpUrl/);
+  });
+
+  it("names the configured endpoint when endpoint attach fails", async () => {
+    setChromeMcpSessionFactoryForTest(async () =>
+      createToolErrorSession("Could not connect to Chrome: ECONNREFUSED"),
+    );
+
+    await expect(
+      listChromeMcpTabs("chrome-live", {
+        cdpUrl:
+          "https://alice:supersecretpasswordvalue1234@example.com/chrome?token=supersecrettokenvalue1234567890",
+      }),
+    ).rejects.toThrow(
+      /configured Chrome endpoint \(https:\/\/example\.com\/chrome\?token=\*\*\*\)/,
+    );
+  });
+
   it("reads screenshot files with the extension written by chrome-devtools-mcp", async () => {
     const factory: ChromeMcpSessionFactory = async () => createFakeSession();
     setChromeMcpSessionFactoryForTest(factory);
diff --git a/extensions/browser/src/browser/chrome-mcp.ts b/extensions/browser/src/browser/chrome-mcp.ts
@@ -143,6 +143,9 @@ const CHROME_MCP_HANDSHAKE_TIMEOUT_MS = 30_000;
 const CHROME_MCP_STDERR_MAX_BYTES = 8 * 1024;
 const CHROME_MCP_PROCESS_EXIT_GRACE_MS = 250;
 const CDP_URL_IN_TEXT_RE = /\b(?:https?|wss?):\/\/[^\s"'<>`]+/gi;
+const DEVTOOLS_ACTIVE_PORT_RE = /\bDevToolsActivePort\b/i;
+const CHROME_CONNECTION_TOOL_ERROR_RE =
+  /(?:Could not connect to Chrome|DevToolsActivePort|ECONNREFUSED|ECONNRESET|websocket|timed out)/i;
 const STALE_SELECTED_PAGE_ERROR =
   "The selected page has been closed. Call list_pages to see open pages.";
 
@@ -267,6 +270,41 @@ function extractToolErrorMessage(result: ChromeMcpToolResult, name: string): str
   return message || `Chrome MCP tool "${name}" failed.`;
 }
 
+function formatChromeMcpEndpointForDiagnostic(browserUrl: string): string {
+  return redactToolPayloadText(redactCdpUrl(browserUrl) ?? browserUrl);
+}
+
+function formatChromeMcpToolErrorMessage(params: {
+  profileName: string;
+  options: NormalizedChromeMcpProfileOptions;
+  toolName: string;
+  message: string;
+}): string {
+  const detail = redactChromeMcpDiagnosticTextWithLocalPaths(params.message);
+  const profileLabel = redactChromeMcpProfileLabelForDiagnostic(params.profileName);
+  if (params.options.browserUrl && CHROME_CONNECTION_TOOL_ERROR_RE.test(params.message)) {
+    return (
+      `Chrome MCP tool "${params.toolName}" failed for profile "${profileLabel}" while using ` +
+      `the configured Chrome endpoint (${formatChromeMcpEndpointForDiagnostic(params.options.browserUrl)}). ` +
+      `Details: ${detail}`
+    );
+  }
+  if (
+    !params.options.browserUrl &&
+    params.options.userDataDir &&
+    DEVTOOLS_ACTIVE_PORT_RE.test(params.message)
+  ) {
+    const cdpUrlPath = path.isAbsolute(params.profileName)
+      ? "this existing-session profile's cdpUrl"
+      : `browser.profiles.${params.profileName}.cdpUrl`;
+    return (
+      `${detail} If this browser was started with --remote-debugging-port, set ${cdpUrlPath} ` +
+      "to that DevTools endpoint instead of relying on Chrome MCP auto-connect."
+    );
+  }
+  return detail;
+}
+
 function shouldReconnectForToolError(name: string, message: string): boolean {
   return name === "list_pages" && message.includes(STALE_SELECTED_PAGE_ERROR);
 }
@@ -1194,9 +1232,10 @@ async function callTool(
   if (signal?.aborted) {
     throw signal.reason ?? new Error("aborted");
   }
+  const normalizedProfileOptions = normalizeChromeMcpOptions(profileOptions);
 
   for (let attempt = 0; attempt < 2; attempt += 1) {
-    const lease = await leaseSession(profileName, profileOptions, options);
+    const lease = await leaseSession(profileName, normalizedProfileOptions, options);
     const rawCall = lease.session.client.callTool({
       name,
       arguments: args,
@@ -1273,7 +1312,14 @@ async function callTool(
           continue;
         }
       }
-      throw new Error(message);
+      throw new Error(
+        formatChromeMcpToolErrorMessage({
+          profileName,
+          options: normalizedProfileOptions,
+          toolName: name,
+          message,
+        }),
+      );
     }
     return result;
   }
diff --git a/extensions/browser/src/browser/config-mutations.ts b/extensions/browser/src/browser/config-mutations.ts
@@ -120,6 +120,7 @@ export async function createBrowserProfileConfig(params: {
         nextProfileConfig = {
           cdpUrl: params.parsedCdpUrl,
           ...(params.driver ? { driver: params.driver } : {}),
+          ...(params.driver === "existing-session" ? { attachOnly: true } : {}),
           color: profileColor,
         };
       } else if (params.driver === "existing-session") {
diff --git a/extensions/browser/src/browser/profiles-service.test.ts b/extensions/browser/src/browser/profiles-service.test.ts
@@ -275,20 +275,57 @@ describe("BrowserProfilesService", () => {
     expect(profiles["chrome-live"]?.attachOnly).toBe(true);
   });
 
-  it("rejects driver=existing-session when cdpUrl is provided", async () => {
+  it("accepts driver=existing-session with cdpUrl", async () => {
     const resolved = resolveBrowserConfig({});
-    const { ctx } = createCtx(resolved);
+    const { ctx, state } = createCtx(resolved);
     vi.mocked(getRuntimeConfig).mockReturnValue({ browser: { profiles: {} } });
 
+    const service = createBrowserProfilesService(ctx);
+    const result = await service.createProfile({
+      name: "chrome-live",
+      driver: "existing-session",
+      cdpUrl: "http://127.0.0.1:9222/",
+    });
+
+    expect(result.transport).toBe("chrome-mcp");
+    expect(result.cdpPort).toBeNull();
+    expect(result.cdpUrl).toBe("http://127.0.0.1:9222");
+    expect(result.userDataDir).toBeNull();
+    const resolvedProfile = state.resolved.profiles["chrome-live"];
+    expect(resolvedProfile?.driver).toBe("existing-session");
+    expect(resolvedProfile?.attachOnly).toBe(true);
+    expect(resolvedProfile?.cdpUrl).toBe("http://127.0.0.1:9222");
+    const profiles = writtenBrowserConfig().profiles as Record<
+      string,
+      { cdpUrl?: string; driver?: string }
+    >;
+    expect(profiles["chrome-live"]?.driver).toBe("existing-session");
+    expect(profiles["chrome-live"]?.cdpUrl).toBe("http://127.0.0.1:9222");
+  });
+
+  it("rejects private-network cdpUrl for existing-session when strict SSRF mode is enabled", async () => {
+    const resolved = resolveBrowserConfig({
+      ssrfPolicy: { dangerouslyAllowPrivateNetwork: false },
+    });
+    const { ctx } = createCtx(resolved);
+
+    vi.mocked(getRuntimeConfig).mockReturnValue({
+      browser: {
+        ssrfPolicy: { dangerouslyAllowPrivateNetwork: false },
+        profiles: {},
+      },
+    });
+
     const service = createBrowserProfilesService(ctx);
 
     await expect(
       service.createProfile({
         name: "chrome-live",
         driver: "existing-session",
-        cdpUrl: "http://127.0.0.1:9222",
+        cdpUrl: "http://10.0.0.42:9222",
       }),
-    ).rejects.toThrow(/does not accept cdpUrl/i);
+    ).rejects.toThrow(/private\/internal\/special-use ip address/i);
+    expect(writeConfigFile).not.toHaveBeenCalled();
   });
 
   it("creates existing-session profiles with an explicit userDataDir", async () => {
diff --git a/extensions/browser/src/browser/profiles-service.ts b/extensions/browser/src/browser/profiles-service.ts
@@ -101,11 +101,6 @@ export function createBrowserProfilesService(ctx: BrowserRouteContext) {
     }
 
     if (rawCdpUrl) {
-      if (driver === "existing-session") {
-        throw new BrowserValidationError(
-          "driver=existing-session does not accept cdpUrl; it attaches via the Chrome MCP auto-connect flow",
-        );
-      }
       let parsed: ReturnType<typeof parseHttpUrl>;
       try {
         parsed = parseHttpUrl(rawCdpUrl, "browser.profiles.cdpUrl");
@@ -139,7 +134,7 @@ export function createBrowserProfilesService(ctx: BrowserRouteContext) {
       profile: name,
       transport: capabilities.usesChromeMcp ? "chrome-mcp" : "cdp",
       cdpPort: capabilities.usesChromeMcp ? null : resolved.cdpPort,
-      cdpUrl: capabilities.usesChromeMcp ? null : resolved.cdpUrl,
+      cdpUrl: resolved.cdpUrl || null,
       userDataDir: resolved.userDataDir ?? null,
       color: resolved.color,
       isRemote: !resolved.cdpIsLoopback,
diff --git a/extensions/browser/src/browser/routes/basic.ts b/extensions/browser/src/browser/routes/basic.ts
@@ -204,7 +204,7 @@ async function buildBrowserStatus(req: BrowserRequest, ctx: BrowserRouteContext)
       ? getChromeMcpPid(profileCtx.profile.name)
       : (profileState?.running?.pid ?? null),
     cdpPort: capabilities.usesChromeMcp ? null : profileCtx.profile.cdpPort,
-    cdpUrl: capabilities.usesChromeMcp ? null : (redactCdpUrl(profileCtx.profile.cdpUrl) ?? null),
+    cdpUrl: profileCtx.profile.cdpUrl ? (redactCdpUrl(profileCtx.profile.cdpUrl) ?? null) : null,
     chosenBrowser: profileState?.running?.exe.kind ?? null,
     detectedBrowser,
     detectedExecutablePath,
diff --git a/extensions/browser/src/browser/server-context.existing-session.test.ts b/extensions/browser/src/browser/server-context.existing-session.test.ts
@@ -33,6 +33,7 @@ const chromeMcp = chromeMcpMock;
 type ChromeLiveProfile = {
   driver?: string;
   name?: string;
+  cdpUrl?: string;
   userDataDir?: string;
 };
 
@@ -138,6 +139,30 @@ describe("browser server-context existing-session profile", () => {
     expect(listOptions).toEqual({ ephemeral: true });
   });
 
+  it("reports endpoint cdpUrl for existing-session profiles", async () => {
+    fs.mkdirSync("/tmp/brave-profile", { recursive: true });
+    const state = makeState();
+    state.resolved.profiles["chrome-live"] = {
+      ...state.resolved.profiles["chrome-live"],
+      cdpUrl: "http://openclaw:relay-token@127.0.0.1:9222",
+    };
+    const ctx = createBrowserRouteContext({ getState: () => state });
+
+    const profiles = await ctx.listProfiles();
+
+    expect(profiles).toHaveLength(1);
+    expect(profiles[0]?.transport).toBe("chrome-mcp");
+    expect(profiles[0]?.cdpPort).toBeNull();
+    expect(profiles[0]?.cdpUrl).toBe("http://127.0.0.1:9222");
+    const [, ensuredProfile] =
+      (
+        vi.mocked(chromeMcp.ensureChromeMcpAvailable).mock.calls as unknown as Array<
+          [string, ChromeLiveProfile, { ephemeral?: boolean; timeoutMs?: number }]
+        >
+      )[0] ?? [];
+    expect(ensuredProfile?.cdpUrl).toBe("http://openclaw:relay-token@127.0.0.1:9222");
+  });
+
   it("keeps the next real attach on the normal sticky session path after an idle status probe", async () => {
     fs.mkdirSync("/tmp/brave-profile", { recursive: true });
     const state = makeState();
diff --git a/extensions/browser/src/browser/server-context.ts b/extensions/browser/src/browser/server-context.ts
@@ -233,7 +233,7 @@ export function createBrowserRouteContext(opts: ContextOptions): BrowserRouteCon
         name,
         transport: capabilities.usesChromeMcp ? "chrome-mcp" : "cdp",
         cdpPort: capabilities.usesChromeMcp ? null : profile.cdpPort,
-        cdpUrl: capabilities.usesChromeMcp ? null : (redactCdpUrl(profile.cdpUrl) ?? null),
+        cdpUrl: profile.cdpUrl ? (redactCdpUrl(profile.cdpUrl) ?? null) : null,
         color: profile.color,
         driver: profile.driver,
         running,
diff --git a/extensions/browser/src/cli/browser-cli-manage.test.ts b/extensions/browser/src/cli/browser-cli-manage.test.ts
diff --git a/extensions/browser/src/cli/browser-cli-manage.ts b/extensions/browser/src/cli/browser-cli-manage.ts
