8.6 KiB
| summary | read_when | ||
|---|---|---|---|
| Hướng dẫn cho người mới: từ số không đến tin nhắn đầu tiên (wizard, xác thực, các kênh, ghép nối) |
|
Hướng dẫn Bắt đầu (Getting Started)
Mục tiêu: đi từ số không → có cuộc trò chuyện đầu tiên (với các cấu hình mặc định hợp lý) nhanh nhất có thể.
Cách chat nhanh nhất: mở Control UI (không cần thiết lập kênh). Chạy lệnh moltbot dashboard và chat trong trình duyệt, hoặc mở http://127.0.0.1:18789/ trên máy chủ gateway.
Tùy chọn tài liệu: Dashboard và Control UI.
Con đường khuyên dùng: sử dụng trình hướng dẫn CLI (onboarding wizard) (moltbot onboard). Nó sẽ thiết lập giúp bạn:
- model/auth (xác thực - khuyên dùng OAuth)
- cấu hình gateway
- các kênh (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
- mặc định ghép nối (secure DMs)
- khởi tạo không gian làm việc + kỹ năng (workspace + skills)
- dịch vụ chạy ngầm tùy chọn
Nếu bạn muốn xem các trang tham chiếu chuyên sâu hơn, hãy nhảy đến: Wizard, Thiết lập, Ghép nối, Bảo mật.
Lưu ý về Sandboxing: agents.defaults.sandbox.mode: "non-main" sử dụng session.mainKey (mặc định là "main"), vì vậy các phiên (session) nhóm/kênh chat sẽ được đặt trong sandbox. Nếu bạn muốn agent chính luôn chạy trên host, hãy thiết lập ghi đè cụ thể cho từng agent:
{
"routing": {
"agents": {
"main": {
"workspace": "~/clawd",
"sandbox": { "mode": "off" }
}
}
}
}
0) Điều kiện tiên quyết
- Node
>=22 pnpm(tùy chọn; khuyên dùng nếu bạn build từ mã nguồn)- Khuyên dùng: API key của Brave Search để tìm kiếm web. Cách dễ nhất:
moltbot configure --section web(lưu trữtools.web.search.apiKey). Xem Công cụ Web.
macOS: nếu bạn định build app, hãy cài Xcode / CLT. Đối với CLI + gateway, chỉ cần Node là đủ. Windows: hãy sử dụng WSL2 (khuyên dùng Ubuntu). WSL2 cực kỳ được khuyến khích; chạy trực tiếp trên Windows (native) chưa được kiểm thử, nhiều lỗi hơn và khả năng tương thích công cụ kém hơn. Hãy cài WSL2 trước, sau đó thực hiện các bước Linux bên trong WSL. Xem Windows (WSL2).
1) Cài đặt CLI (Khuyên dùng)
curl -fsSL https://molt.bot/install.sh | bash
Các tùy chọn cài đặt (phương thức cài đặt, không tương tác, từ GitHub): Cài đặt.
Windows (PowerShell):
iwr -useb https://molt.bot/install.ps1 | iex
Cách khác (cài đặt global qua npm):
npm install -g moltbot@latest
pnpm add -g moltbot@latest
2) Chạy trình hướng dẫn cài đặt (và cài đặt dịch vụ)
moltbot onboard --install-daemon
Những gì bạn sẽ chọn:
- Gateway Local (cục bộ) hay Remote (từ xa)
- Auth (Xác thực): Gói thuê bao OpenAI (Codex) (OAuth) hoặc API keys. Với Anthropic, chúng tôi khuyên dùng API key;
claude setup-tokencũng được hỗ trợ. - Providers (Nhà cung cấp): Đăng nhập QR WhatsApp, bot tokens của Telegram/Discord, plugin tokens của Mattermost, v.v.
- Daemon (Dịch vụ chạy ngầm): cài đặt nền (launchd/systemd; WSL2 dùng systemd)
- Runtime: Node (khuyên dùng; bắt buộc đối với WhatsApp/Telegram). Bun không được khuyên dùng.
- Gateway token: trình hướng dẫn sẽ tự sinh một token mặc định và lưu trong
gateway.auth.token.
Tài liệu về Wizard: Wizard
Auth: nơi lưu trữ (quan trọng)
-
Cách dùng Anthropic khuyên dùng: thiết lập một API key (wizard có thể lưu nó để dịch vụ sử dụng).
claude setup-tokencũng được hỗ trợ nếu bạn muốn dùng lại thông tin đăng nhập của Claude Code. -
Thông tin đăng nhập OAuth (legacy import):
~/.clawdbot/credentials/oauth.json -
Cấu hình xác thực (OAuth + API keys):
~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
Mẹo cho máy chủ không có giao diện (headless): thực hiện OAuth trên máy bình thường trước, sau đó copy file oauth.json sang máy chủ gateway.
3) Khởi động Gateway
Nếu bạn đã cài đặt dịch vụ (service) trong quá trình onboarding, Gateway sẽ đã đang chạy rồi:
moltbot gateway status
Chạy thủ công (hiện nền):
moltbot gateway --port 18789 --verbose
Dashboard (local loopback): http://127.0.0.1:18789/
Nếu đã cài đặt token, hãy dán nó vào phần cài đặt Control UI (được lưu là connect.params.auth.token).
⚠️ Cảnh báo về Bun (WhatsApp + Telegram): Bun gặp một số lỗi đã biết với các kênh này. Nếu bạn dùng WhatsApp hoặc Telegram, hãy chạy Gateway bằng Node.
3.5) Kiểm tra nhanh (2 phút)
moltbot status
moltbot health
moltbot security audit --deep
4) Ghép nối + kết nối giao diện chat đầu tiên
WhatsApp (Đăng nhập qua QR)
moltbot channels login
Quét mã qua WhatsApp → Cài đặt (Settings) → Thiết bị liên kết (Linked Devices).
Tài liệu WhatsApp: WhatsApp
Telegram / Discord / các kênh khác
Trình hướng dẫn có thể viết token/cấu hình giúp bạn. Nếu bạn thích cấu hình thủ công, hãy bắt đầu tại:
- Telegram: Telegram
- Discord: Discord
- Mattermost (plugin): Mattermost
Mẹo cho Telegram DM: tin nhắn riêng đầu tiên của bạn sẽ nhận lại một mã ghép nối. Hãy phê duyệt nó (xem bước tiếp theo) nếu không bot sẽ không trả lời.
5) An toàn tin nhắn DM (phê duyệt ghép nối)
Chế độ mặc định: các tin nhắn DM từ người lạ sẽ nhận được một mã ngắn và tin nhắn không được xử lý cho đến khi được phê duyệt. Nếu tin nhắn DM đầu tiên của bạn không có phản hồi, hãy phê duyệt ghép nối:
moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>
Tài liệu Ghép nối: Pairing
Cài từ nguồn (dành cho phát triển)
Nếu bạn đang trực tiếp chỉnh sửa Moltbot, hãy chạy từ mã nguồn:
git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build # tự động cài deps cho UI lần đầu chạy
pnpm build
moltbot onboard --install-daemon
Nếu bạn chưa có bản cài đặt global, hãy chạy bước onboarding qua pnpm moltbot ... từ trong repo.
pnpm build cũng đóng gói các tài sản A2UI; nếu bạn chỉ cần chạy bước đó, hãy dùng pnpm canvas:a2ui:bundle.
Chạy Gateway (từ repo này):
node moltbot.mjs gateway --port 18789 --verbose
7) Xác minh toàn trình (End-to-end)
Trong một terminal mới, gửi một tin nhắn thử nghiệm:
moltbot message send --target +15555550123 --message "Xin chào từ Moltbot"
Nếu moltbot health báo “no auth configured”, hãy quay lại wizard và thiết lập OAuth/key auth — agent sẽ không thể phản hồi nếu không có nó.
Mẹo: moltbot status --all là báo cáo debug ở chế độ chỉ đọc tốt nhất để copy-paste.
Health probes: moltbot health (hoặc moltbot status --deep) sẽ hỏi gateway đang chạy để lấy ảnh chụp trạng thái sức khỏe hệ thống.
Các bước tiếp theo (tùy chọn, nhưng rất hay)
- App macOS trên menu bar + voice wake: Ứng dụng macOS
- Các node iOS/Android (Canvas/camera/giọng nói): Nodes
- Truy cập từ xa (SSH tunnel / Tailscale Serve): Truy cập từ xa và Tailscale
- Các thiết lập VPN / Always-on: Truy cập từ xa, exe.dev, Hetzner, macOS remote