Dùng Chrome Relay để cho phép tác nhân lập trình điều khiển Chrome đã đăng nhập

Chrome Relay là gì?

Chrome Relay cho phép các tác nhân lập trình được hỗ trợ sử dụng các hồ sơ Google Chrome hằng ngày của bạn từ dòng lệnh. Tác nhân có thể truy cập các trang web nơi bạn đã đăng nhập trong khi làm việc qua các thẻ nền không hoạt động, để quá trình tự động hóa không chiếm quyền điều khiển cửa sổ hiện tại của bạn.

Dự án này hoạt động với Claude Code, Codex, Cursor và Paseo. Dự án kết nối các lệnh trình duyệt của chúng với Chrome thông qua agent-browser. Các lệnh thường hoàn tất trong khoảng 0.15 giây và Chrome không cần cổng gỡ lỗi từ xa.

Chrome Relay hoạt động theo cơ chế bật tùy chọn. Tiện ích này không tự động cài đặt extension và chỉ chạy trên các máy Mac đã được chủ sở hữu hoàn tất thiết lập.

Chrome Relay hoạt động như thế nào

agent-browser CLI → local relay → Chrome Relay extension → agent tab

Hệ thống có ba thành phần chính:

• Tiện ích Chrome: Một extension Manifest V3 chưa đóng gói, được tải riêng vào từng hồ sơ Chrome mà bạn muốn tác nhân sử dụng. Extension mở các thẻ của tác nhân trong một nhóm thẻ Agents không hoạt động và được thu gọn, đồng thời gửi các lệnh DevTools thông qua chrome.debugger.
• Relay cục bộ: Một LaunchAgent lắng nghe tại 127.0.0.1:9333. Relay cung cấp cho mỗi tác nhân một endpoint DevTools riêng và giới hạn tác nhân chỉ được sử dụng các thẻ do chính nó mở.
• Công cụ dòng lệnh: Lệnh chrome-relay xử lý việc thiết lập, URL kết nối, danh tính, cập nhật, chẩn đoán, nhật ký và bản ghi kiểm tra.

Relay chặn các lệnh có thể đưa Chrome lên trước hoặc đặt Chrome vào trạng thái được lấy nét. Chrome vẫn có thể hiển thị thông báo Chrome Relay started debugging this browser trong khi tác nhân làm việc.

Yêu cầu

Trước khi cài đặt, hãy đảm bảo bạn có:

• macOS
• Google Chrome
• Node.js 20 trở lên
• agent-browser được cài đặt toàn cục

Cài đặt agent-browser bằng npm:

npm i -g agent-browser

Cài đặt Chrome Relay

1. Sao chép và cấu hình dự án

git clone https://github.com/aindeev/agent-chrome-relay
cd agent-chrome-relay
bin/chrome-relay setup

Lệnh thiết lập tạo khóa bí mật cục bộ, cấu hình dịch vụ nền, ghi lại danh tính, đưa chrome-relay vào PATH và liên kết kỹ năng Chrome Relay cho Claude Code.

2. Tải extension vào Chrome

Thực hiện các bước sau trong mọi hồ sơ Chrome mà bạn muốn tác nhân có thể sử dụng:

1. Mở chrome://extensions.
2. Bật Chế độ dành cho nhà phát triển.
3. Chọn Tải tiện ích chưa đóng gói.
4. Chọn thư mục extension của kho mã.

Vì mỗi hồ sơ Chrome tải bản sao extension riêng, bạn chỉ có thể cung cấp các hồ sơ mà mình chủ động chọn.

3. Xác minh cài đặt

chrome-relay doctor

Sử dụng kết quả chẩn đoán để xác nhận relay và extension đã được cấu hình chính xác trước khi yêu cầu tác nhân duyệt web.

Thông báo cho tác nhân lập trình về Chrome Relay

Claude Code

Quy trình thiết lập liên kết skill/SKILL.md vào ~/.claude/skills/chrome-relay. Nhờ đó, kỹ năng này khả dụng trên mọi kho mã. CLAUDE.md ở cấp kho mã chỉ cần một dòng trỏ đến kỹ năng đó khi cần thêm chỉ dẫn cụ thể.

Codex, Cursor và các tác nhân được hỗ trợ khác

