Chrome extension (browser relay)

Chrome extension của OpenClaw cho phép agent điều khiển các tab Chrome hiện có của các bạn (cửa sổ Chrome thông thường) thay vì khởi chạy một Chrome profile riêng do openclaw quản lý.

Gắn/tháo tab thông qua một nút duy nhất trên thanh công cụ Chrome.

Khái niệm

Có ba phần:

  • Browser control service (Gateway hoặc node): API mà agent/tool gọi đến (qua Gateway)
  • Local relay server (loopback CDP): cầu nối giữa control server và extension (http://127.0.0.1:18792 mặc định)
  • Chrome MV3 extension: gắn vào tab đang hoạt động bằng chrome.debugger và chuyển tiếp các thông điệp CDP đến relay

OpenClaw sau đó điều khiển tab đã gắn thông qua tool browser bình thường (chọn đúng profile).

Cài đặt / load (unpacked)

  1. Cài extension vào đường dẫn cục bộ ổn định:
openclaw browser extension install
  1. In ra đường dẫn thư mục extension đã cài:
openclaw browser extension path
  1. Chrome → chrome://extensions
  • Bật “Developer mode”
  • “Load unpacked” → chọn thư mục được in ra ở trên
  1. Ghim extension lại.

Cập nhật (không cần build)

Extension được đóng gói sẵn trong bản phát hành OpenClaw (npm package) dưới dạng file tĩnh. Không có bước “build” riêng.

Sau khi nâng cấp OpenClaw:

  • Chạy lại openclaw browser extension install để làm mới các file đã cài trong thư mục state của OpenClaw.
  • Chrome → chrome://extensions → click “Reload” trên extension.

Sử dụng (không cần config thêm)

OpenClaw đi kèm một browser profile có sẵn tên là chrome nhắm đến extension relay trên port mặc định.

Cách dùng:

  • CLI: openclaw browser --browser-profile chrome tabs
  • Agent tool: browser với profile="chrome"

Nếu các bạn muốn tên khác hoặc port relay 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"

Gắn / tháo (nút thanh công cụ)

  • Mở tab mà các bạn muốn OpenClaw điều khiển.
  • Click vào icon extension.
    • Badge hiển thị ON khi đã gắn.
  • Click lại để tháo.

Extension điều khiển tab nào?

  • Nó không tự động điều khiển “tab nào bạn đang xem”.
  • Nó chỉ điều khiển các tab mà bạn đã gắn rõ ràng bằng cách click nút thanh công cụ.
  • Để chuyển tab: mở tab khác và click icon extension ở đó.

Badge + lỗi thường gặp

  • ON: đã gắn; OpenClaw có thể điều khiển tab đó.
  • …: đang kết nối đến local relay.
  • !: không thể kết nối relay (thường gặp nhất: browser relay server không chạy trên máy này).

Nếu thấy !:

  • Đảm bảo Gateway đang chạy cục bộ (thiết lập mặc định), hoặc chạy node host trên máy này nếu Gateway chạy ở nơi khác.
  • Mở trang Options của extension; nó sẽ hiển thị relay có thể kết nối được không.

Gateway từ xa (dùng node host)

Gateway cục bộ (cùng máy với Chrome) — thường không cần bước thêm

Nếu Gateway chạy trên cùng máy với Chrome, nó sẽ khởi động browser control service trên loopback và tự động khởi động relay server. Extension giao tiếp với local relay; các lệnh CLI/tool gọi đến Gateway.

Gateway từ xa (Gateway chạy ở nơi khác) — chạy node host

Nếu Gateway của các bạn chạy trên máy khác, hãy khởi động node host trên máy chạy Chrome. Gateway sẽ proxy các hành động browser đến node đó; extension + relay vẫn ở cục bộ với máy chạy browser.

Nếu có nhiều node kết nối, ghim một node bằng gateway.nodes.browser.node hoặc đặt gateway.nodes.browser.mode.

Sandboxing (tool containers)

Nếu agent session của các bạn được sandbox (agents.defaults.sandbox.mode != "off"), tool browser có thể bị hạn chế:

  • Mặc định, các session được sandbox thường nhắm đến sandbox browser (target="sandbox"), không phải Chrome host của bạn.
  • Chrome extension relay takeover yêu cầu điều khiển host browser control server.

Các lựa chọn:

  • Dễ nhất: dùng extension từ session/agent không được sandbox.
  • Hoặc cho phép điều khiển host browser cho các session được sandbox:
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

Sau đó đảm bảo tool không bị từ chối bởi tool policy, và (nếu cần) gọi browser với target="host".

Debug: openclaw sandbox explain

Mẹo truy cập từ xa

  • Giữ Gateway và node host trên cùng tailnet; tránh expose relay port ra LAN hoặc Internet công cộng.
  • Pair node một cách có chủ đích; tắt browser proxy routing nếu các bạn không muốn điều khiển từ xa (gateway.nodes.browser.mode="off").

Cách “extension path” hoạt động

openclaw browser extension path in ra thư mục đã cài trên đĩa chứa các file extension.

CLI cố tình không in ra đường dẫn node_modules. Luôn chạy openclaw browser extension install trước để copy extension vào vị trí ổn định trong thư mục state của OpenClaw.

Nếu các bạn di chuyển hoặc xóa thư mục cài đặt đó, Chrome sẽ đánh dấu extension là bị lỗi cho đến khi bạn reload nó từ đường dẫn hợp lệ.

Vấn đề bảo mật (đọc kỹ phần này)

Tính năng này rất mạnh và có rủi ro. Hãy coi nó như việc cho model “tay điều khiển trình duyệt của bạn”.

  • Extension sử dụng Chrome’s debugger API (chrome.debugger). Khi đã gắn, model có thể:
    • click/gõ/điều hướng trong tab đó
    • đọc nội dung trang
    • truy cập bất cứ thứ gì mà session đã đăng nhập của tab có thể truy cập
  • Điều này không được cô lập như openclaw-managed profile chuyên dụng.
    • Nếu các bạn gắn vào profile/tab hàng ngày của mình, bạn đang cấp quyền truy cập vào trạng thái tài khoản đó.

Khuyến nghị:

  • Ưu tiên dùng Chrome profile chuyên dụng (tách biệt khỏi việc duyệt web cá nhân) cho extension relay.
  • Giữ Gateway và bất kỳ node host nào chỉ trong tailnet; dựa vào Gateway auth + node pairing.
  • Tránh expose relay port qua LAN (0.0.0.0) và tránh Funnel (public).
  • Relay chặn các origin không phải extension và yêu cầu auth token nội bộ cho CDP client.

Liên quan: