OpenMAIC: biến chủ đề hoặc tài liệu thành lớp học AI tương tác — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
OpenMAIC (Open Multi-Agent Interactive Classroom) là nền tảng mã nguồn mở, giấy phép MIT, tạo lớp học tương tác từ một chủ đề hoặc tài liệu: slide, quiz, mô phỏng, bảng trắng, giọng đọc. Bạn chạy nó trên máy mình bằng Node.js, pnpm và PostgreSQL, hoặc bằng Docker Compose. Cài không quá khó nhưng cần một API key của dịch vụ AI và một chút quen terminal.
OpenMAIC (Open Multi-Agent Interactive Classroom) là một nền tảng mã nguồn mở, viết bằng TypeScript, giúp bạn biến một chủ đề hoặc một bộ tài liệu thành cả một lớp học tương tác. Bạn gõ chủ đề hoặc đính kèm tài liệu, AI dựng bài giảng gồm slide, câu hỏi trắc nghiệm, mô phỏng tương tác và hoạt động học theo dự án. Giáo viên AI và bạn học AI sẽ giảng, vẽ lên bảng trắng và thảo luận với bạn.
Repo này hợp với giáo viên, người làm đào tạo nội bộ, chủ trung tâm dạy học, và cả lập trình viên mới muốn xem một hệ thống nhiều tác tử (multi-agent) chạy thật trông ra sao. Nếu bạn hay phải soạn bài giảng, tài liệu onboarding hay khoá học ngắn thì đây là công cụ đáng thử. Repo hiện có khoảng 43.400 sao và 6.700 fork, giấy phép MIT, vẫn được cập nhật đều.
Điểm đáng giá nhất là bạn không chỉ nhận một file slide. Bạn nhận một buổi học có người giảng, có bài tập, có thảo luận. Kết quả xuất được ra file .pptx, một file .html chạy offline, hoặc gói ZIP để chuyển sang nơi khác.
THU-MAIC/OpenMAIC
OpenMAIC là nền tảng mã nguồn mở biến một chủ đề hoặc tài liệu thành bài học có slide, quiz, mô phỏng, do giáo viên AI và bạn học AI cùng giảng.
I.OpenMAIC làm được gì
- Tạo bài học bằng một lần bấm. Bạn mô tả chủ đề hoặc đính kèm tài liệu, AI dựng trọn bài học trong vài phút. Bạn đỡ phải ngồi dàn ý, làm slide từng trang.
- Lớp học nhiều tác tử. Giáo viên AI và bạn học AI cùng giảng, hỏi, thảo luận với bạn theo thời gian thực. Học một mình mà vẫn có cảm giác lớp học.
- Nhiều loại cảnh học. Slide, quiz, mô phỏng HTML tương tác và học theo dự án (PBL). Cùng một chủ đề có thể học bằng nhiều cách.
- Bảng trắng và giọng nói. Các tác tử vẽ sơ đồ, viết công thức và giải thích thành tiếng.
- Xuất ra nhiều dạng. File
.pptxgiữ đủ các cảnh, một file.htmloffline phát được cả bài, hoặc ZIP lớp học để chuyển sang bản triển khai khác. Bạn dễ đem bài đi dạy ở nơi không có mạng. - Chọn nhiều nhà cung cấp AI. README liệt kê OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok, OpenRouter, Ollama và nhiều dịch vụ khác, kể cả API tương thích OpenAI. Bạn không bị khoá vào một hãng.
- Chạy được từ ứng dụng nhắn tin hoặc IDE. OpenMAIC Skill đi kèm hoạt động với OpenClaw và một số agent workbench như Codex, DeepSeek, WorkBuddy. README nói bạn có thể tạo lớp học từ Feishu, Slack, Telegram hoặc ngay trong IDE.
- Tạo khoá học chạy phía server. Từ bản 1.2.0, việc sinh khoá học chạy trên server, nên đóng tab trình duyệt thì tiến trình vẫn tiếp tục.
II.Cần chuẩn bị gì
Theo README, để chạy theo cách tự dựng bạn cần:
- Node.js từ 22.19 trở lên (
package.jsonyêu cầu>=22.19.0). - pnpm từ 10 trở lên.
- PostgreSQL 16, vì khoá học được lưu trên server. Khi phát triển trên máy mình, lệnh
pnpm db:upsẽ dựng sẵn một PostgreSQL trong Docker cho bạn, nên bạn cần cài Docker nếu đi theo đường này. - Một API key của nhà cung cấp AI. Bản cấu hình mẫu chỉ cần
OPENAI_API_KEYtrong file.env.local, hoặc bạn đổi sang nhà cung cấp khác mà bạn có key.
Nếu chọn cách chạy bằng Docker Compose thì cần Docker và Docker Compose. README không ghi yêu cầu RAM, GPU hay hệ điều hành cụ thể, nên phần này mình không khẳng định.
API key là chìa khoá tính tiền trên tài khoản của bạn. Chỉ đặt nó trong file `.env.local` trên máy bạn, đừng dán vào chat, đừng đẩy lên GitHub. Việc sinh bài học, hình, giọng đọc có thể tốn phí theo bảng giá của nhà cung cấp bạn chọn.
III.Cài đặt từng bước
Có hai đường: chạy trực tiếp bằng pnpm (hợp với người muốn chỉnh sửa, xem code) và chạy bằng Docker Compose (gọn hơn nếu bạn chỉ muốn dùng). Phần dưới đi theo đường pnpm, cuối có phần Docker.
- Tải mã nguồnClone repo về máy và cài thư viện bằng pnpm
- Tạo file cấu hìnhSao chép .env.example và openmaic.example.yml, điền API key
- Bật cơ sở dữ liệuChạy pnpm db:up rồi bỏ comment dòng DATABASE_URL
- Chạy ứng dụngChạy pnpm dev và mở localhost:3000
A.Tải mã nguồn và cài thư viện
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) tại thư mục bạn muốn đặt dự án rồi chạy:
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm installLệnh đầu tải mã nguồn về. Lệnh thứ hai đi vào thư mục dự án. Lệnh thứ ba cài các thư viện cần thiết. Chỗ người mới hay vấp: phải chạy pnpm install bên trong thư mục OpenMAIC, không phải thư mục cha. Nếu máy báo không có pnpm, bạn cần cài pnpm trước (README không hướng dẫn cách cài pnpm, bạn xem trang chủ pnpm).
B.Tạo file cấu hình
Repo có hai file mẫu. Bạn sao chép chúng thành file thật:
cp .env.example .env.local # API keys and server options
cp openmaic.example.yml openmaic.yml # which models the server uses.env.local chứa key và tuỳ chọn của server. openmaic.yml khai báo nhà cung cấp (provider) nào server được gọi và mỗi "slot" (mỗi việc cần AI: dàn ý, nội dung slide, đọc thành tiếng, tìm web…) dùng model nào. Bản mẫu chỉ cần OPENAI_API_KEY trong .env.local. Mở file bằng trình soạn thảo, điền key vào dòng tương ứng, ví dụ OPENAI_API_KEY=sk-.... Trên Windows PowerShell, cp cũng chạy được vì là bí danh của lệnh sao chép.
Ví dụ phần openmaic.yml theo README, khai báo hai nhà cung cấp và gán model cho từng slot:
providers:
openai:
preset: openai
apiKey: ${OPENAI_API_KEY} # OPENAI_API_KEY=sk-... in .env.local
anthropic:
preset: anthropic
apiKey: ${ANTHROPIC_API_KEY}
slots:
llm: openai:gpt-5.5 # the default chat model
course.outline: anthropic:claude-sonnet-4-6
video: null # turn a capability offKey được giữ trong .env.local và gọi lại bằng cú pháp ${TÊN_BIẾN}. Dòng video: null nghĩa là tắt khả năng đó. Server kiểm tra file khi khởi động và báo rõ lỗi nằm ở trường nào, hoặc dòng nào nếu YAML sai cú pháp. Nếu bạn chỉ có key của một hãng, hãy sửa các dòng llm, course.outline cho cùng dùng hãng đó, đừng để slot trỏ tới hãng bạn chưa có key.
C.Bật cơ sở dữ liệu
pnpm db:upLệnh này dựng một PostgreSQL phát triển trong Docker tại 127.0.0.1:5432. Sau đó mở .env.local, bỏ dấu comment ở dòng DATABASE_URL cục bộ:
DATABASE_URL=postgres://openmaic:openmaic-dev@127.0.0.1:5432/openmaicNếu quên bước này, server sẽ từ chối khởi động và nói cách cung cấp DATABASE_URL. Muốn dừng database mà giữ dữ liệu, dùng pnpm db:down. Cần đổi cổng thì đặt OPENMAIC_DB_PORT. Bạn cũng có thể dùng một PostgreSQL khác bất kỳ.
D.Chạy ứng dụng
pnpm devSau đó mở trình duyệt vào http://localhost:3000.
E.Chạy bản production
Khi muốn chạy lâu dài thay vì chế độ phát triển:
pnpm build && DATABASE_URL=postgres://... pnpm startHãy để server chạy như một tiến trình dài hạn (bằng trình quản lý tiến trình hoặc container), vì việc sinh khoá học diễn ra bên trong server và tiếp tục khi bạn rời trang. Trên PowerShell, cú pháp đặt biến ngay trước lệnh như trên không chạy được; bạn cần đặt DATABASE_URL trong .env.local hoặc dùng Docker.
F.Cách khác: chạy bằng Docker Compose
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --buildRồi mở http://localhost:3000. Bộ này gồm hai container: ứng dụng và PostgreSQL. Dữ liệu nằm trong các volume openmaic-postgres và openmaic-data, vẫn còn sau docker compose down, nhưng docker compose down -v sẽ xoá sạch. Muốn cấu hình model bằng openmaic.yml, tạo file từ openmaic.example.yml và bỏ comment dòng mount trong docker-compose.yml. Nếu không, bạn có thể kết nối dịch vụ model ngay trong phần cài đặt model của ứng dụng.
Bản Compose mặc định là cài đặt cá nhân: chỉ lắng nghe ở 127.0.0.1:3000, ai mở từ máy bạn cũng thấy chung một thư viện. Muốn cho máy khác truy cập, README yêu cầu làm trước ba việc: đặt ACCESS_CODE dài và ngẫu nhiên trong .env.local, đặt PERSISTENCE_POSTGRES_PASSWORD ngẫu nhiên (chữ và số) trước lần chạy đầu, rồi mới mở ra mạng:
OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 docker compose up -d --buildNếu mở ra mạng mà không đặt ACCESS_CODE, README cảnh báo bất kỳ ai tới được cổng đó đều có thể xem, sửa và xoá toàn bộ thư viện của bạn. Không bỏ qua bước này.
README còn có hướng dẫn tăng tốc build khi mạng chậm (tham số ALPINE_MIRROR, NPM_REGISTRY), và cách cài OpenMAIC Skill cho OpenClaw. Phần sau nằm ở đoạn README bị cắt trong tư liệu mình có, nên mình không chép lệnh ở đây. Bạn xem trực tiếp README trong repo, và thư mục skills/ để biết skill đi kèm.
IV.Kiểm tra đã chạy được chưa
Cách đơn giản nhất: sau khi chạy pnpm dev (hoặc docker compose up --build), mở http://localhost:3000. Nếu thấy giao diện OpenMAIC tải lên là server đã chạy.
Nếu terminal báo server từ chối khởi động và nhắc về DATABASE_URL, nghĩa là cơ sở dữ liệu chưa được khai báo, bạn quay lại bước bật database. Nếu server báo lỗi cấu hình kèm tên trường, đó là openmaic.yml sai chỗ nào đó, README nói server sẽ chỉ rõ từng lỗi.
Bước kiểm tra cuối cùng là thử tạo một bài học ngắn với một chủ đề đơn giản. Nếu bài học được sinh ra, key và model của bạn đang hoạt động. README không mô tả chính xác từng màn hình, nên mình chỉ nói được ở mức này.
V.Dùng vào việc thật
A.Giáo viên chuẩn bị bài cho tiết sau
Bạn dạy môn khoa học cấp hai và cần bài về một chủ đề mới cho tuần sau. Bạn mở OpenMAIC, mô tả chủ đề, hoặc đính kèm tài liệu giáo khoa bạn đang dùng, và để AI dựng bài. Bạn nhận một bài có slide, quiz và có thể cả mô phỏng tương tác, cùng giáo viên AI giảng thử. Sau đó bạn xuất ra file .pptx để chỉnh tiếp bằng PowerPoint quen thuộc, hoặc mang đi dạy trên lớp.
Soạn bài mất nhiều giờ nhất ở khâu dựng khung, và đó đúng là khâu AI làm nhanh nhất.
Ông T
B.Quản lý đào tạo nội bộ
Bạn làm văn phòng và cần một buổi hướng dẫn nhân viên mới về quy trình công ty, mà đã có sẵn file tài liệu. Bạn đính kèm tài liệu đó làm nguồn, yêu cầu tạo bài học. Kết quả là một lớp học dựa trên chính tài liệu của bạn. Khi cần phát cho người không có mạng ổn định, bạn xuất một file .html offline phát được cả bài. Lưu ý nội dung tài liệu sẽ được gửi tới nhà cung cấp AI bạn chọn, nên đừng đưa tài liệu mật nếu chưa kiểm tra chính sách của họ.
C.Người tự học một kỹ năng mới
Bạn muốn học một chủ đề lạ, ví dụ cơ bản về lập trình. Bạn nhập chủ đề, chọn học theo dự án (PBL) để vừa học vừa làm với gia sư AI. README mô tả PBL là xây một dự án chạy được cùng AI, từng cột mốc một. Bạn có thể hỏi bạn học AI hoặc giáo viên AI khi chưa hiểu, vì lớp có thảo luận theo thời gian thực.
D.Lập trình viên gắn vào công cụ đang dùng
Bạn là dev và đã dùng OpenClaw hoặc một agent workbench như Codex. README nói OpenMAIC Skill cho phép tạo lớp học ngay từ ứng dụng nhắn tin như Slack, Telegram hay từ IDE. Cách này tiện khi bạn muốn nhờ trợ lý tạo nhanh một bài giải thích cho đồng đội mà không rời công cụ làm việc. Cách cài skill chi tiết bạn xem trong README và thư mục skills/.
VI.Lỗi hay gặp và cách xử lý
- Server không khởi động, nhắc
DATABASE_URL. Bạn chưa khai báo cơ sở dữ liệu. Chạypnpm db:up, rồi bỏ comment dòngDATABASE_URLtrong.env.local. Nếupnpm db:uplỗi, kiểm tra Docker đã mở chưa. - Báo thiếu hoặc sai phiên bản Node. Dự án yêu cầu Node 22.19 trở lên. Chạy
node --versionđể kiểm tra, nâng cấp nếu thấp hơn. openmaic.ymlbáo lỗi khi khởi động. Server chỉ ra trường hoặc dòng bị sai. Thường là thụt lề YAML sai, hoặc slot trỏ tới nhà cung cấp bạn chưa khai báo key. Sửa đúng chỗ được báo rồi chạy lại.- Tạo bài học không ra kết quả hoặc báo lỗi gọi model. Thường do key sai, hết hạn mức, hoặc model ghi trong slot không có trong tài khoản của bạn. Kiểm tra lại key trong
.env.localvà tên model. - Cổng 3000 hoặc 5432 bị chiếm. Một chương trình khác đang dùng cổng đó. Với database, README cho phép đổi cổng bằng
OPENMAIC_DB_PORT. Hoặc tắt chương trình đang chiếm cổng.
VII.Có nên dùng không
Điểm mạnh: miễn phí phần mềm (giấy phép MIT), hỗ trợ rất nhiều nhà cung cấp AI, xuất được .pptx và .html offline, có cả đường chạy Docker lẫn chạy trực tiếp, và dự án cập nhật thường xuyên.
Giới hạn: bạn phải tự cài và tự lo API key, nên có chi phí gọi AI. Cần Node, pnpm và PostgreSQL (hoặc Docker), nên người hoàn toàn chưa từng dùng terminal sẽ thấy hơi nặng. Từ bản 1.2.0 OpenMAIC cần một tiến trình Node chạy lâu dài kèm PostgreSQL, không chạy được trên hạ tầng serverless như Vercel. Một số bản nâng cấp là một chiều (không quay lại được), nên đọc ghi chú phát hành trước khi nâng cấp. Chất lượng bài học phụ thuộc vào model bạn chọn và chất lượng tài liệu đầu vào, nên bạn vẫn cần đọc lại trước khi dạy.
Khi nào chọn cách khác: nếu bạn chỉ cần vài slide nhanh, một công cụ làm slide có AI dùng ngay trên web sẽ đỡ công cài đặt hơn. Còn nếu bạn muốn một lớp học có tác tử cùng giảng và thảo luận, tự chủ dữ liệu và tự chọn model, OpenMAIC là lựa chọn đáng thử.
Câu hỏi thường gặp
OpenMAIC có miễn phí không?
Phần mềm là mã nguồn mở với giấy phép MIT nên dùng miễn phí. Tuy nhiên bạn cần API key của nhà cung cấp AI, và việc gọi model có thể tốn phí theo bảng giá của họ. README cũng nhắc bạn có thể dùng model chạy cục bộ như Ollama, nhưng chưa nêu chi phí phần cứng.
Cần những gì để chạy OpenMAIC?
README yêu cầu Node.js từ 22.19, pnpm từ 10 và PostgreSQL 16. Trên máy cá nhân, lệnh pnpm db:up dựng sẵn PostgreSQL bằng Docker. Bạn cũng cần một API key, bản mẫu chỉ cần OPENAI_API_KEY.
Có cần GPU không?
Tư liệu không nói OpenMAIC cần GPU. Phần nặng là gọi model AI qua dịch vụ bạn cấu hình. Nếu muốn chạy model cục bộ như Ollama thì yêu cầu phần cứng phụ thuộc model đó, và README chưa nêu chi tiết.
Chạy được trên Windows không?
README không ghi rõ danh sách hệ điều hành hỗ trợ. Dự án dựa trên Node.js, pnpm và Docker, nên về nguyên tắc có thể chạy ở nơi các công cụ này chạy. Lưu ý cú pháp đặt biến môi trường ngay trước lệnh như trong README là kiểu shell Unix, trên PowerShell bạn nên đặt biến trong file .env.local.
Dữ liệu của mình có an toàn không?
Khoá học lưu trong PostgreSQL do bạn tự chạy. Bản Docker mặc định chỉ lắng nghe ở 127.0.0.1. Nếu mở ra mạng, README yêu cầu đặt ACCESS_CODE và mật khẩu database. Nội dung bạn tạo vẫn được gửi tới nhà cung cấp AI bạn chọn, nên hãy tự xem chính sách của họ.
Có dùng được trên Vercel không?
Từ bản 1.2.0 thì không. Việc sinh khoá học chạy trong một tiến trình dài hạn, nên cần Node.js chạy liên tục kèm PostgreSQL, bằng Docker hoặc pnpm start. Serverless được hỗ trợ đến các bản 1.1.x.
Xuất bài học ra được những định dạng nào?
README nói bạn xuất được file .pptx giữ đủ các cảnh, một file .html chạy offline cả bài học, hoặc ZIP lớp học để chuyển sang bản triển khai khác. Ngoài ra các bản phát hành có nhắc xuất video MP4.


