diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 0aafcd4e19f..630b4ee97d3 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/docs/.generated/config-baseline.sha256 @@ -1,4 +1,4 @@ -c8d24c55df89a76f44cd6ab5fdb7c28b0b3a8adadcd2c94a1d81263512075c0f config-baseline.json -97c37380e03c167ee710adb0ee297573146e78434635780226b744841628370b config-baseline.core.json +6ed33ef102e7c92816243bfabc3626222a679c3270c12ec5ea47b28b66204b3b config-baseline.json +f86cb4d57ec1f5fd75008be0ab86151194945eb013a47ab4bdeaddafd3780da7 config-baseline.core.json 7cd9c908f066c143eab2a201efbc9640f483ab28bba92ddeca1d18cc2b528bc3 config-baseline.channel.json 7825b56a5b3fcdbe2e09ef8fe5d9f12ac3598435afebe20413051e45b0d1968e config-baseline.plugin.json diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 978e3bf75f1..9ad7da2e01b 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -283,7 +283,9 @@ See [Plugins](/tools/plugin). starts successfully but readiness checks race startup. Both values must be positive integers up to `120000` ms; invalid config values are rejected. - Auto-detect order: default browser if Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` accepts `~` for your OS home directory. +- `browser.executablePath` and `browser.profiles..executablePath` both + accept `~` and `~/...` for your OS home directory before Chromium launch. + Per-profile `userDataDir` on `existing-session` profiles is also tilde-expanded. - Control service: loopback only (port derived from `gateway.port`, default `18791`). - `extraArgs` appends extra launch flags to local Chromium startup (for example `--disable-gpu`, window sizing, or debug flags). diff --git a/docs/tools/browser.md b/docs/tools/browser.md index dfa0f3d9e74..a399e928650 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -236,12 +236,12 @@ Browser settings live in `~/.openclaw/openclaw.json`. current process. `OPENCLAW_BROWSER_HEADLESS=0` forces headed mode for ordinary starts and returns an actionable error on Linux hosts without a display server; an explicit `start --headless` request still wins for that one launch. -- `executablePath` can be set globally or per local managed profile. Per-profile values override `browser.executablePath`, so different managed profiles can launch different Chromium-based browsers. +- `executablePath` can be set globally or per local managed profile. Per-profile values override `browser.executablePath`, so different managed profiles can launch different Chromium-based browsers. Both forms accept `~` for your OS home directory. - `color` (top-level and per-profile) tints the browser UI so you can see which profile is active. - Default profile is `openclaw` (managed standalone). Use `defaultProfile: "user"` to opt into the signed-in user browser. - Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary. - `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do not set `cdpUrl` for that driver. -- Set `browser.profiles..userDataDir` when an existing-session profile should attach to a non-default Chromium user profile (Brave, Edge, etc.). +- Set `browser.profiles..userDataDir` when an existing-session profile should attach to a non-default Chromium user profile (Brave, Edge, etc.). This path also accepts `~` for your OS home directory. @@ -251,7 +251,8 @@ Browser settings live in `~/.openclaw/openclaw.json`. If your **system default** browser is Chromium-based (Chrome/Brave/Edge/etc), OpenClaw uses it automatically. Set `browser.executablePath` to override -auto-detection. `~` expands to your OS home directory: +auto-detection. Top-level and per-profile `executablePath` values accept `~` +for your OS home directory: ```bash openclaw config set browser.executablePath "/usr/bin/google-chrome" @@ -533,7 +534,8 @@ Default behavior: - The built-in `user` profile uses Chrome MCP auto-connect, which targets the default local Google Chrome profile. -Use `userDataDir` for Brave, Edge, Chromium, or a non-default Chrome profile: +Use `userDataDir` for Brave, Edge, Chromium, or a non-default Chrome profile. +`~` expands to your OS home directory: ```json5 { diff --git a/src/config/schema.base.generated.ts b/src/config/schema.base.generated.ts index 0e7cff7bbf2..51c6768e7d3 100644 --- a/src/config/schema.base.generated.ts +++ b/src/config/schema.base.generated.ts @@ -668,7 +668,7 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = { type: "string", title: "Browser Executable Path", description: - "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use absolute stable paths so launch behavior stays deterministic across restarts.", + "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use an absolute stable path, or a path starting with ~ for your OS home directory, so launch behavior stays deterministic across restarts.", }, headless: { type: "boolean", @@ -778,7 +778,7 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = { type: "string", title: "Browser Profile User Data Dir", description: - "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node.", + "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node. Paths starting with ~ expand to the OS home directory.", }, mcpCommand: { type: "string", @@ -822,6 +822,9 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = { }, executablePath: { type: "string", + title: "Browser Profile Executable Path", + description: + "Per-profile browser executable path for locally launched managed browser profiles. Overrides browser.executablePath and accepts paths starting with ~ for the OS home directory.", }, attachOnly: { type: "boolean", @@ -24071,7 +24074,7 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = { }, "browser.executablePath": { label: "Browser Executable Path", - help: "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use absolute stable paths so launch behavior stays deterministic across restarts.", + help: "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use an absolute stable path, or a path starting with ~ for your OS home directory, so launch behavior stays deterministic across restarts.", tags: ["storage"], }, "browser.headless": { @@ -24116,7 +24119,7 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = { }, "browser.profiles.*.userDataDir": { label: "Browser Profile User Data Dir", - help: "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node.", + help: "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node. Paths starting with ~ expand to the OS home directory.", tags: ["storage"], }, "browser.profiles.*.mcpCommand": { @@ -24134,6 +24137,11 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = { help: 'Per-profile browser driver mode. Use "openclaw" (or legacy "clawd") for CDP-based profiles, or use "existing-session" for Chrome DevTools MCP attachment on the selected host or browser node.', tags: ["storage"], }, + "browser.profiles.*.executablePath": { + label: "Browser Profile Executable Path", + help: "Per-profile browser executable path for locally launched managed browser profiles. Overrides browser.executablePath and accepts paths starting with ~ for the OS home directory.", + tags: ["storage"], + }, "browser.profiles.*.headless": { label: "Browser Profile Headless Mode", help: "Per-profile headless override for locally launched browser instances. Use this when one profile should stay headless without forcing browser.headless for every other profile.", diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index 61f40dd138d..444a12678b5 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -267,7 +267,7 @@ export const FIELD_HELP: Record = { "browser.color": "Default accent color used for browser profile/UI cues where colored identity hints are displayed. Use consistent colors to help operators identify active browser profile context quickly.", "browser.executablePath": - "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use absolute stable paths so launch behavior stays deterministic across restarts.", + "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use an absolute stable path, or a path starting with ~ for your OS home directory, so launch behavior stays deterministic across restarts.", "browser.headless": "Forces browser launch in headless mode when the local launcher starts browser instances. Keep headless enabled for server environments and disable only when visible UI debugging is required.", "browser.noSandbox": @@ -285,13 +285,15 @@ export const FIELD_HELP: Record = { "browser.profiles.*.cdpUrl": "Per-profile CDP websocket URL used for explicit remote browser routing by profile name. Use this when profile connections terminate on remote hosts or tunnels.", "browser.profiles.*.userDataDir": - "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node.", + "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node. Paths starting with ~ expand to the OS home directory.", "browser.profiles.*.mcpCommand": "Per-profile Chrome DevTools MCP command for existing-session attachment. Defaults to npx.", "browser.profiles.*.mcpArgs": "Extra per-profile Chrome DevTools MCP arguments for existing-session attachment, such as --no-usage-statistics. Endpoint arguments here override the built-in auto-connect or browser URL selection.", "browser.profiles.*.driver": 'Per-profile browser driver mode. Use "openclaw" (or legacy "clawd") for CDP-based profiles, or use "existing-session" for Chrome DevTools MCP attachment on the selected host or browser node.', + "browser.profiles.*.executablePath": + "Per-profile browser executable path for locally launched managed browser profiles. Overrides browser.executablePath and accepts paths starting with ~ for the OS home directory.", "browser.profiles.*.headless": "Per-profile headless override for locally launched browser instances. Use this when one profile should stay headless without forcing browser.headless for every other profile.", "browser.profiles.*.attachOnly": diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts index dd57a710349..0cf0f1d3fef 100644 --- a/src/config/schema.labels.ts +++ b/src/config/schema.labels.ts @@ -157,6 +157,7 @@ export const FIELD_LABELS: Record = { "browser.profiles.*.mcpCommand": "Browser Profile Chrome MCP Command", "browser.profiles.*.mcpArgs": "Browser Profile Chrome MCP Args", "browser.profiles.*.driver": "Browser Profile Driver", + "browser.profiles.*.executablePath": "Browser Profile Executable Path", "browser.profiles.*.headless": "Browser Profile Headless Mode", "browser.profiles.*.attachOnly": "Browser Profile Attach-only Mode", "browser.profiles.*.color": "Browser Profile Accent Color",