fix(browser): add missing Linux Chromium fallback paths to findChro...

[lupuletic]

Linux browser detection misses common Chromium install paths (e.g. /usr/lib/chromium/chromium) and the error message doesn't guide users to set browser.executablePath in config as a workaround

Closes #19185

Changes:

• Add additional Linux fallback paths to findChromeExecutableLinux() in src/browser/chrome.executables.ts: /usr/lib/chromium/chromium, /usr/lib/chromium-browser/chromium-browser, /opt/google/chrome/chrome, /opt/brave.com/brave/brave-browser
• Update the error message in src/browser/chrome.ts launchOpenClawChrome() to suggest setting browser.executablePath in ~/.openclaw/openclaw.json when no browser is auto-detected
• Add test coverage for the new fallback paths in existing browser detection tests

Testing:

• pnpm build && pnpm check && pnpm test
• Run existing browser detection tests (pnpm test -- src/browser/chrome.test.ts src/browser/chrome.default-browser.test.ts) and verify the new paths are checked; verify error message includes config hint

---

AI-assisted (Claude + Codex committee consensus, fully tested).

---

AI-Assisted PR Checklist

• Marked as AI-assisted
• Testing degree: fully tested (pnpm build + check + test gates passed)
• Code reviewed by LLM committee (Claude Opus + Codex dual-model review with consensus gate — equivalent to codex review)
• I understand what the code does
• Bot review conversations addressed and resolved

[greptile-apps]

Greptile Summary

This PR improves Linux browser detection by adding four commonly-missed Chromium-based executable paths to findChromeExecutableLinux(), and makes the "no browser found" error message more helpful by pointing users to the config option they can use as a workaround. The changes are narrowly scoped and well-covered by new tests.

Key changes:

• src/browser/chrome.executables.ts: adds /opt/google/chrome/chrome, /opt/brave.com/brave/brave-browser, /usr/lib/chromium/chromium, and /usr/lib/chromium-browser/chromium-browser to the Linux candidate list — all correctly grouped by browser kind.
• src/browser/chrome.ts: error message now hints at setting browser.executablePath in the OpenClaw config; CONFIG_DIR is already imported in this file and could be interpolated into the message to give users the exact file path.
• src/browser/chrome.test.ts: five new unit tests cover each added path and the null (no-browser) case using the established mockExistsSync pattern.

Confidence Score: 5/5

• Safe to merge — changes are additive path entries and a better error message with full test coverage.
• All three touched files make minimal, low-risk changes: appending paths to an array, tweaking an error string, and adding tests. No existing behaviour is altered. The one style nit (not using CONFIG_DIR in the error message) does not affect correctness or safety.
• No files require special attention.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/browser/chrome.ts
Line: 267-270

Comment:
**Error message could include the config file path**

The new hint is a great improvement, but it leaves the user guessing where "your OpenClaw config" actually lives. Since `CONFIG_DIR` is already imported in this file, you can make the message immediately actionable by embedding the actual file path:

```suggestion
    throw new Error(
      "No supported browser found (Chrome/Brave/Edge/Chromium on macOS, Linux, or Windows)." +
        ` Set \`browser.executablePath\` in ${CONFIG_DIR}/openclaw.json to the path of a Chromium-based browser.`,
    );
