瀏覽器疑難排解（Linux）

問題：「Failed to start Chrome CDP on port 18800」

OpenClaw 的瀏覽器控制伺服器無法啟動 Chrome/Brave/Edge/Chromium，出現以下錯誤：

{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."}

根本原因

在 Ubuntu（以及許多 Linux 發行版）上，預設安裝的 Chromium 是 snap 套件。Snap 的 AppArmor 隔離機制會干擾 OpenClaw 啟動和監控瀏覽器程序的方式。

apt install chromium 安裝的其實是一個會重新導向到 snap 的空殼套件：

Note, selecting 'chromium-browser' instead of 'chromium'
chromium-browser is already the newest version (2:1snap1-0ubuntu2).

這不是真正的瀏覽器 —— 只是一個包裝器。

解法一：安裝 Google Chrome（建議）

安裝官方的 Google Chrome .deb 套件，它不受 snap 沙箱限制：

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y  # 如果有相依性錯誤

然後更新你的 OpenClaw 設定（~/.openclaw/openclaw.json）：

{
  "browser": {
    "enabled": true,
    "executablePath": "/usr/bin/google-chrome-stable",
    "headless": true,
    "noSandbox": true
  }
}

解法二：搭配 Snap Chromium 使用僅附掛模式

如果你必須使用 snap Chromium，可以將 OpenClaw 設定為附掛到手動啟動的瀏覽器：

更新設定：

{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}

手動啟動 Chromium：

chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
  about:blank &

也可以建立 systemd 使用者服務來自動啟動 Chrome：

# ~/.config/systemd/user/openclaw-browser.service
[Unit]
Description=OpenClaw Browser (Chrome CDP)
After=network.target

[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

啟用方式：systemctl --user enable --now openclaw-browser.service

驗證瀏覽器是否正常運作

檢查狀態：

curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'

測試瀏覽功能：

curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

設定參考

選項	說明	預設值
`browser.enabled`	啟用瀏覽器控制	`true`
`browser.executablePath`	Chromium 系列瀏覽器的執行檔路徑（Chrome/Brave/Edge/Chromium）	自動偵測（優先使用 Chromium 系列的預設瀏覽器）
`browser.headless`	無頭模式執行（不顯示視窗）	`false`
`browser.noSandbox`	加上 `--no-sandbox` 旗標（某些 Linux 環境需要）	`false`
`browser.attachOnly`	不啟動瀏覽器，僅附掛到既有的	`false`
`browser.cdpPort`	Chrome DevTools Protocol 連接埠	`18800`

問題：「Chrome extension relay is running, but no tab is connected」

你使用的是 chrome 設定檔（擴充功能中繼）。它需要 OpenClaw 瀏覽器擴充功能附掛到一個活躍的分頁。

修復方式：

使用受管理的瀏覽器： openclaw browser start --browser-profile openclaw （或設定 browser.defaultProfile: "openclaw"）。
使用擴充功能中繼： 安裝擴充功能，開啟一個分頁，然後點擊 OpenClaw 擴充功能圖示來附掛。

注意事項：

chrome 設定檔會盡可能使用你的系統預設 Chromium 瀏覽器。
本地 openclaw 設定檔會自動指派 cdpPort/cdpUrl；只有在遠端 CDP 的情況才需要手動設定。