解決 Linux 上的 Browser 啟動與 CDP 連線問題

在 Linux 環境跑自動化工具最煩人的就是環境相容性。你明明照著指令裝好了 Chromium，但啟動時卻一直噴報錯，這通常是因為系統預設的軟體包管理方式跟你想的不一樣，導致權限或路徑對不起來，讓瀏覽器控制權限被鎖死。

這種情況下，與其在那邊調整系統權限，不如直接換個安裝方式或調整啟動邏輯，效率會高得多。

需要準備的東西

• 運行 Linux (如 Ubuntu) 的環境
• 已安裝 OpenClaw
• 基礎命令列操作能力

快速開始

如果你在啟動時看到 Failed to start Chrome CDP on port 18800 錯誤，最推薦的做法是直接安裝官方 Google Chrome .deb 包，避開 Linux 散佈版常見的 Snap 限制。

1. 安裝官方 Google Chrome：

   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

2. 更新你的 OpenClaw 設定檔 (~/.openclaw/openclaw.json)：

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

3. 驗證狀態：

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

疑難排解

問題：Failed to start Chrome CDP on port 18800

在 Ubuntu 等發行版上，apt install chromium 實際上會安裝一個 Snap 封裝版本。Snap 的 AppArmor 限制會干擾 OpenClaw 生成與監控瀏覽器程序，導致連線失敗。

備選方案：使用 Snap Chromium 並開啟 Attach-Only 模式

如果你必須使用 Snap 版本，請讓 OpenClaw 只負責連線而不負責啟動：

1. 修改設定檔：

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

2. 手動啟動 Chromium：

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

3. （選配）建立 systemd 使用者服務來自動啟動：

   ~/.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 啟用。

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

這代表你正在使用 chrome 設定檔（擴充功能轉發模式），但 OpenClaw 找不到已連接的瀏覽器分頁。

修復方式：

• 使用託管瀏覽器：執行 openclaw browser start --browser-profile openclaw 或在設定中將 browser.defaultProfile 設為 "openclaw"。
• 手動連接擴充功能：安裝 OpenClaw 擴充功能後，開啟任一分頁並點擊擴充功能圖示進行連接。

Config Reference

選項	描述	預設值
browser.enabled	啟用瀏覽器控制	true
browser.executablePath	Chromium 系列瀏覽器路徑	自動偵測
browser.headless	無頭模式（不顯示 GUI）	false
browser.noSandbox	加入 --no-sandbox 參數	false
browser.attachOnly	不啟動瀏覽器，僅掛載至現有程序	false
browser.cdpPort	Chrome DevTools Protocol 埠號	18800

如有其他配置問題，請參考 AI Setup Assistant 獲取即時協助。

下一步

• 瀏覽器自動化進階配置
• API 參考文件