docs(browser): clarify CDP startup vs navigation SSRF troubleshooting

docs/cli/browser.md

@@ -33,6 +33,20 @@ openclaw browser --browser-profile openclaw open https://example.com
 openclaw browser --browser-profile openclaw snapshot
 ```
 
+## Quick troubleshooting
+
+If `start` fails with `not reachable after start`, troubleshoot CDP readiness first. If `start` and `tabs` succeed but `open` or `navigate` fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.
+
+Minimal sequence:
+
+```bash
+openclaw browser --browser-profile openclaw start
+openclaw browser --browser-profile openclaw tabs
+openclaw browser --browser-profile openclaw open https://example.com
+```
+
+Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
+
 ## Lifecycle
 
 ```bash

docs/tools/browser.md

@@ -884,6 +884,63 @@ For Linux-specific issues (especially snap Chromium), see
 For WSL2 Gateway + Windows Chrome split-host setups, see
 [WSL2 + Windows + remote Chrome CDP troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
 
+### CDP startup failure vs navigation SSRF block
+
+These are different failure classes and they point to different code paths.
+
+- **CDP startup or readiness failure** means OpenClaw cannot confirm that the browser control plane is healthy.
+- **Navigation SSRF block** means the browser control plane is healthy, but a page navigation target is rejected by policy.
+
+Common examples:
+
+- CDP startup or readiness failure:
+  - `Chrome CDP websocket for profile "openclaw" is not reachable after start`
+  - `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
+- Navigation SSRF block:
+  - `open`, `navigate`, snapshot, or tab-opening flows fail with a browser/network policy error while `start` and `tabs` still work
+
+Use this minimal sequence to separate the two:
+
+```bash
+openclaw browser --browser-profile openclaw start
+openclaw browser --browser-profile openclaw tabs
+openclaw browser --browser-profile openclaw open https://example.com
+```
+
+How to read the results:
+
+- If `start` fails with `not reachable after start`, troubleshoot CDP readiness first.
+- If `start` succeeds but `tabs` fails, the control plane is still unhealthy. Treat this as a CDP reachability problem, not a page-navigation problem.
+- If `start` and `tabs` succeed but `open` or `navigate` fails, the browser control plane is up and the failure is in navigation policy or the target page.
+- If `start`, `tabs`, and `open` all succeed, the basic managed-browser control path is healthy.
+
+Important behavior details:
+
+- Browser config defaults to a fail-closed SSRF policy object even when you do not configure `browser.ssrfPolicy`.
+- For the local loopback `openclaw` managed profile, CDP health checks intentionally skip browser SSRF reachability enforcement for OpenClaw's own local control plane.
+- Navigation protection is separate. A successful `start` or `tabs` result does not mean a later `open` or `navigate` target is allowed.
+
+Security guidance:
+
+- Do **not** relax browser SSRF policy by default.
+- Prefer narrow host exceptions such as `hostnameAllowlist` or `allowedHostnames` over broad private-network access.
+- Use `dangerouslyAllowPrivateNetwork: true` only in intentionally trusted environments where private-network browser access is required and reviewed.
+
+Example: navigation blocked, control plane healthy
+
+- `start` succeeds
+- `tabs` succeeds
+- `open http://internal.example` fails
+
+That usually means browser startup is fine and the navigation target needs policy review.
+
+Example: startup blocked before navigation matters
+
+- `start` fails with `not reachable after start`
+- `tabs` also fails or cannot run
+
+That points to browser launch or CDP reachability, not a page URL allowlist problem.
+
 ## Agent tools + how control works
 
 The agent gets **one tool** for browser automation: