docs(browser): clarify JSON flag placement

soldforaloss · soldforaloss · commit 82dde7aec656 · 2026-07-10T19:59:41.000-07:00
diff --git a/docs/cli/browser.md b/docs/cli/browser.md
@@ -20,7 +20,10 @@ Related: [Browser tool](/tools/browser)
 - `--timeout <ms>`: request timeout in ms (default: `30000`).
 - `--expect-final`: wait for a final Gateway response.
 - `--browser-profile <name>`: choose a browser profile (default: `openclaw`, or `browser.defaultProfile`).
-- `--json`: machine-readable output (where supported).
+- `--json`: machine-readable output (where supported). Prefer the browser-level flag before
+  the subcommand, for example `openclaw browser --json status`; trailing placement such as
+  `openclaw browser status --json` is also supported when the selected child command does
+  not define its own `--json`.
 
 ## Quick start (local)
 
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
@@ -309,8 +309,10 @@ main model can read the screenshot directly.
   browser processes.
 - On Linux hosts without `DISPLAY` or `WAYLAND_DISPLAY`, local managed profiles
   default to headless automatically when neither the environment nor profile/global
-  config explicitly chooses headed mode. `openclaw browser status --json`
-  reports `headlessSource` as `env`, `profile`, `config`,
+  config explicitly chooses headed mode. The canonical JSON form is
+  `openclaw browser --json status`, and trailing `status --json` also works
+  because `status` does not define its own `--json`. It reports
+  `headlessSource` as `env`, `profile`, `config`,
   `request`, `linux-display-fallback`, or `default`.
 - `OPENCLAW_BROWSER_HEADLESS=1` forces local managed launches headless for the
   current process. `OPENCLAW_BROWSER_HEADLESS=0` forces headed mode for ordinary
