Browser (do OpenClaw quản lý)

OpenClaw có thể chạy một profile Chrome/Brave/Edge/Chromium riêng biệt mà Agent điều khiển. Nó được tách biệt hoàn toàn với trình duyệt cá nhân của các bạn và được quản lý thông qua một dịch vụ điều khiển local nhỏ bên trong Gateway (chỉ loopback).

Góc nhìn cho người mới:

  • Hãy nghĩ về nó như một trình duyệt riêng, chỉ dành cho Agent.
  • Profile openclaw không động đến profile trình duyệt cá nhân của các bạn.
  • Agent có thể mở tab, đọc trang, click và gõ trong một môi trường an toàn.
  • Profile chrome mặc định sử dụng trình duyệt Chromium mặc định của hệ thống thông qua extension relay; chuyển sang openclaw để dùng trình duyệt quản lý tách biệt.

Các bạn nhận được gì

  • Một profile trình duyệt riêng tên là openclaw (màu cam mặc định).
  • Điều khiển tab xác định (list/open/focus/close).
  • Các thao tác của Agent (click/type/drag/select), snapshot, screenshot, PDF.
  • Hỗ trợ nhiều profile tùy chọn (openclaw, work, remote, …).

Trình duyệt này không phải là trình duyệt hàng ngày của các bạn. Nó là một môi trường an toàn, tách biệt cho việc tự động hóa và xác minh của Agent.

Bắt đầu nhanh

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

Nếu gặp lỗi “Browser disabled”, hãy bật nó trong config (xem bên dưới) và khởi động lại Gateway.

Profiles: openclaw vs chrome

  • openclaw: trình duyệt quản lý, tách biệt (không cần extension).
  • chrome: extension relay đến trình duyệt hệ thống của các bạn (cần extension OpenClaw được gắn vào tab).

Đặt browser.defaultProfile: "openclaw" nếu các bạn muốn chế độ quản lý làm mặc định.

Cấu hình

Cài đặt trình duyệt nằm trong ~/.openclaw/openclaw.json.

