@velanir/openclaw-browserbase

OpenClaw gateway plugin that puts a session broker between the bundled browser tool and Browserbase. The agent keeps using the normal browser tool; this plugin owns the Browserbase session lifecycle that a static wss://connect.browserbase.com?apiKey=… profile cannot provide: explicit session creation with the right options, a persistent per-coworker browser context (durable logins), deterministic release, idle disconnect, and stale-session reaping.

Canonical design: docs/plans/openclaw-browserbase-session-broker-design.md in the platform repo (architecture, mint policy, edge-case matrix, decisions).

How it works

browser tool ──cdpUrl http://127.0.0.1:<port>/?token=…──> broker (this plugin)
                                                            │  mint on WS connect
                                                            ▼
                                       Browserbase POST /v1/sessions + CDP pipe

• GET /json/version never creates a session — discovery and browser status probes are free. A Browserbase session is minted only when OpenClaw opens the advertised WebSocket (first real browser action), then CDP frames are piped byte-for-byte.
• Every session is created with the coworker's persistent context (persist: true), the configured timeout/viewport/captcha/recording policy, and userMetadata tagging for observability and reaping.
• Sessions are created with keepAlive: true, so on downstream disconnect the broker lingers: it closes the CDP connection but keeps the Browserbase session alive (default 60s) and re-dials a fresh CDP connection to it on the next browser action — no new mint, no cooldown, and tabs/login state intact. OpenClaw's browser tool opens short probe connections and reconnects between actions; without linger every probe minted (and released) a billable session and the post-release cooldown starved the real connection. Because each client gets a brand-new CDP connection (fresh id space), a late reply to a previous client's command can never reach the next one. Explicit release, idle disconnect, linger expiry, and gateway shutdown all release the keepAlive session deterministically (keepAlive sessions do not self-terminate, so the reaper also backstops crash leftovers).
• One session per coworker context at a time (Browserbase forbids concurrent sessions on one context), with a short cooldown after release.

OpenClaw config

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 5000,
    remoteCdpHandshakeTimeoutMs: 20000,
    profiles: {
      browserbase: {
        cdpUrl: "http://127.0.0.1:18920/?token=${OCT8_BB_BROKER_TOKEN}",
        attachOnly: true,
        color: "#F97316"
      },
      main: { cdpPort: 18910, color: "#EF4444" }
    }
  },
  plugins: {
    allow: ["browser", "velanir-browserbase"],
    entries: {
      "velanir-browserbase": {
        enabled: true,
        config: {
          projectId: "<browserbase project id>",
          apiKey: "${OCT8_BROWSERBASE_API_KEY}",
          listenPort: 18920,
          token: "${OCT8_BB_BROKER_TOKEN}"
        }
      }
    }
  }
}

Notes:

• attachOnly: true is mandatory: a loopback cdpUrl without it is treated as an OpenClaw-managed local browser.
• apiKey and token must use ${ENV} substitution so no secret lives in openclaw.json on disk. Both env vars belong in the gateway service environment (EC2: /etc/oct8/<profile>.env, mode 0600).
• The broker token must be URL-safe ([A-Za-z0-9._~-]) because it rides in the cdpUrl query string on both the profile and the broker-advertised WebSocket URL. Generate it with base64url or hex; reserved characters like + & # = / change meaning across the URL parse boundaries and break auth. The broker refuses to start with a non-URL-safe token.
• The broker binds 127.0.0.1 only and requires the token on every request and WebSocket upgrade.
• Keep a local Chrome profile (main above) as fallback; OpenClaw never auto-falls back — switching profiles is a model decision.

Config reference

See openclaw.plugin.json for the full schema. Defaults implement the locked v1 policy: timeout 3600 s, viewport 1280×900, captcha solving on, recording on, ignoreCertificateErrors: false, per-coworker context with persist: true, linger 60 s, cooldown 3 s, idle disconnect 15 min, reaper every 5 min, no proxies (proxies: [] passes through to session creation when set).

Compatibility

The package supports OpenClaw >=2026.6.5 <2026.7.0. Version 0.1.4 widened the metadata from an exact 2026.6.5 pin after Martina Reyes loaded the broker tools successfully on OpenClaw 2026.6.6.

Agent tools

• browserbase_session_status — session id, expiry, idle time, context id.
• browserbase_live_view — interactive Live View URL for human 2FA/SSO handoff. The URL controls the browser; share it only with the human who must act.
• browserbase_session_release — release the session when browser work is done; logins persist in the context.

Operations

• Sessions carry userMetadata: broker: "velanir-browserbase", a stable per-gateway instance key, bootId, leaseId, plus any configured metadata tags (org, coworker). The reaper only ever touches sessions whose instance matches its own gateway.
• Gateway stop releases the active session (bounded); a boot-time sweep plus the interval reaper release crash leftovers.
• The per-coworker context id persists in <state-dir>/velanir-browserbase/state.json (0600). Deleting it forces a fresh context (one-time re-login on every site).
• Logs redact the API key, broker token, and URL secrets.
• Known limitation: /json/list responses carry no per-target webSocketDebuggerUrl (the broker exposes one multiplexed connection), so OpenClaw's per-target JS-termination recovery path no-ops on this profile. Tab management itself is unaffected — OpenClaw drives tabs Playwright-first over the piped connection, with these HTTP endpoints as fallback.

Development

pnpm --filter @velanir/openclaw-browserbase build
pnpm --filter @velanir/openclaw-browserbase check-types
pnpm --filter @velanir/openclaw-browserbase test

Live integration tests are skipped unless BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID (and optionally BROWSERBASE_API_URL) are set in the environment. They mint real (billed) sessions tagged broker: "velanir-browserbase" with a dedicated test instance key and release them on completion.