openclaw/docs/tools
Viz 4cfc8cd5be
fix(browser): discover CDP websocket from bare ws:// URL before attach (#68715)
* fix(browser): discover CDP websocket from bare ws:// URL before attach

When browser.cdpUrl is set to a bare ws://host:port (no /devtools/ path), ensureBrowserAvailable would call isChromeReachable -> canOpenWebSocket against the URL verbatim. Chrome only accepts WebSocket upgrades at the specific path returned by /json/version, so the handshake failed immediately with HTTP 400. With attachOnly: true, that surfaced as:

  Browser attachOnly is enabled and profile "openclaw" is not running.

even though the CDP endpoint was reachable and the profile was healthy. Reproduced by the new tests in chrome.test.ts and cdp.test.ts (#68027).

Fix: introduce isDirectCdpWebSocketEndpoint(url) — true only when a ws/wss URL has a /devtools/<kind>/<id> handshake path. Route any other ws/wss cdpUrl (including the bare ws://host:port shape) through HTTP /json/version discovery by normalising the scheme via the existing normalizeCdpHttpBaseForJsonEndpoints helper. Apply this in isChromeReachable, getChromeWebSocketUrl, and createTargetViaCdp. Direct WS endpoints with a /devtools/ path are still opened without an extra discovery round-trip.

Fixes #68027

* test(browser): add seeded fuzz coverage for CDP URL helpers

Adds property-based / seeded-fuzz tests for the URL helpers the
attachOnly CDP fix depends on (#68027):

  - isWebSocketUrl
  - isDirectCdpWebSocketEndpoint
  - normalizeCdpHttpBaseForJsonEndpoints
  - parseBrowserHttpUrl
  - redactCdpUrl
  - appendCdpPath
  - getHeadersWithAuth

Follows the existing repo convention (see
src/gateway/http-common.fuzz.test.ts): no fast-check dep, small
mulberry32 PRNG + hand-rolled generators, deterministic per-describe
seeds so failures are reproducible.

Lifts cdp.helpers.ts coverage from 77.77% -> 89.54% statements,
67.9% -> 80.24% branches, 78% -> 90% lines. Remaining uncovered
lines are inside the WS sender internals (createCdpSender,
withCdpSocket, fetchCdpChecked rate-limit branch), which require
integration-style mocks and are unrelated to the attachOnly fix.

* test(browser): drive cdp.helpers/cdp/chrome to 100% coverage

Lifts the three files touched by the #68027 attachOnly fix to 100% statements/branches/functions/lines across the extensions test suite. Adds cdp.helpers.internal.test.ts, cdp.internal.test.ts, and chrome.internal.test.ts covering error paths, branch matrices, CDP session helpers, Chrome spawn/launch/stop flows, and canRunCdpHealthCommand. Defensively unreachable guards are annotated with c8 ignore + inline justifications.

* fix(browser): restore WS fallback for non-/devtools ws:// CDP URLs

When /json/version discovery is unavailable (or returns no
webSocketDebuggerUrl), fall back to treating the original bare ws/wss
URL as a direct WebSocket endpoint. This preserves the #68027 fix for
Chrome's debug port while restoring compatibility with Browserless/
Browserbase-style providers that expose a direct WebSocket root without
a /json/version endpoint.

Priority order for bare ws/wss cdpUrl inputs:
  1. /devtools/<kind>/<id> URL \u2192 direct handshake, no discovery (unchanged)
  2. bare ws/wss root \u2192 try HTTP discovery first; if discovery returns a
     webSocketDebuggerUrl use it; otherwise fall back to the original URL
     as a direct WS endpoint
  3. HTTP/HTTPS URL \u2192 HTTP discovery only, no fallback (unchanged)

Affected call sites: isChromeReachable, getChromeWebSocketUrl,
createTargetViaCdp.

Also renames a misleading test ('still enforces SSRF policy for direct
WebSocket URLs') to accurately describe what it tests: SSRF enforcement
on the navigation target URL, not on the CDP endpoint.

New tests added for all three fallback paths. Coverage remains 100% on
all three touched files (238 tests).

* fix: browser attachOnly bare ws CDP follow-ups (#68715) (thanks @visionik)
2026-04-19 05:43:39 -04:00
..
acp-agents.md fix: raise acpx runtime timeout 2026-04-08 02:36:37 +01:00
agent-send.md docs: reorder Tools & Plugins nav, move Media/devices to Gateway tab, rewrite 4 problem pages with Mintlify components 2026-03-20 11:10:45 -07:00
apply-patch.md fix: default and gate apply_patch like write 2026-03-27 01:14:42 +00:00
brave-search.md docs: refresh brave web search references 2026-04-04 09:19:11 +01:00
browser-linux-troubleshooting.md docs: refresh browser existing-session mirror refs 2026-04-04 20:29:31 +01:00
browser-login.md
browser-wsl2-windows-remote-cdp-troubleshooting.md docs: refresh browser existing-session mirror refs 2026-04-04 20:29:31 +01:00
browser.md fix(browser): discover CDP websocket from bare ws:// URL before attach (#68715) 2026-04-19 05:43:39 -04:00
btw.md
capability-cookbook.md docs: refresh config schema and gateway tool mirrors 2026-04-04 21:43:09 +01:00
clawhub.md docs: refresh plugin install and marketplace refs 2026-04-04 13:22:46 +01:00
code-execution.md refactor(xai): move code_execution into plugin 2026-03-28 21:35:13 +00:00
creating-skills.md docs: refresh clawhub mirror refs 2026-04-04 13:29:07 +01:00
diffs.md Docs: refresh diffs plugin docs 2026-04-02 21:47:55 -04:00
duckduckgo-search.md docs: refresh key-free web search ordering 2026-04-04 09:25:20 +01:00
elevated.md docs: refresh exec host and elevated refs 2026-04-04 18:38:10 +01:00
exa-search.md docs(tools): update Exa Search notes for current API behavior 2026-03-22 21:39:33 -07:00
exec-approvals.md feat: add local exec-policy CLI (#64050) 2026-04-10 01:16:03 -05:00
exec.md fix(exec): remove host obfuscation gating 2026-04-05 18:01:41 +01:00
firecrawl.md docs: refresh Firecrawl and web_fetch config refs 2026-04-04 20:21:16 +01:00
gemini-search.md docs: clarify synthesized web search count behavior 2026-04-04 09:17:49 +01:00
grok-search.md docs: clarify synthesized web search count behavior 2026-04-04 09:17:49 +01:00
image-generation.md refactor: share media normalization across runtimes 2026-04-06 23:50:27 +01:00
index.md fix: route comfy music through shared tool 2026-04-06 02:03:13 +01:00
kimi-search.md docs: clarify synthesized web search count behavior 2026-04-04 09:17:49 +01:00
llm-task.md
lobster.md docs: update Lobster in-process mode and REM preview tooling 2026-04-06 00:40:21 +01:00
loop-detection.md docs: add missing title, remove stale description fields from frontmatter 2026-03-19 15:26:26 -07:00
media-overview.md docs: add media overview page and consolidate TTS duplicate 2026-04-06 16:18:45 +01:00
minimax-search.md docs: refresh minimax multimodal refs 2026-04-04 12:27:47 +01:00
multi-agent-sandbox-tools.md docs: refresh history sanitization tag mirrors 2026-04-04 22:21:26 +01:00
music-generation.md refactor: share media normalization across runtimes 2026-04-06 23:50:27 +01:00
ollama-search.md docs: refresh self-hosted web search references 2026-04-04 09:22:30 +01:00
pdf.md docs: refresh pdf tool model fallback refs 2026-04-04 10:07:16 +01:00
perplexity-search.md docs: refresh perplexity web search references 2026-04-04 09:21:06 +01:00
plugin.md docs: document music generation async flow 2026-04-06 01:49:58 +01:00
reactions.md fix: make docs anchor audit use Mintlify CLI 2026-04-10 21:39:52 +01:00
searxng-search.md docs: refresh key-free web search ordering 2026-04-04 09:25:20 +01:00
skills-config.md docs: clarify setup node-manager refs 2026-04-04 13:34:02 +01:00
skills.md fix(cli-runner): wire OpenClaw skills into Claude CLI 2026-04-10 13:45:02 +01:00
slash-commands.md Add /trace toggle and fix Active Memory diagnostics 2026-04-12 13:20:22 -05:00
subagents.md docs: refresh history sanitization tag mirrors 2026-04-04 22:21:26 +01:00
tavily.md docs(tools): add Exa Search page, align all search provider docs 2026-03-22 21:27:24 -07:00
thinking.md fix: keep Opus 4.7 effort separate from adaptive thinking 2026-04-17 01:26:11 +01:00
tts.md fix: add Google Gemini TTS provider (#67515) (thanks @barronlroth) 2026-04-16 11:54:35 +05:30
video-generation.md fix: bound live video generation smoke 2026-04-14 14:59:01 +01:00
web-fetch.md docs: refresh Firecrawl and web_fetch config refs 2026-04-04 20:21:16 +01:00
web.md docs: refresh Firecrawl and web_fetch config refs 2026-04-04 20:21:16 +01:00