From 4ae1ce4c28ef9c262183e1dcdd535e0dc0ffe08b Mon Sep 17 00:00:00 2001 From: y$un_ Date: Wed, 26 Aug 2026 09:27:30 -0400 Subject: [PATCH] docs: declared local browser profiles must set cdpPort or cdpUrl (#129923) The schema already rejects a hand-declared openclaw or clawd profile that sets neither. Stop telling operators those fields auto-assign. Co-authored-by: Cursor --- docs/gateway/configuration-reference.md | 7 ++++--- docs/tools/browser-linux-troubleshooting.md | 5 +++-- docs/tools/browser.md | 11 ++++++++--- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 37ddabe4fd20..53af3b3b0ab9 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -507,9 +507,10 @@ See [Plugins](/tools/plugin). 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`; set - `cdpUrl` explicitly only for remote CDP profiles or existing-session endpoint - attach. +- Local managed `openclaw` profiles get a `cdpPort` allocated from the managed + range when OpenClaw creates the profile. A profile you declare by hand must + set `cdpPort` itself, or `cdpUrl` for a remote CDP endpoint; the schema + rejects an `openclaw` or `clawd` profile that sets neither. - 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-linux-troubleshooting.md b/docs/tools/browser-linux-troubleshooting.md index fd99813e4187..d8c9cd69f50e 100644 --- a/docs/tools/browser-linux-troubleshooting.md +++ b/docs/tools/browser-linux-troubleshooting.md @@ -149,8 +149,9 @@ Notes: limits: ref-driven actions only, one file per upload, no dialog `timeoutMs` overrides, no `wait --load networkidle`, and no `responsebody`, PDF export, download interception, or batch actions. -- Local `openclaw`-driver profiles auto-assign `cdpPort`/`cdpUrl`; only set - those manually for remote CDP. +- Local `openclaw`-driver profiles get a `cdpPort` allocated when OpenClaw + creates them; a profile you declare by hand must set `cdpPort` itself, or + `cdpUrl` for remote CDP. - Remote CDP profiles accept `http://`, `https://`, `ws://`, and `wss://`. Use HTTP(S) for `/json/version` discovery, or WS(S) when your browser service gives you a direct DevTools socket URL. diff --git a/docs/tools/browser.md b/docs/tools/browser.md index a3d6b4141d53..0bb4a56b23d6 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -298,9 +298,14 @@ main model can read the screenshot directly. - Control service binds to loopback on a port derived from `gateway.port` (default `18791` = gateway + 2). `OPENCLAW_GATEWAY_PORT` takes priority over `gateway.port`; either shifts the derived ports in the same family. -- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` from a range starting 9 ports above the control port (default `18800`-`18899`); set those only for - remote CDP profiles or existing-session endpoint attach. `cdpUrl` defaults to - the managed local CDP port when unset. +- Local `openclaw` profiles use a CDP port range starting 9 ports above the control port (default `18800`-`18899`). OpenClaw allocates from that range for + the implicit default profile and for profiles created with + `openclaw browser create-profile`, writing the chosen `cdpPort` into the + config. A profile you declare by hand must set `cdpPort` itself, or `cdpUrl` + for a remote endpoint: the schema rejects an `openclaw` or `clawd` profile + that sets neither with `Profile must set cdpPort or cdpUrl`. + `existing-session` profiles take the endpoint from `cdpUrl` and ignore + `cdpPort`; `extension` profiles own their relay port and reject `cdpUrl`. - Remote and `attachOnly` CDP reachability, WebSocket handshakes, and local managed-Chrome startup use built-in deadlines. - Repeated managed Chrome launch/readiness failures are circuit-broken per