Hướng Dẫn Cài Đặt & Sử Dụng

Gợi Ý Cài Đặt Siêu Dễ (Cho Người Mới)

Bạn không rành công nghệ? Đừng lo. Chỉ cần làm đúng thứ tự 5 bước vỡ lòng sau đây:

1 Bước 1: Cài Đặt Ứng Dụng HiveMind

Mở màn hình máy tính đen xì ra và dán lệnh cài đặt tự động. Rất an toàn!

Dành cho Windows: Ấn phím Windows (phím Start), gõ chữ PowerShell, rồi chọn Run as Administrator (Chạy với quyền Quản trị). Sau đó copy dòng này dán vào và ấn Enter:

irm https://hivemind.bug.edu.vn/install.ps1 | iex

Dành cho MacBook / Linux: Mở ứng dụng tên là Terminal. Dán dòng này vào và ấn Enter:

curl -fsSL https://hivemind.bug.edu.vn/install.sh | bash

2 Bước 2: Xem Mã Máy Kích Hoạt (HWID)

Mỗi máy tính là một ổ khóa, cần có chìa khóa để chạy. Vẫn ở cửa sổ đen đen lúc nãy, bạn gõ lệnh này để xem "mã ổ khóa" của máy mình:

hivemind license info

Màn hình sẽ in ra một đoạn mã gọi là HWID. Hãy copy đoạn này đưa cho Bot cấp Key. Khi có Key rồi, bạn gõ lệnh kích hoạt sau để mở máy (Thay đoạn mã bằng key thật của bạn):

hivemind activate -k HM-XXXX-YYYY CỦA BẠN Ở ĐÂY

3 Bước 3: Đánh Thức Ứng Dụng (Chạy Server)

Mở khóa xong, bây giờ chúng ta cho ứng dụng chạy bằng đúng 1 câu cẩu quyết này:

hivemind serve

⚠️ Quan trọng: Khi thấy màn hình hiện chữ loằng ngoằng đang chạy, tuyệt đối không ấn dấu X đỏ để tắt cửa sổ đen đó! Hãy ấn nút thu nhỏ "_" để cất nó xuống thanh ngang dưới cùng màn hình.

4 Bước 4: Mở Giao Diện Web (Bảng Điều Khiển)

Bây giờ, hãy mở ứng dụng vào mạng quen thuộc của bạn (Chrome, Cốc Cốc, Edge...) lên. Bấm vào thanh gõ trang web phía trên cùng, dán dòng chữ này vào:

Link Truy Cập: http://localhost:1337

Ngay lập tức, trang web đòi bạn nhập "Admin Password" (Mật khẩu Quản trị). Đừng hoảng, hãy lấy mật khẩu khoá mặc định này để nhập:

Admin Key: admin-secret-hq8F2p9vX

Xong! Chào mừng bạn vào trung tâm quản lý tài khoản.

5 Bước 5: Cắm Extension Vào Trình Duyệt Là Xong

Bước cuối cùng, làm sao để con AI nó gõ hộ mình?

1. Lên trang Bảng Điều Khiển ở bước số 4 (hoặc tải trực tiếp tại đây), ấn nút bự ở trên cùng để Tải File Extension.zip về máy. Sau đó ấn chuột phải vào file vừa tải, chọn Extract Here (Giải nén).

2. Mở Chrome, gõ thanh địa chỉ: chrome://extensions/

3. Gạt nút "Chế độ dành cho nhà phát triển" (Developer mode) trên cùng bên tay phải cho nó sáng màu xanh lên.

4. Bấm chữ "Tải tiện ích đã giải nén" (Load unpacked). Tìm đến cái thư mục có chứa ảnh con Ong bạn vừa giải nén ra lúc nãy click chọn nó!

5. Nhìn lên góc trên cùng bên phải của Chrome, bấm vào icon hình con Ong (HiveMind). Nhập Server URL là ws://localhost:1337/ws và ấn Lưu (Save).

6. Truy cập lại chatgpt.com, đăng nhập cái nick cũ của bạn là xong! Giờ cứ để tab ở đấy, AI bên phần mềm nó sẽ tự nhảy vào gõ như ma nhập cho coi.

🌐 Cấu Hình Trình Duyệt Tự Động (Trinhduyet)

Ngoài cách dùng Extension thủ công ở Bước 5, HiveMind còn hỗ trợ Trinhduyet — trình duyệt tự động chạy trên server, không cần cắm Extension bằng tay. Phù hợp cho VPS, chạy nền 24/7, hoặc nhiều tài khoản cùng lúc.

