# AstrBot: dựng chatbot AI trong Telegram, Slack, Discord… — hướng dẫn cài đặt và dùng

> AstrBot là nền tảng chatbot và trợ lý AI (Agent) mã nguồn mở viết bằng Python, giúp bạn đưa mô hình ngôn ngữ vào các ứng dụng chat như Telegram, Slack, Discord. Có sẵn giao diện web để quản lý, hỗ trợ plugin, MCP, Skills và cơ sở tri thức. Cài bằng ba lệnh với uv hoặc chạy bằng Docker, người mới làm theo được nhưng cần quen dòng lệnh cơ bản.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-28 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/astrbot-chatbot-ai-agent-telegram-slack-discord-huong-dan

AstrBot là một nền tảng chatbot AI mã nguồn mở, viết bằng Python, giúp bạn đưa mô hình ngôn ngữ (LLM) vào thẳng các ứng dụng nhắn tin như Telegram, Slack, Discord, Feishu, DingTalk… Tác giả mô tả nó là một "trợ lý AI kiêm framework phát triển", có thể làm phương án thay thế cho openclaw. Hiện repo có khoảng 46.781 sao và 3.538 fork, và vẫn được cập nhật trong 3 tháng gần đây.

Vấn đề nó giải quyết khá đời thường. Bạn muốn một con bot trả lời khách, một trợ lý trong nhóm chat của công ty, hoặc một "người bạn AI" riêng. Nhưng bạn không muốn tự viết code nối từng nền tảng chat với từng hãng AI. AstrBot đã làm sẵn phần nối đó. Bạn chỉ cần chọn nền tảng chat, chọn mô hình, rồi chỉnh qua giao diện web.

Ai nên dùng? Chủ shop hoặc nhóm nhỏ muốn có bot chăm sóc khách, nhân viên văn phòng muốn trợ lý AI trong kênh chat nội bộ, lập trình viên mới muốn một khung có sẵn để thử Agent, MCP và plugin. Điểm đáng giá nhất là sự gọn: một ứng dụng quản lý được nhiều nền tảng chat, nhiều nhà cung cấp mô hình, và có kho plugin lớn (README nói hơn 1000 plugin cài một cú nhấp).

```repo
- repo | AstrBotDevs/AstrBot
- kind | Framework
- desc | AstrBot là nền tảng chatbot AI mã nguồn mở, nối các mô hình ngôn ngữ với Telegram, Slack, Discord, Feishu… kèm plugin, MCP, Skills và tri thức riêng.
- 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 theo README, kèm lợi ích thực tế.

### Trò chuyện với mô hình ngôn ngữ, có Agent và MCP

AstrBot hỗ trợ hội thoại AI, đa phương thức, Agent, MCP, Skills, cơ sở tri thức, thiết lập nhân vật (persona) và tự nén ngữ cảnh. Nói đơn giản: bạn đặt cho bot một "tính cách", nạp tài liệu riêng của mình vào cơ sở tri thức, và khi cuộc trò chuyện dài ra thì hệ thống tự nén bớt để không quá tải.

### Nhiều nền tảng chat trong một chỗ

README liệt kê các nền tảng do nhóm chính thức duy trì: QQ, giao thức OneBot v11, Telegram, Wecom và Wecom AI Bot, WeChat Official Accounts, Feishu (Lark), DingTalk, Slack, Discord, LINE, Satori, KOOK, Misskey, Mattermost. WhatsApp đang ghi là "sắp có". Ngoài ra có thêm Matrix, Rocket.Chat, VoceChat do cộng đồng làm qua plugin. Với người dùng Việt, các lựa chọn dễ thử nhất thường là Telegram, Discord hoặc Slack.

### Dùng được nhiều nhà cung cấp mô hình

Bạn không bị khoá vào một hãng. Danh sách hỗ trợ gồm 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 như Ollama và LM Studio. Có cả các cổng API tổng hợp và vài dịch vụ khác. Nếu bạn đã có key của một hãng thì dùng luôn, còn muốn không gửi dữ liệu ra ngoài thì có thể trỏ tới Ollama hoặc LM Studio chạy trên máy mình.

### Kết nối nền tảng Agent bên ngoài

AstrBot nối được với Dify, Alibaba Cloud Bailian và Coze. Nếu công ty bạn đã dựng quy trình AI trên các nền tảng này, bạn có thể đưa chúng ra các kênh chat mà không cần viết lại.

### Giọng nói

README có danh sách dịch vụ chuyển giọng nói thành chữ (như OpenAI Whisper, SenseVoice) và chữ thành giọng nói (như OpenAI TTS, Gemini TTS, FishAudio, Edge TTS, Azure TTS). Hữu ích khi bạn muốn bot nghe tin nhắn thoại hoặc trả lời bằng giọng.

### Hộp cát cho Agent (Agent Sandbox)

Đây là điểm đáng chú ý về an toàn. Khi Agent cần chạy code hay lệnh shell, AstrBot có hộp cát cách ly để việc đó diễn ra trong môi trường riêng, không đụng thẳng vào máy của bạn. README cũng nói giao diện Web ChatUI có sẵn hộp cát và tìm kiếm web.

### Giao diện web và đa ngôn ngữ

Có WebUI để quản lý và Web ChatUI để trò chuyện ngay trên trình duyệt. Dự án hỗ trợ đa ngôn ngữ (i18n). README có bản tiếng Trung, Nhật, Pháp, Tây Ban Nha, Nga và Anh. README chưa nhắc tiếng Việt.

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

Chỉ những gì tư liệu nói:

- Python từ 3.12 trở lên (file pyproject.toml yêu cầu `>=3.12`). Lệnh cài bằng uv cũng chỉ định rõ `--python 3.12`.
- Công cụ uv nếu bạn chọn cách cài "một cú" (README ghi rõ cần cài uv trước).
- Docker hoặc Docker Compose nếu bạn chọn cách chạy bằng container. Repo có sẵn Dockerfile và compose.yml.
- Một nguồn mô hình AI: key API của nhà cung cấp bạn chọn, hoặc một mô hình tự chạy như Ollama / LM Studio. README không nói cần phần cứng cụ thể nào cho chính AstrBot, nên chưa có thông tin về cấu hình tối thiểu.
- Tài khoản/bot trên nền tảng chat bạn muốn nối (ví dụ một bot Telegram). Cách tạo và điền thông tin nằm trong tài liệu chính thức của dự án.
- Với macOS: lần chạy đầu của lệnh `astrbot` có thể chậm khoảng 10–20 giây do kiểm tra bảo mật của hệ điều hành.

README không nêu rõ danh sách hệ điều hành được hỗ trợ cho cách cài bằng uv. Bản desktop và bản Launcher được giới thiệu cho người dùng máy tính cá nhân.

```note
Key API là thứ nhạy cảm. Đừng dán key vào tin nhắn nhóm, ảnh chụp màn hình hay repo công khai. Gọi mô hình thường tính phí theo lượng dùng ở phía nhà cung cấp, nên hãy đặt hạn mức chi tiêu trên tài khoản của hãng AI trước khi mở bot cho nhiều người dùng.
```

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

README đưa ra nhiều cách: cài nhanh bằng uv, Docker, ứng dụng desktop, Launcher, hoặc các bảng điều khiển như BT-Panel, 1Panel, CasaOS. Bài này đi theo cách uv vì ngắn nhất, rồi nói qua các cách còn lại.

```steps
- Cài uv | Chuẩn bị công cụ quản lý môi trường Python mà README yêu cầu
- Cài AstrBot | Dùng uv tool install để cài gói astrbot với Python 3.12
- Khởi tạo | Chạy astrbot init một lần duy nhất ở lần đầu
- Chạy bot | Dùng astrbot run để khởi động
- Cấu hình | Mở giao diện quản lý, thêm mô hình và nền tảng chat theo tài liệu
```

### Cài uv

README ghi rõ cần có uv trước. README không kèm lệnh cài uv, nên bạn xem hướng dẫn trên trang chính thức của uv (docs.astral.sh/uv) rồi làm theo cho đúng hệ điều hành của mình. Sau khi cài xong, hãy mở một cửa sổ terminal mới (PowerShell trên Windows, Terminal trên macOS) để máy nhận lệnh `uv`.

### Cài AstrBot

Gõ lệnh sau vào terminal. Lệnh này cài AstrBot như một công cụ dòng lệnh riêng, dùng Python 3.12:

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

Người mới hay vấp ở chỗ: lệnh này không cần bạn đứng trong thư mục nào cả, không cần tải code về trước. Nếu báo không tìm thấy `uv`, nghĩa là bước cài uv chưa xong hoặc terminal chưa được mở lại.

### Khởi tạo môi trường

Lần đầu tiên, chạy lệnh khởi tạo. README nhấn mạnh chỉ làm một lần:

```bash
astrbot init
```

Đừng chạy lại lệnh này mỗi lần bật bot. Nó dùng để dựng môi trường ban đầu.

### Chạy AstrBot

```bash
astrbot run
```

Terminal sẽ giữ lệnh này chạy, nên đừng đóng cửa sổ trong lúc dùng. Trên macOS, lần đầu có thể chờ 10–20 giây. README chưa ghi địa chỉ truy cập giao diện web, nên khi bot khởi động xong, bạn hãy đọc dòng thông báo trong terminal và xem thêm tài liệu tại trang chủ dự án (astrbot.app).

### Cập nhật khi có bản mới

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

### Cách khác: Docker

Nếu bạn quen container và muốn chạy ổn định lâu dài, README khuyên dùng Docker / Docker Compose. Repo có sẵn Dockerfile và compose.yml, nhưng README không chép lệnh cụ thể mà trỏ sang tài liệu "Deploy AstrBot with Docker" trên trang docs của dự án. Bạn nên làm theo đúng trang đó thay vì tự đoán lệnh.

### Cách khác: ứng dụng desktop, Launcher, bảng điều khiển

Nếu bạn chủ yếu muốn dùng ChatUI trên máy tính cá nhân, README gợi ý ứng dụng AstrBot-desktop (repo riêng của cùng nhóm tác giả), không khuyên dùng cho máy chủ. Nếu muốn cài nhanh và chạy nhiều bản tách biệt, có AstrBot Launcher. Còn nếu bạn thích quản lý qua bảng điều khiển, có hướng dẫn cho BT-Panel, 1Panel, CasaOS và cài từ mã nguồn trong tài liệu chính thức.

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

README không mô tả cụ thể màn hình thành công, nên mình chỉ nêu những dấu hiệu hợp lý bạn có thể tự kiểm tra:

- Lệnh `astrbot run` chạy mà không báo lỗi đỏ và không thoát ngay. Terminal vẫn "treo" và in log là bình thường.
- Bạn mở được giao diện web quản lý (WebUI) theo địa chỉ mà log hoặc tài liệu chỉ dẫn.
- Trong Web ChatUI, bạn gõ một câu và nhận được câu trả lời từ mô hình đã cấu hình.
- Sau khi nối nền tảng chat (ví dụ Telegram), bạn nhắn thử cho bot và thấy nó phản hồi.

Nếu mọi thứ chạy mà bot không trả lời, nhiều khả năng bạn chưa cấu hình mô hình hoặc key. Xem phần lỗi hay gặp bên dưới.

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

Các tình huống dưới đây bám theo khả năng README nêu. Chi tiết cách bấm trong giao diện, bạn xem tài liệu chính thức, vì README không mô tả từng màn hình.

### Chủ shop nhỏ: bot trả lời khách trên Telegram hoặc Discord

Bối cảnh: bạn bán đồ handmade, khách hay hỏi cùng một số câu như giá, thời gian giao, cách đổi trả. Bạn cài AstrBot, nối với một bot trên nền tảng khách đang dùng, chọn một mô hình (ví dụ DeepSeek, Gemini hoặc OpenAI), rồi đặt persona kiểu "nhân viên tư vấn thân thiện, trả lời ngắn". Sau đó bạn nạp bảng giá và chính sách đổi trả vào cơ sở tri thức.

Prompt mẫu để đặt vai trò (dán vào phần thiết lập nhân vật):

```text
Bạn là nhân viên tư vấn của shop. Trả lời ngắn, lịch sự, bằng tiếng Việt. Chỉ dùng thông tin trong tài liệu của shop. Nếu không chắc, hãy nói sẽ nhờ chủ shop liên hệ lại.
```

Kết quả: khách nhắn là có trả lời ngay, còn những câu bot không chắc thì bạn xử lý tay. Nhớ kiểm tra bot trên vài câu hỏi thử trước khi mở cho khách thật.

### Nhân viên văn phòng: trợ lý AI trong kênh chat nội bộ

Bối cảnh: công ty dùng Slack hoặc Feishu. Bạn muốn một trợ lý để mọi người hỏi nhanh về quy trình, mẫu biểu, hay nhờ viết lại email. Bạn nối AstrBot vào kênh chat, nạp tài liệu nội bộ vào cơ sở tri thức và đặt persona là trợ lý hành chính.

> Một con bot nằm sẵn trong kênh chat mọi người đang dùng sẽ được dùng nhiều hơn mười công cụ AI phải mở riêng.
>
> — Ông T

Kết quả: đồng nghiệp hỏi ngay trong kênh quen thuộc, không phải mở thêm ứng dụng nào. Nếu tài liệu nội bộ nhạy cảm, hãy cân nhắc dùng mô hình tự chạy (Ollama, LM Studio) để dữ liệu không rời khỏi máy công ty.

### Lập trình viên mới: thử Agent, MCP và plugin

Bối cảnh: bạn đang học làm ứng dụng AI và muốn xem một Agent chạy thật trông như thế nào. AstrBot cho bạn một khung có sẵn: bật MCP để bot gọi công cụ bên ngoài, cài plugin từ kho cộng đồng, và dùng Web ChatUI để thử mà không cần nối nền tảng chat nào.

Bạn có thể thử các việc như nhờ bot tìm kiếm web trong ChatUI, hoặc nhờ Agent chạy một đoạn code ngắn trong hộp cát. README nói hộp cát dành cho việc chạy code và lệnh shell cách ly, nên đây là nơi an toàn hơn để thử so với chạy thẳng trên máy.

Kết quả: bạn hiểu được luồng "tin nhắn → mô hình → công cụ → trả lời" bằng một sản phẩm thật, thay vì chỉ đọc lý thuyết. Nếu muốn đóng góp code, README hướng dẫn clone repo, cài pre-commit và dùng ruff để kiểm tra định dạng.

### Nhóm đã có quy trình AI trên Dify hoặc Coze

Bối cảnh: nhóm bạn đã dựng sẵn một ứng dụng trên Dify, Coze hoặc Alibaba Cloud Bailian nhưng khách và đồng nghiệp lại ở trên Telegram, Slack hay Discord. Bạn dùng AstrBot làm cầu nối: đưa ứng dụng đó ra các kênh chat bằng tính năng kết nối nền tảng Agent.

Kết quả: không phải viết lại quy trình, chỉ cần cấu hình kết nối. README không nêu chi tiết từng bước nên bạn xem mục tương ứng trong tài liệu chính thức.

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

README không có mục xử lý sự cố. Dưới đây là những lỗi rất dễ gặp với loại công cụ này, kèm cách xử lý an toàn.

### Lệnh `uv` hoặc `astrbot` báo không tìm thấy

Nguyên nhân thường là uv chưa cài xong, hoặc terminal chưa nhận đường dẫn mới. Hãy đóng terminal, mở cửa sổ mới rồi thử lại. Nếu vẫn lỗi, xem lại hướng dẫn cài uv trên trang chính thức của uv và đảm bảo bạn không đang ở phiên terminal cũ.

### Báo sai phiên bản Python

AstrBot yêu cầu Python từ 3.12 trở lên. Lệnh cài trong README đã có `--python 3.12` để uv tự dùng đúng phiên bản. Bạn hãy chép đúng nguyên lệnh, đừng bỏ phần cờ đó. Nếu đang cài từ mã nguồn bằng cách khác, kiểm tra lại phiên bản Python đang dùng.

### Chạy rồi nhưng bot không trả lời

Hay gặp nhất là chưa thêm nhà cung cấp mô hình, điền sai key, hoặc hết hạn mức ở phía hãng AI. Hãy thử nhắn ở Web ChatUI trước để loại trừ lỗi từ nền tảng chat. Nếu ChatUI trả lời được mà Telegram hay Slack không, vấn đề nằm ở phần cấu hình kết nối nền tảng đó (token bot, quyền của bot trong nhóm). Xem log trong terminal để biết lỗi cụ thể.

### Chạy `astrbot init` lại làm hỏng dữ liệu cũ

README dặn chỉ chạy `astrbot init` ở lần đầu. Mình không có thông tin về việc chạy lại sẽ làm gì với dữ liệu hiện có, nên cách an toàn là đừng chạy lại, và sao lưu thư mục dữ liệu trước khi thử bất cứ thao tác nào chưa chắc chắn.

### Dữ liệu và key bị lộ khi mở bot cho nhiều người

Đây là rủi ro về cách dùng, không phải lỗi phần mềm. Đừng đưa dữ liệu nhạy cảm vào cơ sở tri thức của bot công khai. Giữ key trong phần cấu hình, không dán vào kênh chat. Nếu bật khả năng chạy code cho Agent, hãy dùng hộp cát mà README nhắc tới thay vì cho chạy thẳng trên máy chính.

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

Điểm mạnh:

- Miễn phí và mã nguồn mở. Bạn không trả tiền cho phần mềm, chỉ trả cho dịch vụ mô hình nếu dùng bản trả phí.
- Một nơi quản lý nhiều nền tảng chat và nhiều nhà cung cấp mô hình.
- Có sẵn cơ sở tri thức, persona, MCP, Skills, plugin và hộp cát cách ly.
- Cài nhanh chỉ với ba lệnh nếu bạn đã có uv. Có cả Docker, desktop, Launcher cho từng nhu cầu.
- Dự án còn hoạt động và có cộng đồng lớn.

Giới hạn cần biết:

- Giấy phép là AGPL-3.0. Nếu bạn định dùng AstrBot trong sản phẩm thương mại hoặc phân phối lại bản sửa đổi, hãy đọc kỹ điều khoản này, đặc biệt là yêu cầu khi cung cấp dịch vụ qua mạng.
- Tài liệu gốc chủ yếu bằng tiếng Trung và tiếng Anh. README chưa có bản tiếng Việt, nên người mới có thể phải đọc docs bằng bản dịch.
- README không ghi cấu hình phần cứng tối thiểu và không mô tả chi tiết các màn hình cấu hình, nên bạn sẽ phải đọc thêm tài liệu chính thức.
- Nhiều nền tảng trong danh sách (QQ, Wecom, KOOK…) ít phổ biến ở Việt Nam. Phần lớn người đọc sẽ dùng Telegram, Discord hoặc Slack.

Khi nào nên chọn cách khác? Nếu bạn chỉ cần hỏi đáp với AI trên một ứng dụng sẵn có, một công cụ chat thông thường là đủ. Nếu bạn cần giải pháp có cam kết hỗ trợ doanh nghiệp, hãy cân nhắc dịch vụ thương mại. Còn nếu bạn muốn tự làm chủ bot, nối nhiều kênh chat và thử các khả năng Agent mà không viết nhiều code, AstrBot là lựa chọn đáng thử.

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

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

README ghi rõ đây là dự án miễn phí và mã nguồn mở, giấy phép AGPL-3.0. Tuy nhiên, nếu bạn dùng mô hình của nhà cung cấp trả phí (như OpenAI hay Anthropic), bạn vẫn trả phí gọi API cho họ. Dùng mô hình tự chạy như Ollama hay LM Studio thì tránh được khoản này.

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

Nếu đã có uv, README chỉ cần ba lệnh: uv tool install astrbot --python 3.12, astrbot init (chỉ lần đầu) và astrbot run. Ngoài ra có Docker, ứng dụng desktop và Launcher cho những ai thích cách khác. Phần cấu hình mô hình và nền tảng chat cần đọc thêm tài liệu chính thức.

### AstrBot cần phiên bản Python nào, có cần GPU không?

File pyproject.toml yêu cầu Python 3.12 trở lên. README không nói AstrBot cần GPU. Nếu bạn muốn tự chạy mô hình trên máy qua Ollama hay LM Studio thì yêu cầu phần cứng phụ thuộc vào mô hình đó. Về cấu hình tối thiểu của chính AstrBot thì tư liệu chưa có thông tin.

### AstrBot kết nối được với những ứng dụng chat nào?

Theo README, các 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, Mattermost. WhatsApp được ghi là sắp có. Cộng đồng còn có plugin cho Matrix, Rocket.Chat và VoceChat.

### Dùng được với những mô hình AI nào?

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 mô hình tự chạy Ollama và LM Studio. Ngoài ra có các cổng API tổng hợp và nền tảng như Dify, Alibaba Cloud Bailian, Coze. Có cả dịch vụ chuyển giọng nói thành chữ và ngược lại.

### Dữ liệu của tôi có an toàn không?

README không có phần nói riêng về quyền riêng tư dữ liệu, nên chưa có thông tin chính thức ở mức chi tiết. Điều README nêu là hộp cát Agent để chạy code và lệnh shell trong môi trường cách ly. Nếu cần dữ liệu không rời khỏi máy, bạn có thể dùng mô hình tự chạy như Ollama hoặc LM Studio.

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

README không liệt kê cụ thể hệ điều hành cho cách cài bằng uv, chỉ có ghi chú riêng cho macOS. Dự án có bản desktop dành cho máy tính cá nhân và có Docker. Bạn nên xem tài liệu chính thức tại trang chủ dự án để biết chắc cách phù hợp với Windows.
