# AstrBot: chatbot AI đa nền tảng, nối LLM vào Telegram, Discord, Slack — hướng dẫn cài đặt và dùng

> AstrBot là nền tảng chatbot AI Agent mã nguồn mở viết bằng Python. Nó giúp bạn nối các mô hình ngôn ngữ lớn vào ứng dụng nhắn tin như Telegram, Discord, Slack, DingTalk, Feishu. Cài bằng ba lệnh với uv nên khá dễ, ngoài ra có Docker và bản ứng dụng desktop.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-17 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/astrbot-chatbot-ai-agent-da-nen-tang-huong-dan-cai-dat

AstrBot là một nền tảng chatbot AI Agent mã nguồn mở, viết bằng Python. Nó đứng giữa ứng dụng nhắn tin của bạn (Telegram, Discord, Slack, Feishu, DingTalk…) và mô hình AI (OpenAI, Anthropic, Google Gemini, DeepSeek, Ollama…). Bạn nhắn vào chat, bot trả lời bằng AI.

Nếu bạn muốn có một trợ lý AI ngay trong nhóm chat của công ty, một bot chăm sóc khách hàng, hay một bạn đồng hành AI cá nhân, repo này đáng thử. Hiện repo có khoảng 46.823 sao và 3.547 fork, vẫn được cập nhật trong vài tháng gần đây. Giấy phép là AGPL-3.0, bạn nên đọc kỹ nếu định dùng thương mại hoặc sửa mã rồi cung cấp dịch vụ cho người khác.

Điểm đáng giá nhất: bạn không phải tự viết code kết nối từng nền tảng chat. AstrBot đã làm sẵn, có giao diện web (WebUI) để cấu hình, và hơn 1000 plugin cài một chạm theo README. Cài đặt nhanh nhất chỉ cần ba lệnh.

```repo
- repo | AstrBotDevs/AstrBot
- kind | Framework
- desc | AstrBot là nền tảng chatbot Agent mã nguồn mở, nối các mô hình AI (OpenAI, Gemini, Ollama…) vào Telegram, Discord, Slack, Feishu… kèm plugin, MCP, WebUI.
- stars | 47k
- lang | Python
- license | AGPL-3.0
```

## AstrBot làm được gì

Dưới đây là các tính năng chính, giải thích theo lợi ích thực tế.

- **Trò chuyện với mô hình AI, đa phương thức.** Bot hỗ trợ hội thoại LLM, đa phương thức, Agent, MCP, Skills, cơ sở tri thức (knowledge base), thiết lập nhân vật (persona) và tự động nén ngữ cảnh. Nghĩa là bạn có thể cho bot một "tính cách" riêng, cho nó đọc tài liệu của bạn, và cuộc trò chuyện dài không bị tràn bộ nhớ.
- **Nhiều nền tảng chat.** README liệt kê các nền tảng chính thức: QQ, giao thức OneBot v11, Telegram, WeCom, WeChat Official Accounts, Feishu (Lark), DingTalk, Slack, Discord, LINE, Satori, KOOK, Misskey, Mattermost. WhatsApp ghi là sắp có. Ngoài ra có adapter do cộng đồng làm cho Matrix, Rocket.Chat, VoceChat. Một bot có thể phục vụ nhiều kênh cùng lúc.
- **Nhiều nhà cung cấp mô hình.** README ghi hỗ trợ OpenAI và các dịch vụ tương thích, Anthropic, Google Gemini, Moonshot AI, Zhipu AI, DeepSeek, cùng mô hình tự chạy như Ollama và LM Studio. Có cả cổng API tổng hợp, chuyển giọng nói thành văn bản (Whisper, SenseVoice…) và văn bản thành giọng nói (OpenAI TTS, Edge TTS, Azure TTS…). Bạn chọn mô hình theo ngân sách và quyền riêng tư.
- **Kết nối nền tảng Agent khác.** AstrBot tích hợp được Dify, Alibaba Cloud Bailian và Coze. Nếu đã dựng quy trình ở đó, bạn có thể đưa nó ra kênh chat.
- **Plugin.** Hơn 1000 plugin cài một chạm. Cần thêm chức năng thì thường đã có người làm.
- **Agent Sandbox.** Môi trường cô lập để chạy code và lệnh shell an toàn, tái sử dụng tài nguyên theo phiên. Bot có thể chạy code mà không đụng vào máy thật của bạn. Chi tiết xem tài liệu chính thức của dự án.
- **WebUI và Web ChatUI.** Bạn cấu hình bằng giao diện web. ChatUI có sẵn sandbox và tìm kiếm web. Giao diện có hỗ trợ đa ngôn ngữ (i18n).

## Cần chuẩn bị gì

Theo tư liệu, bạn cần:

- **Python 3.12 trở lên.** File pyproject.toml yêu cầu Python >=3.12. Lệnh cài bằng uv ở dưới tự chỉ định Python 3.12.
- **uv** nếu chọn cách cài nhanh. README ghi rõ phải cài uv trước. README không hướng dẫn cách cài uv, bạn xem trang tài liệu chính thức của uv.
- **Một mô hình AI để bot trả lời.** Có thể là tài khoản và API key của nhà cung cấp (OpenAI, Gemini, DeepSeek…) hoặc mô hình tự chạy như Ollama. README không nói cần bao nhiêu RAM hay có cần GPU không, nên phần này chưa có thông tin.
- **Tài khoản trên nền tảng chat bạn muốn nối**, ví dụ bot Telegram hay Discord. README không hướng dẫn từng nền tảng, bạn xem tài liệu tại astrbot.app.
- **Docker** nếu chọn cách triển khai bằng container.
- Người dùng macOS: lần đầu chạy lệnh astrbot có thể lâu khoảng 10–20 giây do kiểm tra bảo mật của macOS. Đây là chuyện bình thường.

README không nêu rõ hệ điều hành nào được hỗ trợ cho cách cài bằng uv, ngoài lưu ý cho macOS. Windows có chạy được không, bạn nên kiểm tra thêm trong tài liệu chính thức.

## Cài đặt từng bước

```steps
- Cài uv | Chuẩn bị công cụ uv theo trang chính thức của uv
- Cài AstrBot | Chạy uv tool install astrbot --python 3.12
- Khởi tạo | Chạy astrbot init, chỉ làm lần đầu
- Chạy bot | Chạy astrbot run rồi mở WebUI để cấu hình
```

README đưa ra nhiều cách triển khai. Mình hướng dẫn cách nhanh nhất (uv), rồi nói ngắn về các cách còn lại.

### Cài uv

README yêu cầu có uv trước. README không ghi lệnh cài uv, nên mình không chép bừa. Bạn vào trang tài liệu của uv (docs.astral.sh/uv) và làm theo hướng dẫn cho hệ điều hành của bạn. Cài xong, mở một cửa sổ terminal mới (trên Windows là PowerShell) rồi gõ lệnh sau để xem uv đã nhận chưa:

```bash
uv --version
```

Nếu thấy số phiên bản là ổn. Nếu báo không tìm thấy lệnh, hãy đóng terminal và mở lại.

### Cài AstrBot bằng uv

Lệnh dưới cài AstrBot như một công cụ dòng lệnh độc lập, dùng Python 3.12. Bạn chạy ở terminal nào cũng được, không cần vào thư mục cụ thể.

```bash
uv tool install astrbot --python 3.12
```

### 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. README nhấn mạnh không cần chạy lại những lần sau.

```bash
astrbot init
```

### Chạy AstrBot

```bash
astrbot run
```

Sau khi chạy, bạn mở WebUI để thêm nhà cung cấp mô hình và nền tảng chat. README không ghi địa chỉ truy cập hay tài khoản mặc định, bạn hãy đọc dòng thông báo trên terminal và xem tài liệu tại astrbot.app. Terminal cần giữ mở trong lúc bot chạy; đóng terminal là bot dừng.

Muốn cập nhật bản mới, dùng lệnh:

```bash
uv tool upgrade astrbot --python 3.12
```

### Các cách triển khai khác

- **Docker / Docker Compose:** README khuyên dùng nếu bạn quen container và cần bản ổn định cho môi trường thật. Repo có sẵn Dockerfile và compose.yml, nhưng README chưa ghi lệnh cụ thể, mà trỏ sang tài liệu "Deploy AstrBot with Docker" trên docs.astrbot.app. Bạn làm theo trang đó.
- **Ứng dụng desktop (AstrBot-desktop):** dành cho người chủ yếu dùng ChatUI trên máy cá nhân. README nói không khuyến nghị cho máy chủ.
- **AstrBot Launcher:** cho người dùng desktop muốn triển khai nhanh và chạy nhiều bản riêng biệt.
- **Dịch vụ đám mây một chạm (RainYun):** cho người muốn bot online 24 giờ mà không tự quản máy chủ.
- **Bảng điều khiển BT-Panel, 1Panel, CasaOS, hoặc cài từ mã nguồn:** có trang hướng dẫn riêng trên docs.astrbot.app.

```note
API key của nhà cung cấp mô hình (OpenAI, Gemini…) giống mật khẩu. Đừng dán vào nhóm chat, đừng đưa lên GitHub. Nhiều nhà cung cấp tính tiền theo lượng dùng, nên hãy đặt hạn mức chi tiêu trước khi cho cả nhóm dùng bot.
```

## Kiểm tra đã chạy được chưa