⚡ Trinhduyet vs Extension:
- Extension: Cắm tay vào Chrome → đơn giản, phù hợp máy cá nhân.
- Trinhduyet: Tự mở trình duyệt ảo → tự động hoàn toàn, chạy nhiều tài khoản, phù hợp VPS.

Yêu cầu

Node.js 18+ — Tải tại nodejs.org
HiveMind server đang chạy (hivemind serve)
Ít nhất 1 tài khoản đã được tạo trên Admin Panel

Cách 1: Khởi động từ Admin Panel (Đơn giản nhất)

1. Mở Admin Panel tại http://localhost:1337

2. Vào trang Accounts, nhấn nút 🌐 Launch Trinhduyet trên thanh công cụ.

3. Một cửa sổ terminal mới sẽ mở ra — trinhduyet tự cài đặt dependencies và khởi chạy.

Cách 2: Khởi động bằng lệnh (VPS / Terminal)

Windows:

cd %USERPROFILE%\.hivemind\trinhduyet
start.bat

macOS / Linux:

cd ~/.hivemind/trinhduyet
bash start.sh

Đăng nhập tài khoản ChatGPT

Khi chạy lần đầu, trinhduyet sẽ tự mở trình duyệt cho mỗi tài khoản chưa đăng nhập. Bạn chỉ cần:

1. Đăng nhập ChatGPT trên cửa sổ trình duyệt vừa mở ra.

2. Sau khi đăng nhập xong, trinhduyet tự lưu session vào ~/.hivemind/trinhduyet/sessions/.

3. Các lần sau không cần đăng nhập lại — session được giữ tự động.

Chạy nhiều tài khoản cùng lúc

Trinhduyet tự đọc tất cả tài khoản từ HiveMind database. Mỗi tài khoản = 1 cửa sổ trình duyệt riêng, chạy song song.

Thành phần	Đường dẫn	Mô tả
Thư mục gốc	`~/.hivemind/trinhduyet/`	Chứa app, launcher, config
Accounts	`~/.hivemind/trinhduyet/accounts.json`	Tự đồng bộ từ HiveMind DB
Sessions	`~/.hivemind/trinhduyet/sessions/{id}/`	Cookie + localStorage mỗi tài khoản
Launcher (Win)	`start.bat`	Double-click để chạy trên Windows
Launcher (Unix)	`start.sh`	Chạy trên macOS / Linux

💡 Mẹo:
- Tạo nhiều tài khoản trên Admin Panel → tất cả tự đồng bộ sang trinhduyet.
- Nếu session hết hạn, xóa thư mục sessions/{id}/ rồi chạy lại — sẽ yêu cầu đăng nhập lại.
- Chạy trên VPS nên dùng tmux hoặc screen để giữ process khi tắt SSH.

Tích Hợp API Proxy (v1 / v97 / v98 / v99)

HiveMind hiện hỗ trợ nhiều endpoint theo từng nhóm IDE/Agent. Bạn có thể dùng endpoint chuẩn OpenAI (/v1) hoặc endpoint proxy chuyên biệt để giới hạn tool theo profile.

Checklist nhanh

Server đang chạy: hivemind serve
Có API key hợp lệ: Authorization: Bearer sk-xxx
Request body theo chuẩn OpenAI chat completion

{
  "model": "gpt-5.4",
  "messages": [{ "role": "user", "content": "Xin chào HiveMind" }],
  "stream": false
}

Bảng endpoint

Nhóm API	Endpoint mặc định	Endpoint profile	Profile hợp lệ
OpenAI Compatible	`/v1/chat/completions`	-	-
OpenCLAW	`/v99/chat/completions`	`/v99/chat/{profile}/completions`	`core`, `filesystem`, `shell`, `search`
Cline / Roo Code	`/v98/chat/completions`	`/v98/chat/{profile}/completions`	`core`, `filesystem`, `shell`, `search`
Cursor / Windsurf	`/v97/chat/completions`	`/v97/chat/{profile}/completions`	`core`, `filesystem`, `terminal`, `search`
OpenRouter Compatible	`/openrouter/v1/chat/completions`	`/openrouter/v1/chat/{profile}/completions`	`core`, `filesystem`, `shell`, `search`

Copy-paste theo client

1) OpenAI SDK (Node.js / Python style)

