AstrBot: chatbot AI đa nền tảng chat, cài bằng một lệnh — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
AstrBot là nền tảng chatbot Agent mã nguồn mở viết bằng Python. Nó nối các mô hình ngôn ngữ (OpenAI, Anthropic, Gemini, DeepSeek, Ollama…) vào các ứng dụng nhắn tin để bạn có trợ lý AI, chăm sóc khách hàng tự động hoặc bot nội bộ. Cài bằng công cụ uv chỉ với ba lệnh, hoặc dùng Docker nếu cần chạy ổn định lâu dài.
AstrBot là nền tảng chatbot AI mã nguồn mở, giúp bạn đưa một "bộ não" AI vào chính ứng dụng nhắn tin mà bạn và đồng nghiệp, khách hàng đang dùng. Bạn chọn mô hình (OpenAI, Anthropic, Gemini, DeepSeek, Ollama…), chọn nơi bot sẽ hoạt động (Telegram, Discord, Slack, Feishu, DingTalk…), rồi cấu hình tất cả qua giao diện web.
Repo này hợp với ba nhóm người. Thứ nhất là chủ shop hay doanh nghiệp nhỏ muốn có bot trả lời khách trong kênh chat có sẵn. Thứ hai là nhân viên văn phòng muốn một trợ lý AI dùng chung cho cả nhóm. Thứ ba là lập trình viên mới muốn một nền tảng sẵn có để thử Agent, MCP, Skills hay plugin mà không phải tự viết từ đầu.
Điểm đáng giá nhất là độ "đầy đủ". Một repo gom sẵn nhiều thứ: kết nối nền tảng chat, nhiều nhà cung cấp mô hình, giao diện quản trị, kho plugin và môi trường chạy code cách ly. Repo hiện có khoảng 46.823 sao và 3.547 fork, vẫn được cập nhật trong 3 tháng gần đây. Giấy phép là AGPL-3.0.
AstrBotDevs/AstrBot
AstrBot là nền tảng chatbot AI mã nguồn mở, nối các mô hình như ChatGPT, Gemini, DeepSeek vào Telegram, Discord, Slack, Feishu, DingTalk và nhiều ứng dụng chat khác.
I.AstrBot làm được gì
Dưới đây là các tính năng chính theo README, kèm lợi ích thực tế của từng cái.
A.Trò chuyện AI và các khả năng Agent
AstrBot hỗ trợ hội thoại với mô hình ngôn ngữ, xử lý đa phương thức, Agent, MCP, Skills, kho tri thức, thiết lập persona (tính cách bot) và tự nén ngữ cảnh. Nói đơn giản: bot có thể được "đặt vai" (ví dụ nhân viên tư vấn lịch sự), được nạp tài liệu riêng của bạn để trả lời theo đó, và không bị quá dài khi cuộc trò chuyện kéo dài.
B.Nhiều nền tảng chat trong một bot
README liệt kê các nền tảng do nhóm tác giả hỗ trợ chính thức: QQ, OneBot v11, Telegram, WeCom, WeChat Official Accounts, Feishu (Lark), DingTalk, Slack, Discord, LINE, Satori, KOOK, Misskey, Mattermost. WhatsApp được ghi là "Coming Soon" (sắp có). Ngoài ra có thêm Matrix, Rocket.Chat, VoceChat do cộng đồng làm qua plugin. README không nhắc đến Zalo, nên nếu bạn cần Zalo thì hãy kiểm tra kỹ trước khi quyết định.
C.Nhiều nhà cung cấp mô hình
Bạn không bị khóa vào một hãng. README liệt kê OpenAI và các dịch vụ tương thích, Anthropic, Google Gemini, Moonshot AI, Zhipu AI, DeepSeek, cùng các mô hình tự chạy trên máy như Ollama và LM Studio. Có cả các cổng API gom nhiều mô hình. Ngoài ra còn các dịch vụ chuyển giọng nói thành chữ (OpenAI Whisper, SenseVoice…) và chữ thành giọng nói (OpenAI TTS, Gemini TTS, Edge TTS, Azure TTS…).
D.Nối với nền tảng agent có sẵn
Nếu bạn đã xây ứng dụng trên Dify, Alibaba Cloud Bailian hoặc Coze, AstrBot có thể đóng vai "cầu nối" để đưa ứng dụng đó vào các kênh chat.
E.Hơn 1000 plugin cài một chạm
README cho biết có hơn 1000 plugin có thể cài chỉ với một thao tác. Cần thêm chức năng gì, bạn thử tìm plugin trước khi nghĩ đến chuyện tự viết.
F.Agent Sandbox
Khi bot cần chạy code hay lệnh shell, Agent Sandbox cho phép làm việc đó trong môi trường cách ly. Nhờ vậy, việc để AI chạy code ít rủi ro hơn so với chạy thẳng trên máy của bạn.
G.WebUI và Web ChatUI
Bạn quản lý bot qua giao diện web, không cần sửa file cấu hình bằng tay. Web ChatUI cho phép chat với bot ngay trên trình duyệt, có sẵn sandbox và tìm kiếm web. Giao diện cũng hỗ trợ đa ngôn ngữ (i18n).
II.Cần chuẩn bị gì
Tư liệu nói rõ những điều sau:
- Python 3.12 trở lênfile pyproject.toml của repo yêu cầu Python từ 3.12. Nếu cài bằng uv theo README, lệnh đã chỉ định luôn Python 3.12.
- uvcông cụ quản lý môi trường Python. README ghi rõ cách cài nhanh cần có uv.
- Docker / Docker Composechỉ cần nếu bạn chọn cách triển khai bằng container.
- Tài khoản và khóa APIbot cần một mô hình ngôn ngữ để trả lời. Bạn cần khóa API từ nhà cung cấp bạn chọn, hoặc một mô hình tự chạy như Ollama hay LM Studio. README không nêu khóa nào bắt buộc.
- Tài khoản nền tảng chatví dụ bot Telegram, ứng dụng Discord hay Slack mà bạn muốn gắn vào. Mỗi nền tảng có cách tạo bot riêng, xem tài liệu chính thức trên trang astrbot.app.
- Hệ điều hànhREADME nhắc riêng người dùng macOS (lần chạy đầu có thể chậm). README không nói giới hạn nào về Windows hay Linux. Phần phần cứng (GPU, RAM) cũng chưa có thông tin trong tư liệu.
Khóa API là chìa khóa tính tiền của bạn. Đừng dán vào ảnh chụp màn hình, tin nhắn nhóm hay nơi công khai. Nếu bot đặt trong nhóm đông người, hãy theo dõi mức sử dụng ở nhà cung cấp mô hình để tránh bị tính phí ngoài ý muốn.
III.Cài đặt từng bước
README đưa ra nhiều cách triển khai. Bài này hướng dẫn cách nhanh nhất cho người mới (dùng uv) và nói ngắn về Docker.
- Cài uvcông cụ cần có trước khi cài AstrBot
- Cài AstrBotdùng uv tool install với Python 3.12
- Khởi tạochạy astrbot init một lần duy nhất
- Chạy botchạy astrbot run để khởi động
- Cấu hìnhmở WebUI, điền khóa API và gắn nền tảng chat
A.Cài uv
README yêu cầu bạn tự cài uv trước. README không đưa lệnh cài uv, nên bạn xem hướng dẫn chính thức tại docs.astral.sh/uv. Cài xong, mở một cửa sổ terminal mới (trên Windows dùng PowerShell hoặc Windows Terminal) rồi gõ thử lệnh dưới đây để chắc chắn máy đã nhận uv.
uv --versionLệnh này chỉ in ra phiên bản uv. Chỗ người mới hay vấp là cài xong nhưng mở lại terminal cũ nên máy vẫn báo không tìm thấy lệnh. Hãy đóng terminal và mở cái mới.
B.Cài AstrBot
Đây là lệnh trong README. uv sẽ cài AstrBot như một công cụ dòng lệnh riêng, dùng Python 3.12.
uv tool install astrbot --python 3.12Bạn không cần tải mã nguồn về hay tạo môi trường ảo thủ công.
C.Khởi tạo môi trường
Lệnh này chỉ chạy lần đầu để tạo môi trường làm việc cho AstrBot.
astrbot initREADME nhấn mạnh: chỉ chạy lệnh này lần đầu. Những lần sau không cần chạy lại.
D.Chạy AstrBot
astrbot runTerminal sẽ giữ nguyên và in log trong lúc bot chạy. Đừng đóng cửa sổ này, vì đóng là bot dừng. Riêng người dùng macOS: lần chạy đầu của lệnh astrbot có thể mất khoảng 10-20 giây do kiểm tra bảo mật của hệ điều hành. Bạn cứ chờ, không phải treo máy.
E.Cấu hình trong WebUI
Sau khi chạy, bạn cấu hình qua WebUI: thêm nhà cung cấp mô hình (dán khóa API), rồi thêm nền tảng chat muốn gắn. README không ghi địa chỉ và cổng của WebUI, nên hãy xem log trong terminal hoặc tài liệu trên astrbot.app để biết địa chỉ chính xác.
F.Cập nhật phiên bản mới
Khi có bản mới, bạn dùng lệnh sau theo README:
uv tool upgrade astrbot --python 3.12G.Cách khác: Docker
Nếu bạn quen với container và muốn chạy ổn định lâu dài trên máy chủ, README khuyên dùng Docker hoặc Docker Compose và dẫn tới trang tài liệu "Deploy AstrBot with Docker" trên docs.astrbot.app. Repo có sẵn các file Dockerfile, compose.yml và thư mục k8s. README không chép lệnh Docker cụ thể, nên hãy làm theo trang tài liệu đó. Nếu muốn xem cấu hình mẫu, bạn có thể tải mã nguồn về:
git clone https://github.com/AstrBotDevs/AstrBot.git
cd AstrBotREADME còn nhắc các cách khác: ứng dụng desktop AstrBot-desktop (hợp khi chủ yếu dùng ChatUI trên máy cá nhân, không khuyến nghị cho máy chủ), AstrBot Launcher (chạy nhiều bản riêng biệt), các bảng điều khiển như BT-Panel, 1Panel, CasaOS, và triển khai từ mã nguồn. Ngoài ra còn có dịch vụ triển khai đám mây một chạm của RainYun nếu bạn không muốn tự quản lý máy chủ.
IV.Kiểm tra đã chạy được chưa
README không mô tả chi tiết màn hình kết quả. Bạn có thể kiểm tra theo các dấu hiệu hợp lý sau:
- Lệnh astrbot run không báo lỗi ngay mà giữ terminal ở trạng thái đang chạy, có in log.
- Bạn mở được WebUI theo địa chỉ ghi trong log hoặc tài liệu.
- Sau khi thêm khóa API và một mô hình, bạn thử nhắn một câu vào Web ChatUI (khung chat có sẵn trên trình duyệt). Nếu bot trả lời, phần lõi đã hoạt động.
- Gắn thêm một nền tảng chat (ví dụ Telegram), nhắn thử cho bot. Bot trả lời nghĩa là toàn bộ chuỗi "nền tảng chat → AstrBot → mô hình AI" đã thông.
Nếu bước chat thử không có phản hồi, hãy đọc log trong terminal trước. Log thường nói rõ lỗi nằm ở khóa API, mô hình hay kết nối nền tảng.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo khả năng ghi trong README. Phần thao tác cụ thể trong WebUI bạn xem thêm tài liệu chính thức.
A.Chủ shop có bot tư vấn trên kênh chat
Bạn bán hàng online và hay bị hỏi lặp lại: giờ giao hàng, đổi trả, bảo hành. Bạn dùng kho tri thức của AstrBot để nạp tài liệu chính sách của shop, đặt persona là nhân viên tư vấn lịch sự, rồi gắn bot vào kênh bạn đang dùng, chẳng hạn Telegram hoặc Discord. Khách nhắn "Đơn của em đổi size được không?", bot trả lời dựa trên tài liệu bạn đã nạp. Kết quả là bạn đỡ phải trả lời những câu giống nhau, còn các ca khó vẫn do bạn xử lý.
Bot hay nhất không phải bot biết nhiều nhất, mà là bot nằm sẵn trong kênh chat mà mọi người đã mở mỗi ngày.
Ông T
B.Nhân viên văn phòng có trợ lý chung cho cả nhóm
Công ty bạn dùng Slack, Feishu hoặc DingTalk. Bạn gắn AstrBot vào đó với một mô hình như DeepSeek hay Gemini, rồi cả nhóm nhắn nhờ bot những việc quen thuộc. Một prompt mẫu: "Soạn giúp mình email nhắc khách hàng thanh toán, giọng lịch sự, tối đa 5 câu". Hoặc: "Tóm tắt đoạn thảo luận này thành 3 gạch đầu dòng". Mọi người dùng chung một chỗ, và bạn là người giữ khóa API nên quản lý được chi phí tập trung.
C.Người muốn giữ dữ liệu trên máy mình
Bạn ngại gửi nội dung nội bộ ra dịch vụ bên ngoài. AstrBot hỗ trợ các mô hình tự chạy như Ollama và LM Studio. Bạn cài mô hình đó trên máy, khai báo nó làm nhà cung cấp trong WebUI, rồi chat với bot qua Web ChatUI. README không nói về mức độ riêng tư hay yêu cầu phần cứng, nên chất lượng và tốc độ còn tùy mô hình và máy của bạn.
D.Lập trình viên thử Agent, MCP và chạy code an toàn
Bạn muốn thử cho AI dùng công cụ (MCP, Skills) hoặc chạy code. Bạn bật Agent Sandbox để code và lệnh shell chạy trong môi trường cách ly, rồi nhắn bot một yêu cầu như "Viết và chạy đoạn Python tính tổng doanh thu theo tháng từ dữ liệu sau". Bạn thử được ý tưởng agent mà không phải để AI chạy lệnh thẳng trên máy chính. Cách cấu hình sandbox có trong trang tài liệu riêng của dự án.
VI.Lỗi hay gặp và cách xử lý
A.Báo không tìm thấy lệnh uv hoặc astrbot
Nguyên nhân thường là vừa cài xong nhưng vẫn dùng cửa sổ terminal cũ. Hãy đóng terminal, mở cửa sổ mới rồi thử lại lệnh uv --version. Nếu vẫn không được, hãy cài lại uv theo hướng dẫn chính thức. Đừng tự sửa biến PATH nếu bạn chưa quen.
B.Phiên bản Python không phù hợp
Repo yêu cầu Python từ 3.12 trở lên. Nếu bạn cài bằng cách khác (tải mã nguồn, dùng Python có sẵn trên máy) mà Python cũ hơn, việc cài sẽ lỗi. Cách an toàn là dùng đúng lệnh uv trong README, vì lệnh đã chỉ định Python 3.12.
C.Lần chạy đầu trên macOS rất chậm
README đã báo trước: lần chạy lệnh astrbot đầu tiên có thể mất khoảng 10-20 giây do kiểm tra bảo mật của macOS. Bạn chỉ cần chờ. Những lần sau sẽ nhanh hơn.
D.Bot không trả lời dù đã chạy
Đây là tình huống rất hay gặp với mọi loại chatbot. Hãy kiểm tra lần lượt: đã điền khóa API đúng chưa, tài khoản nhà cung cấp còn hạn mức không, đã chọn mô hình trong WebUI chưa, và nền tảng chat đã được bật và gắn đúng chưa. Thử chat trong Web ChatUI trước. Nếu ở đó bot trả lời được, lỗi nằm ở phần kết nối nền tảng chat. Mọi lỗi cụ thể đều nên đối chiếu với log trong terminal.
E.Tắt terminal là bot dừng
Với cách chạy astrbot run, bot sống cùng cửa sổ terminal. Muốn bot online liên tục (24 giờ), bạn nên chạy trên một máy luôn bật, hoặc chuyển sang Docker, hoặc dùng dịch vụ đám mây mà README gợi ý. Cách giữ tiến trình chạy nền khi dùng uv, README chưa ghi, bạn xem tài liệu trên astrbot.app.
VII.Có nên dùng không
Điểm mạnh. AstrBot miễn phí và mã nguồn mở. Phạm vi rộng: nhiều nền tảng chat, nhiều nhà cung cấp mô hình, có kho plugin lớn, WebUI để quản lý, và sandbox cho việc chạy code. Cài bằng uv chỉ ba lệnh, đủ để thử trong vài phút. Nếu cần chạy nghiêm túc, bạn có Docker, Kubernetes (thư mục k8s) và nhiều cách triển khai khác.
Giới hạn cần biết. Phần lớn tài liệu và cộng đồng của dự án thiên về tiếng Trung. README viết bằng nhiều ngôn ngữ nhưng các nền tảng như QQ, WeCom, DingTalk, Feishu chiếm vị trí nổi bật. README không nhắc Zalo, và WhatsApp mới ở mức "sắp có". README chưa nêu yêu cầu phần cứng, nên nếu bạn định chạy mô hình tự host, hãy tự kiểm tra máy mình. Giấy phép AGPL-3.0 có yêu cầu riêng khi bạn chỉnh sửa và cung cấp dịch vụ cho người khác. Nếu dùng cho kinh doanh, hãy đọc kỹ giấy phép hoặc hỏi người am hiểu pháp lý.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần chat với AI cho cá nhân, dùng thẳng ứng dụng của nhà cung cấp sẽ đơn giản hơn. Nếu bạn cần một sản phẩm có hợp đồng, hỗ trợ chính thức và cam kết dịch vụ, một giải pháp thương mại sẽ hợp hơn. Còn nếu bạn muốn tự lắp một bot đa nền tảng, có agent, plugin và giao diện quản trị mà không phải viết từ đầu, AstrBot đáng để thử trước.
Câu hỏi thường gặp
AstrBot có miễn phí không?
README ghi AstrBot miễn phí và mã nguồn mở, dùng giấy phép AGPL-3.0. Tuy nhiên bạn vẫn có thể phải trả phí cho nhà cung cấp mô hình AI (khóa API) hoặc máy chủ nếu dùng dịch vụ có tính phí. Chi phí này không do AstrBot thu.
Cài AstrBot nhanh nhất bằng cách nào?
Cách nhanh nhất theo README là dùng uv với ba lệnh: uv tool install astrbot --python 3.12, astrbot init (chỉ chạy lần đầu) và astrbot run. Bạn cần tự cài uv trước. README cũng có các cách khác như Docker, ứng dụng desktop và Launcher.
Cần Python phiên bản nào?
File pyproject.toml của repo yêu cầu Python từ 3.12 trở lên. Nếu cài bằng lệnh uv trong README, lệnh đã chỉ định Python 3.12 nên bạn không phải cài tay.
AstrBot có chạy được trên Windows không, và có cần GPU không?
README không nêu giới hạn về hệ điều hành, chỉ nhắc riêng lưu ý cho người dùng macOS. Tư liệu cũng chưa nói về yêu cầu GPU. Nếu bạn dùng mô hình qua API thì máy của bạn không phải làm phần nặng nhất. Nếu tự chạy mô hình bằng Ollama hay LM Studio, yêu cầu phần cứng tùy mô hình đó.
AstrBot kết nối được với những ứng dụng chat nào?
Nền tảng chính thức gồm QQ, OneBot v11, Telegram, WeCom, WeChat Official Accounts, Feishu, DingTalk, Slack, Discord, LINE, Satori, KOOK, Misskey và Mattermost. WhatsApp được ghi là sắp có. Cộng đồng có thêm Matrix, Rocket.Chat và VoceChat qua plugin. README không nhắc đến Zalo.
Dữ liệu của mình có an toàn không?
README không có phần riêng nói về quyền riêng tư dữ liệu. Bạn tự triển khai nên bot chạy trên máy hoặc máy chủ của bạn. Nội dung chat vẫn được gửi tới nhà cung cấp mô hình mà bạn chọn, trừ khi dùng mô hình tự host như Ollama. Bạn cũng nên giữ kín khóa API.
Agent Sandbox dùng để làm gì?
README mô tả Agent Sandbox là môi trường cách ly để chạy code và lệnh shell một cách an toàn hơn, có thể tái sử dụng tài nguyên theo từng phiên. Cách bật và cấu hình có trong trang tài liệu riêng của dự án trên docs.astrbot.app.


