📖 Hướng dẫn sử dụng BizClaw

Tài liệu đầy đủ từ cài đặt đến vận hành — AI Agent Platform mã nguồn mở cho doanh nghiệp.

1. Giới thiệu

BizClaw là nền tảng AI Agent viết 100% bằng Rust, tự host hoàn toàn — dữ liệu không rời khỏi máy bạn. Hỗ trợ 15 AI providers, 9 kênh giao tiếp, 15 công cụ, MCP mở rộng vô hạn.

2. Yêu cầu hệ thống

3. Cài đặt

3.1 One-Click Install (Khuyến nghị)

curl -sSL https://bizclaw.vn/install.sh | sudo bash

Script tự động: cài Rust, clone repo, build release, tạo systemd service, khởi chạy.

3.2 Docker Compose

git clone https://github.com/nguyenduchoai/bizclaw-cloud.git
cd bizclaw
docker-compose up -d

3.3 Build from Source

# Cài Rust (nếu chưa có)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Clone & build
git clone https://github.com/nguyenduchoai/bizclaw-cloud.git
cd bizclaw
cargo build --release

# Chạy Gateway (standalone)
./target/release/bizclaw serve --port 3000

# Hoặc chạy Platform (multi-tenant)
./target/release/bizclaw-platform --port 3001

4. Chạy lần đầu

Sau khi cài đặt, truy cập Dashboard:

# Platform mode
http://your-ip:3001

# Default Admin credentials
Email:    admin@your-domain.com
Password: (set via BIZCLAW_ADMIN_PASSWORD env var or auto-generated on first run)

Các bước tiếp theo:

1. Vào Providers → nhập API Key (OpenAI, Gemini, Ollama...)
2. Vào Agents → tạo agent hoặc cài từ Gallery (51 mẫu)
3. Vào Chat → bắt đầu trò chuyện real-time
4. (Tùy chọn) Vào Channels → kết nối Telegram, Zalo, Discord...

5. Web Dashboard

Dashboard 12 trang, song ngữ VI/EN, WebSocket real-time:

6. AI Providers

BizClaw hỗ trợ 15 providers. Mỗi agent chọn provider riêng → tiết kiệm 60-80% chi phí:

7. Agents & Gallery

51 mẫu agent, 13 danh mục. Cài 1 click:

HR (5) · Sales (5) · Finance (5) · Operations (5) · Legal (4) · Customer Service (3) · Marketing (5) · E-commerce (3) · Management (5) · Admin (3) · IT (3) · Business (3) · Training (2)

8. Group Chat

Tạo nhóm nhiều agent, mỗi agent dùng provider khác nhau. Gửi 1 câu hỏi → tất cả phản hồi:

# Ví dụ: Pitch nhà đầu tư
Bạn: "Chuẩn bị pitch cho Series A"
  ├── 🧑‍💼 Chiến lược (Claude)  → TAM/SAM/SOM, moat
  ├── 📊 Tài chính (DeepSeek)  → Unit economics
  ├── 📣 Marketing (Gemini)    → Brand story
  └── ⚖️ Pháp lý (Groq)       → Term sheet

9. Kết nối Channels

Telegram

[channel.telegram]
enabled = true
bot_token = "123456789:ABCdef..."
allowed_chat_ids = [12345678]

Discord

[channel.discord]
enabled = true
bot_token = "your-discord-bot-token"
allowed_channel_ids = [1234567890]

Zalo (Cá nhân + OA)

[channel.zalo]
enabled = true
mode = "personal"    # personal | official

[channel.zalo.personal]
cookie_path = "~/.bizclaw/zalo/cookie.json"
imei = "your-device-imei"

Webhook

Nhận HTTP POST từ bất kỳ hệ thống nào → AI xử lý → trả response.

Email (IMAP/SMTP)

Tự động đọc email qua IMAP polling, trả lời qua SMTP.

10. Knowledge RAG

Upload tài liệu → hệ thống chunk, index FTS5 → agent tự search khi chat.

11. Scheduler

Tạo task hẹn giờ. Agent tự chạy background theo lịch.

12. Cấu hình (config.toml)

File cấu hình chính tại ~/.bizclaw/config.toml:

# AI Provider mặc định
api_key = "sk-your-key"
default_provider = "openai"
default_model = "gpt-4o-mini"

[identity]
name = "BizClaw"
system_prompt = "Bạn là trợ lý AI thông minh."

[brain]
enabled = true
model_path = "~/.bizclaw/models/tinyllama.gguf"
threads = 4

[gateway]
port = 3000
host = "127.0.0.1"

[autonomy]
level = "supervised"
allowed_commands = ["git", "npm", "cargo"]

[secrets]
encrypt = true

13. Identity (Nhân cách AI)

[identity]
name = "Linh"
persona = "Nhân viên tư vấn bất động sản"
system_prompt = """
Bạn là Linh, nhân viên tư vấn BĐS công ty ABC.
Luôn trả lời lịch sự, chuyên nghiệp, bằng tiếng Việt.
"""

14. Brain Engine (LLM Offline)

# Tải model GGUF
mkdir -p ~/.bizclaw/models
wget -O ~/.bizclaw/models/tinyllama.gguf \
  https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf

# Hoặc dùng Ollama (đơn giản hơn)
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3.2
ollama pull qwen3

15. MCP Servers

[[mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
[mcp_servers.env]
GITHUB_TOKEN = "ghp_xxx"

16. Bảo mật

17. Multi-Tenant Platform

./target/release/bizclaw-platform --port 3001

18. Docker

docker-compose up -d
# Dashboard: http://localhost:3001

19. Raspberry Pi

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/nguyenduchoai/bizclaw-cloud.git
cd bizclaw && cargo build --release  # ~5-10 phút trên Pi 4
./target/release/bizclaw serve

20. Systemd Service

[Unit]
Description=BizClaw AI Agent
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/bizclaw-platform --port 3001
Restart=always
Environment=RUST_LOG=info
Environment=JWT_SECRET=your-secret

[Install]
WantedBy=multi-user.target

sudo systemctl enable bizclaw-platform
sudo systemctl start bizclaw-platform

21. Nginx Reverse Proxy

server {
    server_name apps.bizclaw.vn;
    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

22. API Reference

Gateway API

Platform Admin API

23. Biến môi trường

24. Crate Map

25. FAQ

❓ Có cần internet không?

Không. Brain Engine + Ollama hoạt động hoàn toàn offline.

❓ License?

MIT — Miễn phí vĩnh viễn.

❓ Cập nhật?

cd bizclaw && git pull && cargo build --release
sudo systemctl restart bizclaw-platform

26. Xử lý lỗi

Lỗi build trên ARM

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev

Cross-compile lỗi

⚠️ Phải build trực tiếp trên VPS, không cross-compile từ macOS.

VPS cargo not found

source ~/.cargo/env

Text file busy

sudo systemctl stop bizclaw-platform
# Rồi copy binary mới