Theo README, dấu hiệu chạy được là lệnh astrbot run khởi động mà terminal không báo lỗi, và bạn mở được WebUI. README không mô tả chính xác màn hình hay địa chỉ, nên bạn đối chiếu với thông tin in ra trên terminal.

Cách kiểm tra thực tế:

1. Mở WebUI, thêm một nhà cung cấp mô hình bằng API key của bạn.
2. Dùng Web ChatUI có sẵn để gõ thử một câu hỏi. Nếu bot trả lời là phần AI đã thông.
3. Rồi mới nối nền tảng chat (ví dụ Telegram) và nhắn thử từ điện thoại.

Tách thành hai bước như vậy giúp bạn biết lỗi nằm ở mô hình hay ở kênh chat.

## Dùng vào việc thật

Các tình huống dưới đây bám vào những gì README mô tả. Cách bấm cụ thể trong WebUI bạn xem tài liệu chính thức.

### Chủ shop làm trợ lý trả lời khách trên kênh chat

Bạn bán hàng online và hay bị hỏi đi hỏi lại về giá, chính sách đổi trả, giờ mở cửa. Bạn cài AstrBot, nối với Telegram hoặc Slack và cấu hình một nhân vật (persona), ví dụ "nhân viên tư vấn lịch sự, trả lời ngắn". Rồi thêm tài liệu chính sách vào cơ sở tri thức để bot dựa vào đó.

Prompt mẫu để đặt persona:

```
Bạn là nhân viên tư vấn của cửa hàng. Chỉ trả lời dựa trên tài liệu chính sách đã cung cấp. Nếu không chắc, hãy nói sẽ chuyển cho nhân viên thật.
```

Kết quả: các câu hỏi lặp lại được bot trả lời trước, bạn chỉ xử lý những ca khó. Hãy tự đọc thử các câu trả lời trước khi cho khách dùng thật.

### Nhân viên văn phòng đưa AI vào nhóm chat công ty

Công ty bạn dùng Feishu, DingTalk hoặc Slack. Bạn nối AstrBot vào nhóm để đồng nghiệp hỏi nhanh: soạn email, tóm tắt nội dung dán vào, dịch đoạn văn. Mỗi người không cần tự đăng ký công cụ AI riêng.

> Điểm hay nhất của AstrBot là bạn dựng bot một lần, rồi cả nhóm dùng ngay trong ứng dụng chat quen thuộc.
>
> — Ông T

Kết quả: AI trở thành một thành viên trong nhóm. Vì mọi câu hỏi đi qua cùng một API key, bạn nên theo dõi chi phí và nhắc mọi người không dán dữ liệu nhạy cảm.

### Người quan tâm quyền riêng tư dùng mô hình tự chạy

Bạn không muốn gửi nội dung ra dịch vụ đám mây. README ghi AstrBot hỗ trợ Ollama và LM Studio, hai công cụ chạy mô hình ngay trên máy bạn. Bạn cài một trong hai, rồi khai báo nó làm nhà cung cấp trong WebUI và dùng bot như bình thường.

Kết quả: nội dung hội thoại ở lại trong máy của bạn. Chất lượng và tốc độ phụ thuộc cấu hình máy; README chưa có thông tin về yêu cầu phần cứng.

### Lập trình viên mới mở rộng bot bằng plugin và MCP

Bạn biết chút Python và muốn bot làm thêm việc: tra cứu, gọi một dịch vụ, chạy code thử. Bạn vào phần plugin cài thử một plugin có sẵn trước khi tự viết. Với việc chạy code, bạn bật Agent Sandbox để code chạy trong môi trường cô lập. Nếu cần nối công cụ ngoài, README cho biết AstrBot hỗ trợ MCP và Skills.

Kết quả: bot đi từ "chỉ trả lời" sang "làm được việc". Với repo đóng góp mã, README gợi ý dùng ruff và pre-commit; hãy thảo luận qua Issue trước khi thêm tính năng lớn.

## Lỗi hay gặp và cách xử lý

**1. Lệnh astrbot hoặc uv báo "không tìm thấy lệnh".**
Thường do terminal chưa nhận đường dẫn mới sau khi cài uv. Hãy đóng terminal, mở lại rồi thử lệnh phiên bản của uv. Nếu vẫn lỗi, xem lại hướng dẫn cài uv chính thức.

**2. Lần đầu chạy trên macOS rất chậm.**
README đã nói trước: lần chạy đầu có thể mất khoảng 10–20 giây do kiểm tra bảo mật. Cứ chờ, đừng bấm hủy.

**3. Bot không trả lời.**
Các nguyên nhân hay gặp: chưa khai báo nhà cung cấp mô hình, API key sai hoặc hết hạn mức, hoặc chưa nối đúng nền tảng chat. Hãy thử trước trong Web ChatUI. Nếu ở đó bot trả lời được, lỗi nằm ở phần kết nối kênh chat.

