Spec ADE
English
Về trang chủ

Cài đặt Browzy

Viết cho người chưa từng dùng terminal. Từng lệnh một, và những gì bạn sẽ thấy sau mỗi bước.

Hai nửa, và chúng phải khớp nhau

Browzy gồm hai phần: một browser extension và một tiến trình companion (native host). Extension không tự làm được gì — nó nói chuyện với companion qua cơ chế native messaging của Chrome, và Chrome đòi companion phải được đăng ký sẵn trên đĩa trước khi kết nối. Đó là lý do luôn có một bước cài ngoài trình duyệt — chỉ "Load unpacked" không bao giờ là đủ.

Nửa Là gì Chạy ở đâu
Extension Giao diện và phần điều khiển trình duyệt Trong Chrome, Edge hoặc Brave
Companion (native host) Bộ não agent — chạy Claude Agent SDK Tiến trình Node trên máy bạn

Chuẩn bị trước

Node.js Bản LTS. Companion chạy trên Node — không có Node thì không cài được. Git Để lấy mã nguồn. Một trình duyệt nhân Chromium Chrome, Edge hoặc Brave. API key Của một nhà cung cấp tương thích Anthropic — ví dụ Anthropic Console chính thức. Browzy không kèm sẵn key nào và không có máy chủ trung gian.

Cài đặt

  1. 1. Lấy mã nguồn

    Mở terminal (Git Bash trên Windows, Terminal trên macOS/Linux) và chạy:

    git clone https://github.com/Nguy-n-Th-Huy/Browzy.git
cd Browzy
    Kết quả mong đợi

    Bạn sẽ thấy một thư mục Browzy mới xuất hiện, và dấu nhắc terminal giờ cho thấy bạn đang ở trong đó.

  2. 2. Cài companion

    Chọn một dòng theo hệ điều hành. Lệnh này tự làm ba việc: cài dependency, suy ra extension ID từ khoá công khai trong manifest, rồi ghi đăng ký native host cho từng trình duyệt tìm thấy. Dòng Windows có tiền tố -ExecutionPolicy Bypass là có chủ đích: PowerShell mặc định từ chối mọi file .ps1 chưa ký, kể cả file nằm sẵn trên máy bạn, nên gõ thẳng .\install.ps1 sẽ lỗi trên máy mới cài. Tiền tố đó chỉ áp dụng cho đúng lần chạy này và không đổi gì trên hệ thống.

    macOS / Linux / Git Bash 
    ./install.sh
    Windows PowerShell 
    powershell -ExecutionPolicy Bypass -File .\install.ps1
    Kết quả mong đợi

    Script in ra "Done! Next steps" kèm lời nhắc khởi động lại trình duyệt. Chạy lại sau này vô hại — không có gì thay đổi thì nó in "Already up to date" và không ghi gì.

  3. 3. Nạp extension

    Mở chrome://extensions (hoặc edge://extensions, brave://extensions), bật Developer mode ở góc trên bên phải, bấm Load unpacked, rồi chọn thư mục extension/ bên trong repo vừa clone.

    Kết quả mong đợi

    Thẻ Browzy xuất hiện với id ihljfjgoakmoemkdondoaadegpmibimh — cùng một id trên mọi máy và mọi lần nạp lại, vì extension mang sẵn một khoá manifest cố định. Không có id nào cần copy cả.

    Thẻ Browzy trong chrome://extensions, đang bật, hiển thị extension id
    Mục Browzy trong chrome://extensions — đang bật, với id cố định ihljfjgoakmoemkdondoaadegpmibimh mà mọi máy đều nhận.

  4. 4. Khởi động lại trình duyệt

    Đóng tất cả cửa sổ rồi mở lại trình duyệt hoàn toàn. Trình duyệt đọc cấu hình native-messaging host khi khởi động, nên bước này không thể bỏ qua.

    Kết quả mong đợi

    Trình duyệt khởi động lại; chưa có gì khác cần kiểm tra.

  5. 5. Nhập API key

    Mở panel Browzy (bấm biểu tượng trên thanh công cụ) rồi mở Settings — biểu tượng bánh răng, hoặc chuột phải vào icon extension và chọn Options. Nhập Base URL, API key, và ít nhất một Model ID, rồi bấm Test connection.

    Kết quả mong đợi

    Test connection gửi một request nhỏ, có tính phí, tới điểm cuối của bạn. Khi nó qua, khung soạn tin chấp nhận tin nhắn — đó là lúc panel thực sự hoạt động.

    Màn hình cài đặt Browzy với ô Base URL, API key và mô hình
    Cài đặt: Base URL và API key của riêng bạn, cùng mô hình muốn dùng. Khoá được lưu vào kho bảo mật của hệ điều hành, không nằm trong trang.