Trỏ hướng dẫn toàn cục của tác nhân đến cùng tệp kỹ năng. Ví dụ, thêm một chỉ dẫn như sau vào ~/.codex/AGENTS.md:

For any browser step that needs my logins, follow /path/to/agent-chrome-relay/skill/SKILL.md.

Thay đường dẫn ví dụ bằng đường dẫn tuyệt đối đến kho mã bạn đã sao chép.

Chạy quy trình tự động hóa trình duyệt đầu tiên

Trước tiên, yêu cầu Chrome Relay cung cấp URL kết nối đã xác thực, sau đó truyền URL này cho agent-browser:

agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/
agent-browser snapshot -i
agent-browser click @e5
agent-browser close

Thay you@company.com bằng danh tính đã cấu hình phù hợp và thay trang web ví dụ bằng trang bạn muốn tự động hóa.

1. chrome-relay url in ra URL kết nối chứa khóa bí mật của máy Mac này.
2. agent-browser open tạo một thẻ không hoạt động do tác nhân sở hữu và mở trang được yêu cầu.
3. snapshot -i liệt kê các điều khiển tương tác như liên kết, nút và trường nhập. Mỗi phần tử nhận một tham chiếu như @e5.
4. click @e5 kích hoạt phần tử được tham chiếu bằng mô phỏng thao tác nhập thực trong thẻ nền.
5. close kết thúc phiên trình duyệt.

Hiểu về cách đăng nhập

Tác nhân không nhập thông tin đăng nhập của bạn. Nếu một trang web chuyển hướng qua Google và tài khoản chính xác đã đăng nhập, extension có thể chọn tài khoản đó rồi nhấp vào Tiếp tục hoặc Cho phép. Cách này sử dụng tập lệnh trang và có thể hoạt động ngay cả khi 1Password đã đặt một khung trên trang.

Nếu quy trình đi đến màn hình yêu cầu mật khẩu, passkey, xác minh hai bước hoặc tài khoản đã đăng xuất, quá trình tự động hóa sẽ dừng. Tác nhân nhận được thông báo SIGN-IN NEEDED và cần yêu cầu bạn hoàn tất đăng nhập trong cửa sổ của mình.

Quản lý danh tính hồ sơ và trang web

Cấu hình danh tính được lưu trong ~/.chrome-relay/identities.json. Xem hoặc quản lý cấu hình bằng:

chrome-relay identities

Cấu hình bao gồm các hồ sơ Chrome được phát hiện trong quá trình thiết lập, các sites.rules được cấu hình thủ công (nếu có), và các mục sites.learned được ghi nhận sau những lần chuyển tiếp đăng nhập thành công. Theo mặc định, một trang web sử dụng tài khoản thuộc hồ sơ Chrome đã chọn.

Mô hình bảo mật

Mọi kết nối của tác nhân đều phải vượt qua hai bước kiểm tra:

1. Bí mật cục bộ: Quá trình thiết lập tạo một token tại ~/.chrome-relay/token với quyền tệp 600. Token được nhúng trong các URL do chrome-relay url in ra.
2. Ứng dụng tác nhân được cho phép: Tiến trình kết nối phải được liên kết với Claude Code, Codex, Cursor hoặc Paseo. Relay kiểm tra các tiến trình và các dấu hiệu mà những ứng dụng này thiết lập trong các tiến trình con.

Các kết nối có tiêu đề Origin của trình duyệt sẽ bị từ chối ngay cả khi có bí mật. Tiện ích cũng được kiểm tra bằng ID tiện ích bắt nguồn từ Chrome, origin chrome-extension:// và yêu cầu tiến trình kết nối phải là Chrome.

Những cơ chế kiểm soát này ngăn các công cụ cục bộ không liên quan, trang web và kết nối ngoài ý muốn truy cập. Chúng không phải là ranh giới bảo mật chống lại phần mềm độc hại đã chạy dưới tài khoản người dùng của bạn, vì phần mềm đó có thể đọc bí mật và giả mạo các dấu hiệu tiến trình.

Xem nhật ký kiểm tra

Chrome Relay ghi lại hoạt động của tác nhân trong các tệp JSON Lines hằng ngày tại ~/.chrome-relay/audit/YYYY-MM-DD.jsonl. Đọc các bản ghi bằng:

chrome-relay audit

Nhật ký kiểm tra bao gồm thông tin kết nối, thư mục làm việc, mã định danh phiên, các trang đã truy cập, vị trí nhấp chuột, phím đặc biệt, tập lệnh tác nhân, ảnh chụp màn hình, tệp tải lên, cửa sổ bật lên, thao tác nhấp đăng nhập và các trang bị chặn. Để bảo vệ quyền riêng tư, văn bản đã nhập chỉ được biểu thị bằng số lượng ký tự, còn chuỗi truy vấn URL sẽ bị loại bỏ.

Hành vi nâng cao và mẹo

Cửa sổ bật lên và tab mới

Các liên kết sử dụng target=_blank và cửa sổ bật lên sẽ mở dưới dạng các tab ẩn do cùng một tác nhân sở hữu. Quy trình xác thực qua cửa sổ bật lên vẫn có thể gửi thông báo về cửa sổ mở nó và tự đóng. Relay thực thi các origin thông báo được quan sát và targetOrigin thay vì tin vào tuyên bố của trang.

Các trang 1Password

Chrome có thể ngắt trình gỡ lỗi tiện ích khi một trang chứa khung của tiện ích khác, chẳng hạn menu 1Password trên biểu mẫu đăng nhập. Chrome Relay sẽ chờ và kết nối lại trước khi tiếp tục các lệnh của tác nhân.

Dọn dẹp tự động

Các tab của tác nhân sẽ đóng sau 30 phút không hoạt động. Khi relay khởi động lại, tiện ích cũng đóng các tab mà trước đó nó đã mở. Việc dọn dẹp dựa trên ID tab, nên không thay đổi các nhóm tab của bạn.

Nhập liệu nền

Mô phỏng tiêu điểm vẫn được bật trong các tab của tác nhân. Điều này cho phép thao tác nhấp và nhập liệu đến các tab không hoạt động trong khi tab Chrome hiện tại của bạn vẫn giữ nguyên.

Cập nhật, chẩn đoán và gỡ Chrome Relay

Sau khi kéo các thay đổi từ kho mã, hãy khởi động lại relay và tải lại tiện ích trong mọi hồ sơ đã cấu hình:

git pull
chrome-relay update

Xem nhật ký relay bằng:

chrome-relay logs

Tệp nhật ký được lưu tại ~/.chrome-relay/relay.log. Để gỡ dịch vụ cục bộ và thiết lập dòng lệnh, hãy chạy:

chrome-relay uninstall

Sau đó, hãy tự xóa tiện ích chưa đóng gói khỏi từng hồ sơ Chrome.

Phát triển và kiểm thử

Để cài đặt các phần phụ thuộc của relay và chạy bộ kiểm thử:

cd relay && npm install && npm test

Các bài kiểm thử bao quát việc ủy quyền kết nối, bao gồm bí mật, các ứng dụng được cho phép, kết nối tiện ích chỉ dành cho Chrome và hoạt động kiểm tra nhật ký. Sau khi chỉnh sửa các tệp trong extension/, hãy tải lại tiện ích bằng:

chrome-relay update

Trong các môi trường tùy chỉnh, CHROME_RELAY_HOME ghi đè thư mục dữ liệu và CHROME_RELAY_PORT ghi đè cổng relay.

Kết luận

Chrome Relay cung cấp cho các tác nhân lập trình được hỗ trợ quyền truy cập có kiểm soát vào các phiên Chrome hiện có mà không cần cổng gỡ lỗi từ xa hoặc chiếm quyền cửa sổ đang hoạt động của bạn. Sau khi relay cục bộ và tiện ích chưa đóng gói được cấu hình, bạn có thể tự động hóa các tác vụ trình duyệt đã xác thực bằng agent-browser, chọn danh tính theo hồ sơ hoặc trang web, kiểm tra các bản ghi chi tiết có cân nhắc quyền riêng tư và dựa vào tính năng dọn dẹp tự động cho các phiên bị bỏ lại.

Để xem mã nguồn, các bản cập nhật và báo cáo vấn đề, hãy truy cập kho lưu trữ Chrome Relay trên GitHub. Dự án được cung cấp theo Giấy phép MIT.