Dùng endpoint chuẩn OpenAI để thay thế nhanh:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxx",
  baseURL: "http://localhost:1337/v1",
});

const res = await client.chat.completions.create({
  model: "gpt-5.4",
  messages: [{ role: "user", content: "Viết hàm Rust parse JSON" }],
});

console.log(res.choices[0].message.content);

2) OpenCLAW (v99)

Nếu bạn muốn giới hạn tool theo profile, gọi trực tiếp endpoint tương ứng:

curl -X POST http://localhost:1337/v99/chat/filesystem/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"openclaw-v99",
    "messages":[{"role":"user","content":"Đọc file README.md"}]
  }'

Tool map OpenCLAW:
core: read, write, edit, apply_patch, exec, process, web_search, web_fetch
filesystem: read, write, edit, apply_patch
shell: exec, process
search: web_search, web_fetch

3) Cline / Roo Code (v98)

curl -X POST http://localhost:1337/v98/chat/shell/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"cline-v98",
    "messages":[{"role":"user","content":"Chạy npm test"}]
  }'

Tool map Cline/Roo:
core: execute_command, read_file, write_to_file, replace_in_file, read_multiple_files, search_files, list_files, list_code_definition_names
filesystem: read_file, read_multiple_files, write_to_file, replace_in_file, list_files
shell: execute_command
search: search_files

4) Cursor / Windsurf (v97)

curl -X POST http://localhost:1337/v97/chat/terminal/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"cursor-v97",
    "messages":[{"role":"user","content":"Build project này giúp tôi"}]
  }'

Tool map Cursor/Windsurf:
core: run_terminal_command, edit_file, read_file, codebase_search
filesystem: read_file, edit_file
terminal: run_terminal_command
search: codebase_search

5) OpenRouter-compatible route

curl -X POST http://localhost:1337/openrouter/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"openrouter-v1",
    "messages":[{"role":"user","content":"Giải thích tokio runtime"}]
  }'

Lưu ý lỗi thường gặp:
- Sai profile slug: trả 400 InvalidRequest.
- Chưa kích hoạt license: trả 403 license_required.
- Thiếu Bearer key hoặc key sai: trả 401 Unauthorized.
- Hệ thống có alias tương thích IDE: bash -> exec, run_terminal_cmd -> run_terminal_command, list_dir -> list_files.

🗑️ Gỡ Cài Đặt (Uninstall)

Nếu bạn muốn xóa HiveMind hoàn toàn khỏi máy, làm theo các bước sau:

Windows (PowerShell — chạy với quyền Administrator)

# 1. Dừng service nếu đang chạy
Stop-Service HiveMind -ErrorAction SilentlyContinue
sc.exe delete HiveMind

# 2. Xóa file chương trình
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Programs\hivemind"

# 3. Xóa dữ liệu (database, conversations, sessions)
Remove-Item -Recurse -Force "$env:USERPROFILE\.hivemind"

# 4. Xóa hivemind khỏi PATH (mở System Environment Variables → xóa dòng chứa hivemind)
# Hoặc chạy lệnh sau:
$path = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = ($path -split ";" | Where-Object { $_ -notmatch "hivemind" }) -join ";"
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")

macOS / Linux (Terminal)

# 1. Dừng service nếu đang chạy
sudo systemctl stop hivemind 2>/dev/null
sudo systemctl disable hivemind 2>/dev/null
sudo rm -f /etc/systemd/system/hivemind.service

# 2. Xóa file chương trình
sudo rm -rf /usr/local/bin/hivemind
rm -rf ~/.local/bin/hivemind

# 3. Xóa dữ liệu (database, conversations, sessions)
rm -rf ~/.hivemind

# 4. Xóa PATH (nếu đã thêm vào .bashrc/.zshrc)
# Mở file ~/.bashrc hoặc ~/.zshrc, xóa dòng chứa "hivemind"

Hủy kích hoạt License (trước khi xóa)

Nếu bạn muốn chuyển license sang máy khác, hãy hủy kích hoạt trước khi xóa:

hivemind deactivate

Gỡ Extension Chrome

1. Mở chrome://extensions/

2. Tìm HiveMind → nhấn Remove (Xóa).

⚠️ Lưu ý: Xóa thư mục ~/.hivemind sẽ xóa toàn bộ database, conversations, sessions trình duyệt, và cấu hình. Hành động này không thể hoàn tác.

Tài Liệu Hướng Dẫn