Khi có trục trặc

Windows báo "running scripts is disabled on this system"

Đây là chính sách thực thi của Windows, không phải lỗi Browzy: PowerShell mặc định từ chối mọi file .ps1 chưa ký, kể cả file nằm sẵn trên máy bạn. Bạn gặp lỗi này khi gõ thẳng .\install.ps1 thay vì dòng lệnh ở trên — dòng đó đã có sẵn tiền tố -ExecutionPolicy Bypass để tránh. Dùng đúng dòng đó, hoặc mở Git Bash rồi chạy ./install.sh. Muốn khỏi vướng về sau, đặt một lần cho tài khoản của bạn (không cần quyền admin): Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned.

Panel hiện "Chưa cài companion"

Extension không tìm thấy native host. Chạy lại lệnh cài đặt theo hệ điều hành của bạn, rồi tải lại extension ở chrome://extensions.

Panel đứng ở "Đang kết nối" mãi

Companion đã đăng ký nhưng không khởi động được. Chạy lệnh doctor bên dưới — nguyên nhân hay gặp nhất là đăng ký trỏ vào một đường dẫn không còn tồn tại, do thư mục repo bị di chuyển hoặc đổi tên sau khi cài. Chạy lại installer là xong.

Bạn đã di chuyển hoặc đổi tên thư mục repo

Đăng ký ghi đường dẫn tuyệt đối tới đúng thư mục này. Di chuyển hay đổi tên là đăng ký hỏng — chạy lại installer ở vị trí mới.

Kiểm tra bằng browzy doctor

Lệnh này chỉ đọc, không sửa gì. Chạy nó từ bên trong repo vừa clone:

node host/bin/browzy.js doctor

Nếu bạn đã cài companion toàn cục qua npm (xem FAQ bên dưới), lệnh ngắn hơn browzy doctor hoạt động y hệt.

Đọc kết quả thế nào

  • Default extension id — id mà doctor kỳ vọng companion trả lời.
  • native-host.js present: yes/NO — file companion mà bản clone này trỏ tới có còn tồn tại không.
  • Một khối cho mỗi trình duyệt được kiểm tra, cho biết đường dẫn manifest, đường dẫn companion nó trỏ tới (exists hay MISSING), và allowed_origins đã đăng ký.

Câu hỏi hay gặp

Đã cài gói npm rồi, sao vẫn phải clone?

Gói @huydepzai2810/browzy-host trên npm chỉ chứa companion, không chứa extension. Load unpacked cần một thư mục extension/ có thật trên đĩa. Nên hôm nay, nếu đằng nào cũng phải clone để lấy extension, thì ./install.sh đã cài luôn companion và npm i -g là bước thừa. Gói npm chỉ thật sự cần khi Browzy đã lên Chrome Web Store — lúc đó extension đến từ store và chỉ companion là còn thiếu.

Dữ liệu của tôi đi đâu?

Không đi qua hạ tầng nào của Browzy — vì không có hạ tầng nào cả. Nội dung trang và tin nhắn của bạn đi thẳng từ máy bạn tới điểm cuối AI do bạn cấu hình.

Đọc chính sách quyền riêng tư

Sẵn sàng thử chưa?

Quay lại trang giới thiệu Browzy, hoặc vào thẳng repository.

Giới thiệu Browzy Xem Repository