Ran — hướng dẫn sử dụng

Từ lúc cài đặt tới lúc Ran tự trả lời: chín bước, làm theo đúng thứ tự.

1 Cài   →  2 Chọn model  →  3 Chạy  →  4 Đăng nhập QR  →  5 Cài đặt chung
   →  6 Thêm người / group  →  7 Cấu hình từng nơi  →  8 Thử  →  9 Vận hành

1. Cài

Cần Node.js 20 trở lên.

git clone https://github.com/dac2205/conan1.git
cd conan1/ran
npm install

2. Chọn model

Lựa chọn	Cần chuẩn bị
Claude (mặc định)	API key tại console.anthropic.com. Model mặc định là claude-sonnet-5-5
Ollama (chạy hẳn trên máy, miễn phí)	Cài Ollama, rồi ollama pull qwen3 (hoặc model khác). Provider ollama đã có sẵn với base URL http://localhost:11434/v1
FAQ offline (không mạng, không key)	Chọn provider offline. Ran chọn câu có sẵn trong tab FAQ offline (100 câu mặc định, sửa được) bằng so khớp từ khoá BM25 + trigram ký tự. Tin khớp dưới Ngưỡng FAQ (mặc định 0.6) thì Ran im lặng. Ô thử trong tab cho xem điểm khớp
Cloudflare Workers AI (không cần token)	npm start tự chạy kèm Worker local cf-proxy/ dùng phiên đăng nhập wrangler, gọi Workers AI qua AI Gateway conan1. Provider cloudflare, base URL http://127.0.0.1:8788/v1, model workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731
OpenAI, OpenRouter, LM Studio…	Thêm một provider kiểu openai với base URL và key tương ứng

3. Chạy

npm start            # Ran: http://127.0.0.1:3939

Mở trình duyệt vào http://127.0.0.1:3939. Tắt Ran bằng Ctrl+C; cấu hình vẫn được giữ trong ran/data/.

4. Đăng nhập Zalo

1. Đóng mọi tab Zalo Web của tài khoản này. Mỗi tài khoản chỉ giữ được một kết nối web; Zalo PC và điện thoại vẫn dùng bình thường.
2. Bấm Tạo mã QR, rồi dùng Zalo trên điện thoại quét mã và xác nhận.
3. Trạng thái chuyển sang Đã kết nối. Từ lần chạy sau Ran tự đăng nhập lại bằng phiên đã lưu.

WARNING

Ran dùng zca-js, một thư viện không chính thức. Zalo có thể hạn chế tài khoản. Đừng để Ran nhắn với số lượng lớn.

5. Cài đặt chung

Vào tab Cài đặt:

Ô	Gợi ý
Tên của bạn	Để model biết các tin "assistant" là của bạn
Provider	Dán API key cho anthropic hoặc chọn ollama làm mặc định
Persona chung	Cách bạn nhắn tin nói chung: xưng hô, độ dài, emoji, những điều không được hứa
Chờ gom tin	5 giây: người kia hay nhắn nhiều dòng liền, Ran đợi họ nhắn xong
Bạn tự nhắn → bot nhường	30 phút: bạn vừa nhắn tay thì Ran không chen vào

Bấm Lưu cài đặt.

6. Thêm người / group

Có hai cách:

• Bấm Tải danh bạ Zalo, gõ tên vào ô tìm kiếm rồi bấm +.
• Ở mục Vừa nhắn tới: ai nhắn cho bạn mà chưa được cấu hình sẽ hiện ở đây, bấm + để thêm.

Ran chỉ trả lời những người, những group có trong danh sách Đang theo dõi.

7. Cấu hình từng nơi

Chọn một mục trong Đang theo dõi:

Ô	Ví dụ
Chế độ	Người thân: Tự trả lời. Group công việc: Chỉ khi @ tôi. Khách quan trọng: Soạn nháp, tôi duyệt
Từ khoá	Ran, anh Conan, báo giá (dùng cho chế độ Chỉ khi @ tôi)
Model riêng	Group kỹ thuật dùng model mạnh; chat vui dùng Ollama
Persona riêng	"Với mẹ: xưng con, nhắn ấm áp, nhắc uống thuốc nếu mẹ hỏi"
Bối cảnh	"Group dự án Nemo12. Tôi phụ trách thiết kế; anh Bình là PM"

Bấm Lưu. Sau khoảng profileEvery tin, Ran tự viết Hồ sơ tự học; bạn có thể sửa tay hoặc bấm Học lại từ lịch sử.

Đúng

Mới bắt đầu thì để mọi nơi ở chế độ Soạn nháp. Duyệt vài ngày, chỉnh persona cho đúng giọng, rồi mới chuyển sang Tự trả lời.

8. Thử

Bấm Thử sinh câu trả lời: Ran viết câu trả lời cho lịch sử hiện tại nhưng không gửi. Kết quả (im lặng) nghĩa là Ran thấy không cần trả lời.

9. Vận hành hằng ngày

Việc	Cách
Duyệt nháp	Nháp hiện ở đầu trang. Sửa nếu cần, rồi bấm Gửi hoặc Bỏ
Dừng khẩn cấp	Bật Tạm dừng toàn bộ ở thanh trên cùng
Xem Ran đã làm gì	Tab Nhật ký
Mất kết nối, mã 3000	Có tab Zalo Web đang mở ở nơi khác: đóng tab đó rồi chạy lại npm start
Phiên hết hạn	Cài đặt → Đăng xuất Zalo, rồi quét QR lại
Sao lưu	Chép thư mục ran/data/. Giữ kín, vì trong đó có phiên Zalo và API key