**4. Chạy astrbot init nhiều lần.**
README dặn lệnh này chỉ chạy lần đầu. Những lần sau chỉ cần astrbot run. Nếu bạn muốn khởi tạo lại, hãy sao lưu dữ liệu cũ trước.

**5. Python không đúng phiên bản khi cài từ mã nguồn.**
repo yêu cầu Python 3.12 trở lên. Nếu cài theo kiểu mã nguồn mà máy bạn có Python cũ, hãy dùng cách uv ở trên, vì lệnh đã chỉ định Python 3.12.

## Có nên dùng không

**Điểm mạnh:**
- Miễn phí, mã nguồn mở, cài nhanh bằng ba lệnh.
- Hỗ trợ rất nhiều nền tảng chat và nhà cung cấp mô hình, gồm cả mô hình tự chạy.
- Có WebUI, plugin phong phú, sandbox cho việc chạy code.
- Dự án đông người dùng và vẫn được cập nhật.

**Giới hạn cần biết:**
- Phần lớn tài liệu và cộng đồng bằng tiếng Trung hoặc tiếng Anh; README có thêm bản Pháp, Nhật, Tây Ban Nha, Nga. Chưa thấy bản tiếng Việt.
- Nhiều nền tảng được liệt kê (QQ, WeCom, DingTalk…) phổ biến ở Trung Quốc hơn ở Việt Nam. Với nhu cầu của bạn, hãy kiểm tra nền tảng bạn dùng có trong danh sách (Telegram, Discord, Slack thì có).
- Giấy phép AGPL-3.0 có ràng buộc nếu bạn sửa mã và cung cấp dịch vụ ra ngoài.
- Bạn vẫn phải tự lo API key, chi phí mô hình và việc vận hành máy chạy bot. README chưa có thông tin về yêu cầu cấu hình máy.

**Khi nào nên chọn cách khác:** nếu chỉ cần hỏi đáp AI 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 không muốn tự quản máy chủ, README gợi ý dịch vụ triển khai đám mây hoặc bản desktop. Còn nếu cần một bot chạy ổn định nhiều kênh, có plugin và agent, AstrBot là lựa chọn đáng thử.

## Câu hỏi thường gặp

### AstrBot có miễn phí không?

Có. README ghi đây là dự án miễn phí và mã nguồn mở, 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 (qua API key) hoặc cho máy chủ nếu thuê.

### AstrBot cần GPU không?

README không nêu yêu cầu GPU hay RAM. Nếu bạn dùng mô hình qua API của nhà cung cấp thì phần nặng nằm ở phía họ. Nếu muốn tự chạy mô hình bằng Ollama hay LM Studio thì cấu hình phụ thuộc mô hình bạn chọn, tư liệu chưa có thông tin cụ thể.

### AstrBot chạy được trên Windows không?

README không nói rõ hệ điều hành hỗ trợ cho cách cài bằng uv, chỉ có lưu ý riêng cho macOS. Bạn có thể xem thêm tài liệu tại astrbot.app, hoặc dùng cách Docker và ứng dụng desktop mà README đề cập.

### AstrBot khác gì việc dùng ChatGPT hay Gemini trực tiếp?

AstrBot không phải một mô hình AI mà là lớp nền tảng nối mô hình vào ứng dụng chat như Telegram, Discord, Slack. Nó thêm persona, cơ sở tri thức, plugin, MCP và sandbox. Phù hợp khi bạn muốn bot chạy trong kênh chat của nhóm thay vì mở từng ứng dụng AI riêng.

### Dữ liệu chat có an toàn không?

README không có phần riêng về bảo mật dữ liệu. Bạn tự triển khai nên dữ liệu nằm ở máy của bạn, nhưng nội dung gửi tới nhà cung cấp mô hình đám mây sẽ đi qua họ. Muốn giữ trong máy, README cho biết có thể dùng Ollama hoặc LM Studio.

### Muốn bot chạy 24/7 thì làm thế nào?

README gợi ý dịch vụ triển khai đám mây một chạm của RainYun cho người không muốn tự quản máy chủ. Ngoài ra bạn có thể triển khai bằng Docker trên máy chủ riêng, hoặc dùng các bảng điều khiển như BT-Panel, 1Panel, CasaOS có tài liệu hướng dẫn riêng.

### Cài AstrBot có khó không?

Với người quen dòng lệnh thì khá dễ: sau khi có uv, chỉ cần ba lệnh gồm cài đặt, init và run. Nếu chưa quen terminal, README có thêm bản ứng dụng desktop và AstrBot Launcher dành cho người dùng máy cá nhân.