{
  browser: {
    enabled: true, // default: true
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Lưu ý:

  • Dịch vụ điều khiển trình duyệt bind vào loopback trên một port được tính từ gateway.port (mặc định: 18791, tức là gateway + 2). Relay dùng port tiếp theo (18792).
  • Nếu các bạn override port Gateway (gateway.port hoặc OPENCLAW_GATEWAY_PORT), các port trình duyệt sẽ tự động dịch chuyển để ở cùng “family”.
  • cdpUrl mặc định là relay port khi không được set.
  • remoteCdpTimeoutMs áp dụng cho các kiểm tra kết nối CDP từ xa (non-loopback).
  • remoteCdpHandshakeTimeoutMs áp dụng cho các kiểm tra kết nối WebSocket CDP từ xa.
  • attachOnly: true nghĩa là “không bao giờ khởi chạy trình duyệt local; chỉ attach nếu nó đang chạy sẵn.”
  • color + color theo profile sẽ tô màu UI trình duyệt để các bạn biết profile nào đang active.
  • Profile mặc định là chrome (extension relay). Dùng defaultProfile: "openclaw" cho trình duyệt quản lý.
  • Thứ tự tự động phát hiện: trình duyệt mặc định của hệ thống nếu là Chromium-based; nếu không thì Chrome → Brave → Edge → Chromium → Chrome Canary.
  • Các profile openclaw local tự động gán cdpPort/cdpUrl — chỉ set những cái này cho remote CDP.

Dùng Brave (hoặc trình duyệt Chromium-based khác)

Nếu trình duyệt mặc định của hệ thống các bạn là Chromium-based (Chrome/Brave/Edge/etc), OpenClaw sẽ tự động dùng nó. Đặt browser.executablePath để override việc tự động phát hiện:

Ví dụ CLI:

openclaw config set browser.executablePath "/usr/bin/google-chrome"
// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

Điều khiển local vs remote

  • Điều khiển local (mặc định): Gateway khởi động dịch vụ điều khiển loopback và có thể khởi chạy trình duyệt local.
  • Điều khiển remote (node host): chạy một node host trên máy có trình duyệt; Gateway proxy các thao tác trình duyệt đến nó.
  • Remote CDP: đặt browser.profiles.<name>.cdpUrl (hoặc browser.cdpUrl) để attach vào trình duyệt Chromium-based từ xa. Trong trường hợp này, OpenClaw sẽ không khởi chạy trình duyệt local.

Remote CDP URL có thể bao gồm auth:

  • Query token (ví dụ: https://provider.example?token=<token>)
  • HTTP Basic auth (ví dụ: https://user:[email protected])

OpenClaw giữ nguyên auth khi gọi các endpoint /json/* và khi kết nối đến CDP WebSocket. Nên dùng biến môi trường hoặc secrets manager cho token thay vì commit chúng vào file config.

Node browser proxy (zero-config mặc định)

Nếu các bạn chạy một node host trên máy có trình duyệt, OpenClaw có thể tự động route các lệnh gọi browser tool đến node đó mà không cần config trình duyệt thêm. Đây là đường đi mặc định cho các remote gateway.

Lưu ý:

  • Node host expose local browser control server của nó thông qua một proxy command.
  • Các profile đến từ config browser.profiles của chính node (giống như local).
  • Tắt nếu các bạn không muốn:
    • Trên node: nodeHost.browserProxy.enabled=false
    • Trên gateway: gateway.nodes.browser.mode="off"

Browserless (hosted remote CDP)

Browserless là một dịch vụ Chromium hosted expose các CDP endpoint qua HTTPS. Các bạn có thể trỏ một OpenClaw browser profile vào Browserless region endpoint và xác thực bằng API key.

Ví dụ:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

Lưu ý:

  • Thay <BROWSERLESS_API_KEY> bằng token Browserless thật của các bạn.
  • Chọn region endpoint khớp với tài khoản Browserless của các bạn (xem docs của họ).

Bảo mật

Các điểm chính:

  • Điều khiển trình duyệt chỉ loopback; truy cập đi qua auth của Gateway hoặc node pairing.
  • Giữ Gateway và bất kỳ node host nào trên mạng riêng (Tailscale); tránh expose công khai.
  • Coi remote CDP URL/token như là secret; nên dùng env var hoặc secrets manager.

Mẹo cho remote CDP:

  • Ưu tiên HTTPS endpoint và token ngắn hạn khi có thể.
  • Tránh nhúng token dài hạn trực tiếp vào file config.

Profiles (multi-browser)

OpenClaw hỗ trợ nhiều profile có tên (routing config). Các profile có thể là:

  • openclaw-managed: một instance trình duyệt Chromium-based riêng với thư mục user data riêng + CDP port riêng
  • remote: một CDP URL rõ ràng (trình duyệt Chromium-based chạy ở nơi khác)
  • extension relay: các tab Chrome hiện có của các bạn thông qua relay local + Chrome extension

Mặc định:

  • Profile openclaw được tự động tạo nếu thiếu.
  • Profile chrome được tích hợp sẵn cho Chrome extension relay (trỏ đến http://127.0.0.1:18792 mặc định).
  • Các CDP port local được phân bổ từ 18800–18899 mặc định.
  • Xóa một profile sẽ chuyển thư mục data local của nó vào Trash.

Tất cả control endpoint chấp nhận ?profile=<name>; CLI dùng --browser-profile.

Chrome extension relay (dùng Chrome hiện có của các bạn)

OpenClaw cũng có thể điều khiển các tab Chrome hiện có của các bạn (không cần instance Chrome “openclaw” riêng) thông qua một CDP relay local + một Chrome extension.

Hướng dẫn đầy đủ: Chrome extension

Luồng hoạt động:

  • Gateway chạy local (cùng máy) hoặc một node host chạy trên máy có trình duyệt.
  • Một relay server local lắng nghe tại loopback cdpUrl (mặc định: http://127.0.0.1:18792).
  • Các bạn click icon extension OpenClaw Browser Relay trên một tab để attach (nó không tự động attach).
  • Agent điều khiển tab đó thông qua tool browser bình thường, bằng cách chọn đúng profile.

Nếu Gateway chạy ở nơi khác, hãy chạy một node host trên máy có trình duyệt để Gateway có thể proxy các thao tác trình duyệt.

Session Sandbox

Nếu Agent session được sandbox, tool browser có thể mặc định là target="sandbox" (sandbox browser). Chrome extension relay takeover cần quyền điều khiển host browser, nên các bạn có thể:

  • chạy session không sandbox, hoặc
  • đặt agents.defaults.sandbox.browser.allowHostControl: true và dùng target="host" khi gọi tool.

Cài đặt

  1. Load extension (dev/unpacked):
openclaw browser extension install
  • Chrome → chrome://extensions → bật “Developer mode”
  • “Load unpacked” → chọn thư mục được in ra bởi openclaw browser extension path
  • Pin extension, sau đó click nó trên tab các bạn muốn điều khiển (badge hiển thị ON).
  1. Sử dụng:
  • CLI: openclaw browser --browser-profile chrome tabs
  • Agent tool: browser với profile="chrome"

Tùy chọn: nếu các bạn muốn tên khác hoặc relay port khác, tạo profile riêng:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

Lưu ý:

  • Chế độ này dựa vào Playwright-on-CDP cho hầu hết các thao tác (screenshot/snapshot/action).
  • Detach bằng cách click lại icon extension.

Đảm bảo tách biệt

  • Thư mục user data riêng: không bao giờ động đến profile trình duyệt cá nhân của các bạn.
  • Port riêng: tránh 9222 để không xung đột với workflow dev.
  • Điều khiển tab xác định: target tab bằng targetId, không phải “tab cuối cùng”.

Lựa chọn trình duyệt

Khi khởi chạy local, OpenClaw chọn cái đầu tiên có sẵn:

  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary

Các bạn có thể override bằng browser.executablePath.

Các nền tảng:

  • macOS: kiểm tra /Applications và ~/Applications.
  • Linux: tìm google-chrome, brave, microsoft-edge, chromium, v.v.
  • Windows: kiểm tra các vị trí cài đặt phổ biến.

Control API (tùy chọn)

Chỉ cho tích hợp local, Gateway expose một HTTP API loopback nhỏ:

  • Status/start/stop: GET /, POST /start, POST /stop
  • Tab: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
  • Snapshot/screenshot: GET /snapshot, POST /screenshot
  • Action: POST /navigate, POST /act
  • Hook: POST /hooks/file-chooser, POST /hooks/dialog
  • Download: POST /download, POST /wait/download
  • Debug: GET /console, POST /pdf
  • Debug: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
  • Network: POST /response/body
  • State: GET /cookies, POST /cookies/set, POST /cookies/clear
  • State: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
  • Setting: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

Tất cả endpoint chấp nhận ?profile=<name>.

Yêu cầu Playwright

Một số tính năng (navigate/act/AI snapshot/role snapshot, element screenshot, PDF) cần Playwright. Nếu Playwright chưa cài, các endpoint đó trả về lỗi 501 rõ ràng. ARIA snapshot và screenshot cơ bản vẫn hoạt động cho openclaw-managed Chrome. Với Chrome extension relay driver, ARIA snapshot và screenshot cần Playwright.

Nếu các bạn thấy Playwright is not available in this gateway build, hãy cài package Playwright đầy đủ (không phải playwright-core) và khởi động lại gateway, hoặc cài lại OpenClaw với hỗ trợ trình duyệt.

Cách hoạt động (internal)

Luồng tổng quan:

  • Một control server nhỏ nhận HTTP request.
  • Nó kết nối đến các trình duyệt Chromium-based (Chrome/Brave/Edge/Chromium) qua CDP.
  • Với các thao tác nâng cao (click/type/snapshot/PDF), nó dùng Playwright trên CDP.
  • Khi thiếu Playwright, chỉ các thao tác không cần Playwright mới khả dụng.

Thiết kế này giữ Agent trên một interface ổn định, xác định trong khi cho phép các bạn đổi trình duyệt local/remote và profile.

Tham chiếu nhanh CLI

Tất cả lệnh chấp nhận --browser-profile <name> để target một profile cụ thể. Tất cả lệnh cũng chấp nhận --json cho output dạng machine-readable (payload ổn định).

Cơ bản:

  • openclaw browser status
  • openclaw browser start
  • openclaw browser stop
  • openclaw browser tabs
  • openclaw browser tab
  • openclaw browser tab new
  • openclaw browser tab select 2
  • openclaw browser tab close 2
  • openclaw browser open https://example.com
  • openclaw browser focus abcd1234
  • openclaw browser close abcd1234

Kiểm tra:

  • openclaw browser screenshot
  • openclaw browser screenshot --full-page
  • openclaw browser screenshot --ref 12
  • openclaw browser screenshot --ref e12
  • openclaw browser snapshot
  • openclaw browser snapshot --format aria --limit 200
  • openclaw browser snapshot --interactive --compact --depth 6
  • openclaw browser snapshot --efficient
  • openclaw browser snapshot --labels
  • openclaw browser snapshot --selector "#main" --interactive
  • openclaw browser snapshot --frame "iframe#main" --interactive
  • openclaw browser console --level error
  • openclaw browser errors --clear
  • openclaw browser requests --filter api --clear
  • openclaw browser pdf
  • openclaw browser responsebody "**/api" --max-chars 5000

Thao tác:

  • openclaw browser navigate https://example.com
  • openclaw browser resize 1280 720
  • openclaw browser click 12 --double
  • openclaw browser click e12 --double
  • openclaw browser type 23 "hello" --submit
  • openclaw browser press Enter
  • openclaw browser hover 44
  • openclaw browser scrollintoview e12
  • openclaw browser drag 10 11
  • openclaw browser select 9 OptionA OptionB
  • openclaw browser download e12 /tmp/report.pdf
  • openclaw browser waitfordownload /tmp/report.pdf
  • openclaw browser upload /tmp/file.pdf
  • openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
  • openclaw browser dialog --accept
  • openclaw browser wait --text "Done"
  • openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
  • openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
  • openclaw browser highlight e12
  • openclaw browser trace start
  • openclaw browser trace stop

State:

  • openclaw browser cookies
  • openclaw browser cookies set session abc123 --url "https://example.com"
  • openclaw browser cookies clear
  • openclaw browser storage local get
  • openclaw browser storage local set theme dark
  • openclaw browser storage session clear
  • openclaw browser set offline on
  • openclaw browser set headers --json '{"X-Debug":"1"}'
  • openclaw browser set credentials user pass
  • openclaw browser set credentials --clear
  • openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
  • openclaw browser set geo --clear
  • openclaw browser set media dark
  • openclaw browser set timezone America/New_York
  • openclaw browser set locale en-US
  • openclaw browser set device "iPhone 14"

Lưu ý:

  • upload và dialog là các lệnh arming; chạy chúng trước khi click/press kích hoạt chooser/dialog.
  • upload cũng có thể set file input trực tiếp qua --input-ref hoặc --element.
  • snapshot:
    • --format ai (mặc định khi Playwright được cài): trả về AI snapshot với ref số (aria-ref="<n>").
    • --format aria: trả về accessibility tree (không có ref; chỉ để kiểm tra).
    • --efficient (hoặc --mode efficient): preset role snapshot compact (interactive + compact + depth + maxChars thấp hơn).
    • Config mặc định (chỉ tool/CLI): đặt browser.snapshotDefaults.mode: "efficient" để dùng efficient snapshot khi caller không truyền mode (xem Gateway configuration).
    • Các tùy chọn role snapshot (--interactive, --compact, --depth, --selector) bắt buộc role-based snapshot với ref như ref=e12.
    • --frame "<iframe selector>" giới hạn role snapshot vào một iframe (kết hợp với role ref như e12).
    • --interactive xuất ra danh sách phẳng, dễ chọn các phần tử interactive (tốt nhất cho điều khiển thao tác).
    • --labels thêm screenshot viewport-only với ref label overlay (in ra MEDIA:<path>).
  • click/type/v.v. cần một ref từ snapshot (hoặc ref số 12 hoặc role ref e12). CSS selector cố ý không được hỗ trợ cho các thao tác.

Snapshot và ref

OpenClaw hỗ trợ hai kiểu “snapshot”:

  • AI snapshot (ref số): openclaw browser snapshot (mặc định; --format ai)

    • Output: một text snapshot bao gồm ref số.
    • Thao tác: openclaw browser click 12, openclaw browser type 23 "hello".
    • Bên trong, ref được resolve qua aria-ref của Playwright.

  • Role snapshot (role ref như e12): openclaw browser snapshot --interactive (hoặc --compact, --depth, --selector, --frame)

    • Output: một danh sách/cây dựa trên role với [ref=e12] (và tùy chọn [nth=1]).
    • Thao tác: openclaw browser click e12, openclaw browser highlight e12.
    • Bên trong, ref được resolve qua getByRole(...) (cộng nth() cho các phần tử trùng).
    • Thêm --labels để có screenshot viewport với label e12 overlay.

Hành vi của ref:

  • Ref không ổn định qua các lần navigation; nếu có gì đó fail, chạy lại snapshot và dùng ref mới.
  • Nếu role snapshot được lấy với --frame, role ref được giới hạn trong iframe đó cho đến lần role snapshot tiếp theo.

Tính năng nâng cao của Wait

Các bạn có thể wait nhiều thứ hơn là chỉ time/text:

  • Wait cho URL (glob được hỗ trợ bởi Playwright):
    • openclaw browser wait --url "**/dash"
  • Wait cho load state:
    • openclaw browser wait --load networkidle
  • Wait cho một JS predicate:
    • openclaw browser wait --fn "window.ready===true"
  • Wait cho một selector hiển thị:
    • openclaw browser wait "#main"

Các điều kiện này có thể kết hợp:

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

Workflow debug

Khi một thao tác fail (ví dụ: “not visible”, “strict mode violation”, “covered”):

  1. openclaw browser snapshot --interactive
  2. Dùng click <ref> / type <ref> (ưu tiên role ref trong interactive mode)
  3. Nếu vẫn fail: openclaw browser highlight <ref> để xem Playwright đang target cái gì
  4. Nếu trang hoạt động lạ:
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. Để debug sâu: record một trace:
    • openclaw browser trace start
    • tái hiện vấn đề
    • openclaw browser trace stop (in ra TRACE:<path>)