```

This way users on any OS see exactly which file to edit without having to hunt for it.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: dc657c1}

[aisle-research-bot]

🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

#	Severity	Title
1	🟡 Medium	Linux browser auto-discovery executes first existing path without validating file type/permissions (TOCTOU + symlink risk)

Vulnerabilities

---

1. 🟡 Linux browser auto-discovery executes first existing path without validating file type/permissions (TOCTOU + symlink risk)

Property	Value
Severity	Medium
CWE	CWE-367
Location	extensions/browser/src/browser/chrome.executables.ts:454-459

Description

findChromeExecutableLinux() was extended with additional absolute-path candidates under /opt and /usr/lib. The selection logic only checks fs.existsSync() and then later launches the returned path via spawn(exe.path, ...).

This is risky because:

• No validation of executable safety: the code does not verify the candidate is a regular file, is executable, is not a symlink, or is owned by a trusted user (e.g., root).
• TOCTOU window: there is a time gap between existence check and spawn(); a local attacker who can modify the target path (or a symlink target) could swap it after detection.
• Newly added paths like /opt/google/chrome/chrome and /opt/brave.com/brave/brave-browser increase exposure in environments where /opt may be writable (containers, misconfigurations), potentially enabling local code execution / privilege escalation when a higher-privileged process auto-launches the browser.

Vulnerable code:

function findFirstExecutable(candidates: Array<BrowserExecutable>): BrowserExecutable | null {
  for (const candidate of candidates) {
    if (exists(candidate.path)) {
      return candidate;
    }
  }
  return null;
}

Recommendation

Harden executable discovery before returning a path:

• Resolve and validate the executable at the time of use (minimize TOCTOU): prefer validating immediately before spawn().
• Require that the candidate is a regular file and executable.
• Consider rejecting or carefully handling symlinks (lstat + isSymbolicLink) and/or require the resolved realpath to be within trusted directories.
• Optionally enforce ownership/permissions checks (e.g., owned by root and not group/other-writable) when running in elevated contexts.

Example:

import fs from "node:fs";
import path from "node:path";

function isSafeExecutable(p: string): boolean {
  try {
    const st = fs.lstatSync(p);
    if (!st.isFile()) return false;
    if (st.isSymbolicLink()) return false; // or resolve+validate realpath
    fs.accessSync(p, fs.constants.X_OK);
    return true;
  } catch {
    return false;
  }
}

function findFirstExecutable(candidates: Array<BrowserExecutable>): BrowserExecutable | null {
  for (const candidate of candidates) {
    if (isSafeExecutable(candidate.path)) return candidate;
  }
  return null;
}

Additionally, when running as root/in containers, consider requiring an explicit browser.executablePath configuration rather than auto-discovery.

---

Analyzed PR: #48563 at commit fa4804d

_{Last updated on: 2026-03-29T14:16:31Z}

Latest run failed. Keeping previous successful results. Trace ID: 019d3d62daef09e210ec2c62a41bab7d.

_{Last updated on: 2026-03-30T09:47:26Z}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ce63a6ec6d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use active config path in browser-not-found hint

The new error text hardcodes ${CONFIG_DIR}/openclaw.json, but OpenClaw can load config from other locations (for example via OPENCLAW_CONFIG_PATH/profile-specific path resolution in resolveConfigPath in src/config/paths.ts). In those environments this points users to the wrong file, so they can set browser.executablePath in a file that is never read and still fail to launch a browser.

Useful? React with 👍 / 👎.

[lupuletic]

CONFIG_DIR already respects the OPENCLAW_STATE_DIR override and is the canonical config path variable used elsewhere (e.g. src/tts/tts.ts). The "active config" concern is addressed by this variable — it resolves correctly in all environments.

[steipete]

Codex deep review: this still looks valid and current-path.

What it solves: Linux managed-browser startup currently only checks /usr/bin and snap paths in extensions/browser/src/browser/chrome.executables.ts; the linked report has a real Debian/LXC-style path (/usr/lib/chromium/chromium) that main still misses. The PR adds the missing absolute install locations plus regression coverage in extensions/browser/src/browser/chrome.test.ts, and the error-message hint is useful because browser.executablePath is the documented escape hatch.

I do not think the security-bot finding should block this PR. The existing auto-detection code already returns the first existing absolute system path; this PR does not introduce PATH lookup or a new trust boundary. If we want to harden executable validation, that should be a separate browser discovery hardening change across all platforms and configured browser.executablePath, not a reason to reject these Linux candidates.

Remaining before merge: rebase/rerun. Current PR CI is stale/red across broad unrelated lanes, while the browser extension lane passed. I did not find a code blocker in this diff.

[steipete]

Codex deep review update: the fix is still useful, but the branch is too stale to merge directly.

Current main still lacks the Linux candidates this PR found:

• /opt/google/chrome/chrome
• /opt/brave.com/brave/brave-browser
• /usr/lib/chromium/chromium
• /usr/lib/chromium-browser/chromium-browser
• plus /opt/google/chrome/chrome in the Google-Chrome-only finder.

Those are worth adding with regression coverage. I still do not think the security-bot finding blocks this narrow path addition: OpenClaw already auto-detects absolute system browser paths, and executable validation hardening should be a separate cross-platform change covering all auto-discovery/configured executable paths.

But this branch is ~8.3k commits behind main; direct merge/rebase diff is noisy around chrome.ts and tests. Best path is a current-main rewrite/cherry-pick of only the executable candidates and tests. I'll preserve contributor credit if we land the maintainer rewrite.

[steipete]

Landed via maintainer rewrite on current main.

Kept the useful payload from this PR:

• Linux managed-browser discovery now checks /opt/google/chrome/chrome, /opt/brave.com/brave/brave-browser, /usr/lib/chromium/chromium, and /usr/lib/chromium-browser/chromium-browser.
• The Google-Chrome-only Linux finder now checks /opt/google/chrome/chrome.
• Added focused regression coverage in extensions/browser/src/browser/chrome.test.ts.
• Updated browser docs and changelog.

Skipped the stale chrome.ts error-message hunk because current docs/doctor already point users at browser.executablePath.

Source PR head: cbe89bb
Landed commit: 5ac36c9

Thanks @lupuletic!