From aa21d4ea7e9aab034acbf0b13f8c3575057c5c54 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 24 Apr 2026 08:27:01 +0100 Subject: [PATCH] fix(browser): clarify existing-session timeout limits --- CHANGELOG.md | 1 + docs/gateway/troubleshooting.md | 1 + extensions/browser/src/browser-tool.test.ts | 10 ++++++++++ extensions/browser/src/browser-tool.ts | 1 + 4 files changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf95d2c2994..0597b527180 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,7 @@ Docs: https://docs.openclaw.ai ### Fixes +- Browser/tool: tell agents not to pass per-call `timeoutMs` on existing-session evaluate and other Chrome MCP actions that reject timeout overrides. - Voice-call/Telnyx: preserve inbound/outbound callback metadata and read transcription text from Telnyx's current `transcription_data` payload. - Codex harness: send verbose tool progress to chat channels for native app-server runs, matching the Pi harness `/verbose on` and `/verbose full` behavior. (#70966) Thanks @jalehman. - Codex models: fetch paginated Codex app-server model catalogs, mark truncated `/codex models` output, and keep ChatGPT OAuth defaults on the `openai-codex/gpt-5.5` route instead of the OpenAI API-key route. diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index ee5b076afb7..c946715be0a 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -482,6 +482,7 @@ Common signatures: - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP upload hooks need snapshot refs, not CSS selectors. - `existing-session file uploads currently support one file at a time.` → send one upload per call on Chrome MCP profiles. - `existing-session dialog handling does not support timeoutMs.` → dialog hooks on Chrome MCP profiles do not support timeout overrides. +- `existing-session evaluate does not support timeoutMs overrides.` → omit `timeoutMs` for `act:evaluate` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required. - `response body is not supported for existing-session profiles yet.` → `responsebody` still requires a managed browser or raw CDP profile. - stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `openclaw browser stop --browser-profile ` to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway. diff --git a/extensions/browser/src/browser-tool.test.ts b/extensions/browser/src/browser-tool.test.ts index 6f506eef77c..b33eae01974 100644 --- a/extensions/browser/src/browser-tool.test.ts +++ b/extensions/browser/src/browser-tool.test.ts @@ -299,6 +299,16 @@ async function runSnapshotToolCall(params: { await tool.execute?.("call-1", { action: "snapshot", target: "host", ...params }); } +describe("browser tool description", () => { + it("warns agents about existing-session act timeout limits", () => { + const tool = createBrowserTool(); + + expect(tool.description).toContain('profile="user"'); + expect(tool.description).toContain("omit timeoutMs on act:evaluate"); + expect(tool.description).toContain("existing-session profiles"); + }); +}); + describe("browser tool snapshot maxChars", () => { registerBrowserToolAfterEachReset(); diff --git a/extensions/browser/src/browser-tool.ts b/extensions/browser/src/browser-tool.ts index beb9c5c1451..b0792674b9c 100644 --- a/extensions/browser/src/browser-tool.ts +++ b/extensions/browser/src/browser-tool.ts @@ -382,6 +382,7 @@ export function createBrowserTool(opts?: { "Control the browser via OpenClaw's browser control server (status/start/stop/profiles/tabs/open/snapshot/screenshot/actions).", "Browser choice: omit profile by default for the isolated OpenClaw-managed browser (`openclaw`).", 'For the logged-in user browser, use profile="user". A supported Chromium-based browser (v144+) must be running on the selected host or browser node. Use only when existing logins/cookies matter and the user is present.', + 'For profile="user" or other existing-session profiles, omit timeoutMs on act:evaluate, hover, scrollIntoView, drag, select, and fill; that driver rejects per-call timeout overrides for those actions.', 'When a node-hosted browser proxy is available, the tool may auto-route to it. Pin a node with node= or target="node".', "When using refs from snapshot (e.g. e12), keep the same tab: prefer passing targetId from the snapshot response into subsequent actions (act/click/type/etc).", 'For stable, self-resolving refs across calls, use snapshot with refs="aria" (Playwright aria-ref ids). Default refs="role" are role+name-based.',