瀏覽器(由 openclaw 管理)
OpenClaw 可以執行一個 專用的 Chrome/Brave/Edge/Chromium 設定檔,由代理程式控制。 它與你的個人瀏覽器隔離,並透過 Gateway 閘道器 內部的一個小型本地 控制服務來管理(僅限 local loopback)。 It is isolated from your personal browser and is managed through a small local control service inside the Gateway (loopback only). 新手視角:- 把它想成一個 僅供代理程式使用的獨立瀏覽器。
openclaw設定檔不會影響你的個人瀏覽器設定檔。- The agent can open tabs, read pages, click, and type in a safe lane.
- 預設的
chrome設定檔透過 擴充功能轉送使用 系統預設的 Chromium 瀏覽器;切換至openclaw以使用隔離的受管瀏覽器。
你可以獲得什麼
- 一個名為 openclaw 的獨立瀏覽器設定檔(預設為橘色強調)。
- Deterministic tab control (list/open/focus/close).
- 代理程式動作(點擊/輸入/拖曳/選取)、快照、螢幕截圖、PDF。
- 可選的多設定檔支援(
openclaw、work、remote、…)。
快速開始
設定檔:openclaw vs chrome
openclaw:受管、隔離的瀏覽器(不需要擴充功能)。chrome:透過 系統瀏覽器 的擴充功能轉送(需要將 OpenClaw 擴充功能附加到某個分頁)。
browser.defaultProfile: "openclaw"。
設定
瀏覽器設定位於~/.openclaw/openclaw.json。
- 瀏覽器控制服務會綁定到來自
gateway.port推導出的 loopback 連接埠 (預設:18791,也就是 Gateway 閘道器 + 2)。轉送會使用下一個連接埠(18792)。 The relay uses the next port (18792). The relay uses the next port (18792). - 如果你覆寫 Gateway 閘道器 連接埠(
gateway.port或OPENCLAW_GATEWAY_PORT), 推導出的瀏覽器連接埠會一起平移以保持在同一「家族」中。 cdpUrl在未設定時預設為轉送連接埠。remoteCdpTimeoutMs套用於遠端(非 loopback)的 CDP 可達性檢查。remoteCdpHandshakeTimeoutMs套用於遠端 CDP WebSocket 可達性檢查。attachOnly: true表示「永不啟動本地瀏覽器;僅在其已執行時才附加」。color+ per-profilecolortint the browser UI so you can see which profile is active.- Default profile is
chrome(extension relay). UsedefaultProfile: "openclaw"for the managed browser. - 自動偵測順序:若系統預設瀏覽器為 Chromium 系列則優先;否則 Chrome → Brave → Edge → Chromium → Chrome Canary。
- 本地
openclaw設定檔會自動指派cdpPort/cdpUrl—— 僅在遠端 CDP 時才需要設定這些。
使用 Brave(或其他 Chromium 系列瀏覽器)
如果你的 系統預設 瀏覽器是 Chromium 系列(Chrome/Brave/Edge 等), OpenClaw 會自動使用它。設定browser.executablePath 以覆寫
自動偵測: Set browser.executablePath to override
auto-detection: Set browser.executablePath to override
auto-detection:
CLI 範例:
本地與遠端控制
- 本地控制(預設): Gateway 閘道器 會啟動 loopback 控制服務並可啟動本地瀏覽器。
- 遠端控制(節點主機): 在有瀏覽器的機器上執行節點主機;Gateway 閘道器 會將瀏覽器動作代理到該主機。
- 遠端 CDP: 設定
browser.profiles.<name>.cdpUrl(或browser.cdpUrl)以 附加到遠端的 Chromium 系列瀏覽器。在此情況下,OpenClaw 不會啟動本地瀏覽器。 .cdpUrl(或browser.cdpUrl`)以 附加到遠端的 Chromium 系列瀏覽器。在此情況下,OpenClaw 不會啟動本地瀏覽器。 In this case, OpenClaw will not launch a local browser.
- 查詢權杖(例如
https://provider.example?token=<token>) - HTTP Basic auth(例如
https://user:[email protected])
/json/* 端點以及連線到
CDP WebSocket 時會保留這些驗證資訊。請優先使用環境變數或秘密管理器來保存
權杖,而不是將其提交到設定檔。 Prefer environment variables or secrets managers for
tokens instead of committing them to config files.
Node 瀏覽器代理(零設定預設)
如果你在擁有瀏覽器的機器上執行 node host,OpenClaw 可以 自動將瀏覽器工具呼叫路由到該節點,而無需任何額外的瀏覽器設定。 這是遠端 Gateway 閘道器 的預設路徑。 This is the default path for remote gateways. This is the default path for remote gateways. 注意事項:- node host 會透過 代理指令 暴露其本地瀏覽器控制伺服器。
- 設定檔來自該節點自身的
browser.profiles設定(與本地相同)。 - 若你不想要此功能,可停用:
- 在節點上:
nodeHost.browserProxy.enabled=false - 在 Gateway 閘道器 上:
gateway.nodes.browser.mode="off"
- 在節點上:
Browserless(託管的遠端 CDP)
Browserless 是一個託管的 Chromium 服務,透過 HTTPS 暴露 CDP 端點。你可以將 OpenClaw 的瀏覽器設定檔指向 Browserless 的區域端點,並使用你的 API 金鑰進行驗證。 You can point a OpenClaw browser profile at a Browserless region endpoint and authenticate with your API key. You can point a OpenClaw browser profile at a Browserless region endpoint and authenticate with your API key. 範例:- 將
<BROWSERLESS_API_KEY>替換為你實際的 Browserless 權杖。 - Choose the region endpoint that matches your Browserless account (see their docs).
安全性
核心概念:- Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
- 若已啟用瀏覽器控制且未設定任何驗證,OpenClaw 會在啟動時自動產生
gateway.auth.token並將其保存至設定檔。 - 將 Gateway 閘道器 與任何 node host 保持在私有網路(Tailscale)中;避免公開暴露。
- Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.
- Prefer HTTPS endpoints and short-lived tokens where possible.
- 避免直接在設定檔中嵌入長期有效的權杖。
Profiles (multi-browser)
OpenClaw supports multiple named profiles (routing configs). Profiles can be:- openclaw-managed:具有自身使用者資料目錄與 CDP 連接埠的專用 Chromium 系列瀏覽器實例
- remote:明確的 CDP URL(在其他地方執行的 Chromium 系列瀏覽器)
- extension relay:透過本地轉送 + Chrome 擴充功能控制你現有的 Chrome 分頁
- The
openclawprofile is auto-created if missing. - The
chromeprofile is built-in for the Chrome extension relay (points athttp://127.0.0.1:18792by default). - 本地 CDP 連接埠預設配置自 18800–18899。
- Deleting a profile moves its local data directory to Trash.
?profile=<name>;CLI 使用 --browser-profile。
Chrome 擴充功能轉送(使用你現有的 Chrome)
OpenClaw 也可以透過本地 CDP 轉送 + Chrome 擴充功能 驅動 你現有的 Chrome 分頁(不會啟動獨立的「openclaw」Chrome 實例)。 完整指南:Chrome extension 流程:- Gateway 閘道器 在本地執行(同一台機器),或在瀏覽器機器上執行 node host。
- 本地 轉送伺服器 會在 loopback 的
cdpUrl(預設:http://127.0.0.1:18792)監聽。 - You click the OpenClaw Browser Relay extension icon on a tab to attach (it does not auto-attach).
- The agent controls that tab via the normal
browsertool, by selecting the right profile.
Sandboxed sessions
If the agent session is sandboxed, thebrowser tool may default to target="sandbox" (sandbox browser).
Chrome extension relay takeover requires host browser control, so either:
- run the session unsandboxed, or
- 設定
agents.defaults.sandbox.browser.allowHostControl: true,並在呼叫工具時使用target="host"。
設定
- 載入擴充功能(dev/unpacked):
- Chrome →
chrome://extensions→ 啟用「Developer mode」 - 「Load unpacked」→ 選取
openclaw browser extension path輸出的目錄 - Pin the extension, then click it on the tab you want to control (badge shows
ON).
- 使用方式:
- CLI:
openclaw browser --browser-profile chrome tabs - 代理程式工具:
browser搭配profile="chrome"
- 此模式在多數操作(螢幕截圖/快照/動作)上依賴 Playwright-on-CDP。
- Detach by clicking the extension icon again.
隔離保證
- Dedicated user data dir: never touches your personal browser profile.
- 專用連接埠:避免
9222,以防與開發流程發生衝突。 - 可預期的分頁控制:以
targetId為目標,而不是「最後一個分頁」。
瀏覽器選擇
在本地啟動時,OpenClaw 會選擇第一個可用的:- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
browser.executablePath 覆寫。
平台:
- macOS:檢查
/Applications與~/Applications。 - Linux:尋找
google-chrome、brave、microsoft-edge、chromium等。 - Windows:檢查常見的安裝位置。
控制 API(選用)
僅供本地整合,Gateway 閘道器 會暴露一個小型的 loopback HTTP API:- 狀態/啟動/停止:
GET /、POST /start、POST /stop - 分頁:
GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId - 快照/螢幕截圖:
GET /snapshot、POST /screenshot - 動作:
POST /navigate、POST /act - Hooks:
POST /hooks/file-chooser、POST /hooks/dialog - 下載:
POST /download、POST /wait/download - 偵錯:
GET /console、POST /pdf - 偵錯:
GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight - 網路:
POST /response/body - 狀態:
GET /cookies、POST /cookies/set、POST /cookies/clear - 狀態:
GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear - 設定:
POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device
?profile=<name>。
若已設定 gateway 驗證,瀏覽器的 HTTP 路由也需要驗證:
Authorization: Bearer <gateway token>- OpenClaw 在呼叫
/json/*端點以及連線到 CDP WebSocket 時會保留這些驗證資訊。請優先使用環境變數或秘密管理器來保存 權杖,而不是將其提交到設定檔。 Prefer environment variables or secrets managers for tokens instead of committing them to config files.
Playwright 需求
Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require Playwright. If Playwright isn’t installed, those endpoints return a clear 501 error. ARIA snapshots and basic screenshots still work for openclaw-managed Chrome. For the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright. 如果你看到Playwright is not available in this gateway build,請安裝完整的
Playwright 套件(不是 playwright-core)並重新啟動 gateway,
或重新安裝包含瀏覽器支援的 OpenClaw。
Docker 中安裝 Playwright
如果你的 Gateway 閘道器 在 Docker 中執行,請避免npx playwright(npm 覆寫衝突)。
請改用隨附的 CLI:
Use the bundled CLI instead:
Use the bundled CLI instead:
PLAYWRIGHT_BROWSERS_PATH(例如
/home/node/.cache/ms-playwright),並確保 /home/node 透過
OPENCLAW_HOME_VOLUME 或 bind mount 被保留。請參閱 Docker。 See Docker.
How it works (internal)
高層流程:- 一個小型 控制伺服器 接受 HTTP 請求。
- 它透過 CDP 連線到 Chromium 系列瀏覽器(Chrome/Brave/Edge/Chromium)。
- 對於進階動作(點擊/輸入/快照/PDF),它在 CDP 之上使用 Playwright。
- 當缺少 Playwright 時,只能使用非 Playwright 的操作。
CLI 快速參考
All commands accept--browser-profile <name> to target a specific profile.
All commands also accept --json for machine-readable output (stable payloads).
基礎:
openclaw browser statusopenclaw browser startopenclaw browser stopopenclaw browser tabsopenclaw browser tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234
openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12openclaw browser screenshot --ref e12openclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000
openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --doubleopenclaw browser click e12 --doubleopenclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 /tmp/report.pdfopenclaw browser waitfordownload /tmp/report.pdfopenclaw browser upload /tmp/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw browser highlight e12openclaw browser trace startopenclaw browser trace stop
openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --json '{"X-Debug":"1"}'openclaw browser set credentials user passopenclaw browser set credentials --clearopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set geo --clearopenclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"
upload與dialog是 預備 呼叫;請在觸發選擇器/對話框的點擊或按鍵前執行。- 下載與追蹤輸出路徑會限制在 OpenClaw 的暫存根目錄內:
- OpenClaw 可以執行一個 專用的 Chrome/Brave/Edge/Chromium 設定檔,由代理程式控制。 它與你的個人瀏覽器隔離,並透過 Gateway 閘道器 內部的一個小型本地 控制服務來管理(僅限 local loopback)。 It is isolated from your personal browser and is managed through a small local control service inside the Gateway (loopback only).
- downloads:
/tmp/openclaw/downloads(備援:${os.tmpdir()}/openclaw/downloads)
- 上傳路徑會限制在 OpenClaw 的暫存 uploads 根目錄內:
- 預設設定檔為
chrome(extension relay)。若要使用受管瀏覽器,請設定defaultProfile: "openclaw"。
- 預設設定檔為
upload也可以透過--input-ref或--element直接設定檔案輸入。snapshot:--format ai(安裝 Playwright 時的預設):回傳帶有數字參照的 AI 快照(aria-ref="<n>")。--format aria:回傳可及性樹(無參照;僅供檢視)。--efficient(或--mode efficient):精簡的角色快照預設(互動式 + 精簡 + 深度 + 較低的 maxChars)。- 設定預設(僅工具/CLI):設定
browser.snapshotDefaults.mode: "efficient",當呼叫端未指定模式時使用高效率快照(見 Gateway 設定)。 - 角色快照選項(
--interactive、--compact、--depth、--selector)會強制使用角色式快照,並產生如ref=e12的參照。 --frame "<iframe selector>"會將角色快照限定於某個 iframe(搭配如e12的角色參照)。--interactive會輸出扁平、易於挑選的互動元素清單(最適合驅動動作)。--labels會加入僅限視窗的螢幕截圖,並疊加參照標籤(輸出MEDIA:<path>)。
click/type/等需要一個來自snapshot的ref(可以是數字12或角色參照e12)。 動作刻意不支援 CSS 選擇器。click/type/等需要一個來自snapshot的ref(可以是數字12或角色參照e12)。 動作刻意不支援 CSS 選擇器。 CSS selectors are intentionally not supported for actions.
Snapshots and refs
OpenClaw 支援兩種「快照」樣式:-
AI 快照(數字參照):
openclaw browser snapshot(預設;--format ai)- Output: a text snapshot that includes numeric refs.
- 動作:
openclaw browser click 12、openclaw browser type 23 "hello"。 - Internally, the ref is resolved via Playwright’s
aria-ref.
-
角色快照(角色參照如
e12):openclaw browser snapshot --interactive(或--compact、--depth、--selector、--frame)- Output: a role-based list/tree with
[ref=e12](and optional[nth=1]). - 動作:
openclaw browser click e12、openclaw browser highlight e12。 - 內部透過
getByRole(...)(以及重複項目的nth())解析參照。 - 加上
--labels以包含帶有疊加e12標籤的視窗螢幕截圖。
- Output: a role-based list/tree with
- Refs are not stable across navigations; if something fails, re-run
snapshotand use a fresh ref. - 如果角色快照是以
--frame取得,角色參照會限定於該 iframe,直到下一次角色快照為止。
等待強化功能
你不只能等待時間/文字:- 等待 URL(Playwright 支援 glob):
openclaw browser wait --url "**/dash"
- 等待載入狀態:
openclaw browser wait --load networkidle
- 等待 JS 條件:
openclaw browser wait --fn "window.ready===true"
- 等待選擇器顯示:
openclaw browser wait "#main"
Debug workflows
當動作失敗時(例如「不可見」、「嚴格模式違規」、「被遮擋」):openclaw browser snapshot --interactive- 使用
click <ref>/type <ref>(在互動模式下優先使用角色參照) - 若仍失敗:
openclaw browser highlight <ref>以查看 Playwright 的目標 - 若頁面行為異常:
openclaw browser errors --clearopenclaw browser requests --filter api --clear
- For deep debugging: record a trace:
openclaw browser trace start- 重現問題
openclaw browser trace stop(輸出TRACE:<path>)
JSON 輸出
--json is for scripting and structured tooling.
範例:
refs,以及一小段 stats 區塊(行數/字元數/參照/互動性),以便工具評估負載大小與密度。
State and environment knobs
這些對於「讓網站表現得像 X」的工作流程很有用:- Cookies:
cookies、cookies set、cookies clear - 儲存空間:
storage local|session get|set|clear - 離線:
set offline on|off - 標頭:
set headers --json '{"X-Debug":"1"}'(或--clear) - HTTP basic auth:
set credentials user pass(或--clear) - 地理位置:
set geo <lat> <lon> --origin "https://example.com"(或--clear) - 媒體:
set media dark|light|no-preference|none - 時區/語系:
set timezone ...、set locale ... - 裝置/視窗:
set device "iPhone 14"(Playwright 裝置預設)set viewport 1280 720
安全性與隱私
- The openclaw browser profile may contain logged-in sessions; treat it as sensitive.
browser act kind=evaluate/openclaw browser evaluate與wait --fn會在頁面情境中執行任意 JavaScript。提示注入可能引導此行為。 若不需要,請使用browser.evaluateEnabled=false停用。 Prompt injection can steer this. Prompt injection can steer this. Disable it withbrowser.evaluateEnabled=falseif you do not need it.- 登入與反機器人注意事項(X/Twitter 等),請參閱 Browser login + X/Twitter posting。
- 保持 Gateway 閘道器/node host 為私有(僅 loopback 或 tailnet)。
- 遠端 CDP 端點權力強大;請進行通道化並妥善保護。
Troubleshooting
Linux 特定問題(尤其是 snap Chromium),請參閱 Browser troubleshooting。代理程式工具 + 控制方式
代理程式只有 一個工具 用於瀏覽器自動化:browser— 狀態/啟動/停止/分頁/開啟/聚焦/關閉/快照/螢幕截圖/導覽/動作
browser snapshot回傳穩定的 UI 樹(AI 或 ARIA)。browser act使用快照的refID 來點擊/輸入/拖曳/選取。browser screenshot擷取像素(全頁或元素)。browser接受:profile以選擇具名瀏覽器設定檔(openclaw、chrome 或遠端 CDP)。target(sandbox|host|node)以選擇瀏覽器所在位置。- 在沙箱化工作階段中,
target: "host"需要agents.defaults.sandbox.browser.allowHostControl=true。 - 若省略
target:沙箱化工作階段預設為sandbox,非沙箱化工作階段預設為host。 - 若連線了具備瀏覽器能力的節點,工具可能會自動路由到該節點,除非你固定
target="host"或target="node"。