pixiebrix · twschiller · May 30, 2026 · May 30, 2026 · May 30, 2026
diff --git a/docs/src/content/docs/openclaw.md b/docs/src/content/docs/openclaw.md
@@ -1,13 +1,102 @@
 ---
 title: Use with OpenClaw
-description: Drive OpenClaw against a Browserbase session that has the agent-browser-shield extension loaded.
+description: Run agent-browser-shield with OpenClaw — either inside your own browser profile via the existing-session driver, or in a Browserbase remote CDP session.
 ---
 
 OpenClaw's [managed browser profile](https://docs.openclaw.ai/tools/browser) is
-deliberately isolated and does not accept Chromium extensions. To run OpenClaw
-with `agent-browser-shield` active, point it at a remote browser that does
-support extension upload — currently only
-[Browserbase](https://docs.browserbase.com/platform/browser/core-features/browser-extensions#browser-extensions).
+deliberately isolated and does not accept Chromium extensions, so
+`agent-browser-shield` has to ride along on a browser OpenClaw merely *attaches*
+to. Two paths work:
+
+- **Local browser via existing-session** — install the extension in your own
+  Chrome/Brave/Edge profile and have OpenClaw attach over CDP. Best for
+  development and for tasks that need your logged-in sessions.
+- **Browserbase remote CDP** — upload a ZIP of the extension to Browserbase and
+  point OpenClaw at the session's connect URL. Best for headless / cloud runs.
+
+The rest of this page covers both.
+
+## Letting OpenClaw run your browser profile
+
+This is the path you want when you'd rather hand OpenClaw the keys to a real
+profile than spin up a remote browser. The extension installs normally; OpenClaw
+attaches via CDP and inherits whatever's already loaded.
+
+### 1. Install the extension into the profile
+
+Follow [Install](/agent-browser-shield/install/) through `bun run build`, then
+in the Chromium-based browser whose profile OpenClaw will drive:
+
+1. Open `chrome://extensions` (or `brave://extensions`, `edge://extensions`).
+2. Enable **Developer mode**.
+3. Click **Load unpacked** and select `extension/dist/`.
+4. Pin the shield icon so it's easy to confirm the extension is live.
+
+Use a dedicated browser profile for agent runs if you don't want OpenClaw
+touching your everyday tabs and cookies — create one from the browser's profile
+switcher and install the extension only there.
+
+### 2. Enable remote debugging and let OpenClaw attach
+
+OpenClaw's `existing-session` driver (Chrome DevTools MCP under the hood)
+attaches to a running Chromium instance. The built-in `user` profile targets
+your default Chrome installation; add a custom profile for Brave, Edge, or a
+non-default Chrome user data dir.
+
+`~/.openclaw/config.json5`:
+
+```json5
+{
+  browser: {
+    enabled: true,
+    defaultProfile: "shielded-local",
+    profiles: {
+      "shielded-local": {
+        driver: "existing-session",
+        attachOnly: true,
+        // Point at the user-data-dir that has the extension installed.
+        // Omit for the default Chrome profile (use the built-in `user` profile instead).
+        userDataDir: "~/Library/Application Support/Google/Chrome/Profile 2",
+        color: "#F97316",
+      },
+    },
+  },
+}
+```
+
+Then, with the browser running:
+
+1. Open `chrome://inspect` (or the equivalent for your browser) and enable
+   remote debugging.
+
+2. Start the session:
+
+   ```sh
+   openclaw browser --browser-profile shielded-local start
+   openclaw browser --browser-profile shielded-local tabs
+   ```
+
+3. Approve the connection prompt the browser shows when OpenClaw attaches.
+
+Because `attachOnly: true` is set, OpenClaw will not launch or kill the browser
+— keep it running for the duration of the agent task. Skip to [Verify](#verify)
+to confirm the shield is active.
+
+### Caveats for the local-profile path
+
+- **Your cookies are in scope.** Anything the agent navigates to is acting as
+  *you*. Use a separate profile for anything sensitive.
+- **No isolation between tabs.** OpenClaw drives whatever tab you point it at,
+  including ones you opened manually.
+- **Extension reloads need a tab refresh.** After `bun run watch` rebuilds,
+  click reload at `chrome://extensions` and refresh the agent's tabs — OpenClaw
+  won't do it for you.
+
+## Using a Browserbase remote CDP session
+
+When OpenClaw can't attach to a local browser — headless runs, CI, or anywhere
+you want disposable browser state — upload the extension to Browserbase and have
+OpenClaw connect over CDP.
 
 The flow:
 
@@ -17,13 +106,13 @@ The flow:
    connect URL.
 4. Configure OpenClaw to use that URL as a remote CDP profile.
 
-## 1. Package the extension
+### 1. Package the extension
 
 Follow [Install](/agent-browser-shield/install/) through `bun run package`.
 You'll end up with `output/extension.zip` whose `manifest.json` sits at the
 archive root.
 
-## 2. Upload to Browserbase
+### 2. Upload to Browserbase
 
 Grab `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` from *Settings → API
 Keys* at <https://www.browserbase.com>:
@@ -40,7 +129,7 @@ curl -X POST https://api.browserbase.com/v1/extensions \
 Stash the returned `id` — it's reusable across sessions until you upload a new
 build.
 
-## 3. Create a session with the extension attached
+### 3. Create a session with the extension attached
 
 The extension is bound to the **session**, not the project. A session created
 without `extensionId` runs unguarded — there is no way to attach the extension
@@ -58,7 +147,7 @@ curl -X POST https://api.browserbase.com/v1/sessions \
 Capture `connectUrl` from the response. It looks like
 `wss://connect.browserbase.com?apiKey=...&sessionId=...`.
 
-## 4. Point OpenClaw at the session
+### 4. Point OpenClaw at the session
 
 Add a remote CDP profile to your OpenClaw config:
 
@@ -90,14 +179,17 @@ On the first non-trivial page load, look for:
 - `[data-abs-rule="<rule-id>"]` attributes in the DOM.
 - Inline `[PII masked]` / `[secret masked]` chips on pages with sensitive data.
 
-If none of those markers appear, the extension is not attached — re-check that
-the session was created with the `extensionId` from step 2. There is no way to
-add the extension to an already-running session.
+If none of those markers appear, the extension is not attached:
+
+- *Local profile:* confirm the shield is pinned in the browser whose
+  `userDataDir` OpenClaw is attached to, and reload the agent's tabs.
+- *Browserbase:* confirm the session was created with the `extensionId` from
+  step 2 — there's no way to add the extension to an already-running session.
 
 ## Why not OpenClaw's managed profile?
 
 OpenClaw's `openclaw` profile launches a dedicated Chromium under its own
 control service and intentionally rejects unpacked extensions for isolation.
-Pointing OpenClaw at a Browserbase CDP session moves the agent's traffic onto a
-browser that *does* allow extension upload, without giving up OpenClaw's control
-loop.
+Both paths above work around that: existing-session reuses a browser you
+control, and Browserbase moves traffic onto a remote browser that accepts
+extension upload — neither gives up OpenClaw's control loop.