OpenMAIC: tạo lớp học AI nhiều thầy cô, bạn học từ một chủ đề — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về THU-MAIC/OpenMAIC — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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. Bạn đưa một chủ đề hoặc tài liệu, nó dựng cả bài học gồm slide, quiz, mô phỏng và hoạt động theo dự án, do giáo viên và bạn học AI dẫn dắt. Cài không quá khó nếu bạn quen terminal, nhưng cần Node.js 22.19 trở lên, pnpm, PostgreSQL và ít nhất một API key của dịch vụ AI.
OpenMAIC là một nền tảng mã nguồn mở biến một chủ đề, hoặc một bộ tài liệu của bạn, thành lớp học tương tác hoàn chỉnh. Tên đầy đủ là Open Multi-Agent Interactive Classroom. Trong lớp có giáo viên AI và bạn học AI. Họ giảng bài, vẽ lên bảng trắng, nói thành tiếng và thảo luận với bạn theo thời gian thực.
Nếu bạn là giáo viên, người làm đào tạo nội bộ, chủ doanh nghiệp nhỏ muốn dạy nhân viên, hay lập trình viên muốn thử một sản phẩm giáo dục dùng AI, repo này đáng để xem. Bạn không phải soạn slide từng trang. Bạn mô tả bài học, AI dựng giúp, rồi bạn chỉnh lại.
Điểm đáng giá nhất là sự trọn vẹn. Một bài học không chỉ có slide mà còn có quiz, mô phỏng tương tác bằng HTML và hoạt động học theo dự án (PBL). Kết quả xuất được ra file PowerPoint, một file HTML chạy offline, hoặc file ZIP để chuyển sang nơi khác. Hiện repo có khoảng 43397 sao và 6691 fork, viết chủ yếu bằng TypeScript, dùng giấy phép MIT.
THU-MAIC/OpenMAIC
OpenMAIC biến một chủ đề hoặc tài liệu thành lớp học tương tác: slide, quiz, mô phỏng, có giáo viên AI giảng và thảo luận cùng bạn.
I.OpenMAIC làm được gì
A.Sinh bài học chỉ bằng một mô tả
Bạn nói chủ đề muốn dạy hoặc đính kèm tài liệu có sẵn. AI dựng một bài học đầy đủ trong vài phút. Bạn đỡ phải bắt đầu từ trang trắng.
B.Lớp học nhiều agent
Giáo viên và bạn học AI cùng tham gia. Họ giảng, thảo luận và tương tác với bạn. Bạn có thể hỏi về bất kỳ thành phần nào trên slide, về phần tương tác hoặc hình vẽ trên bảng trắng. Cảm giác gần với một lớp học thật hơn là đọc tài liệu một chiều.
C.Nhiều loại cảnh học
Ngoài slide và quiz, có mô phỏng tương tác bằng HTML và học theo dự án. Ở chế độ học theo dự án, bạn làm ra một sản phẩm chạy được cùng gia sư AI, qua từng cột mốc. Bản cập nhật gần đây còn nhắc tới chế độ tương tác sâu như 3D, mô phỏng, trò chơi, sơ đồ tư duy và lập trình trực tuyến.
D.Bảng trắng và giọng nói
Agent vẽ sơ đồ, viết công thức và giải thích bằng giọng nói. Với môn có công thức hoặc hình minh hoạ, phần này giúp bài giảng dễ theo dõi hơn nhiều.
E.Xuất ra nhiều dạng
Bạn xuất được file .pptx giữ nguyên các cảnh, một file .html offline phát lại cả bài, hoặc ZIP lớp học để đưa sang bản triển khai khác. README cũng nhắc việc xuất video MP4 và hoàn tác ở cấp khoá học.
F.Dùng từ ứng dụng nhắn tin hoặc IDE
Repo có sẵn một Skill tên OpenMAIC. Skill này làm việc với OpenClaw và các agent workbench như Codex, DeepSeek, WorkBuddy. Nhờ đó bạn tạo lớp học từ Feishu, Slack, Telegram hoặc ngay trong IDE.
G.Chọn mô hình AI linh hoạt
Bạn khai báo nhà cung cấp và mô hình trong một file cấu hình. README liệt kê OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok, OpenRouter, Ollama, Lemonade và nhiều nơi khác, kể cả mọi API tương thích OpenAI.
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Node.js từ 22.19 trở lên. File
package.jsoncũng yêu cầu Node từ 22.19.0. - pnpm từ 10 trở lên. README không ghi cách cài pnpm, bạn tự cài theo hướng dẫn chính thức của pnpm.
- PostgreSQL 16, vì khoá học được lưu trên máy chủ. Khi chạy thử trên máy cá nhân, lệnh
pnpm db:upsẽ bật giúp một PostgreSQL trong Docker, nên bạn cần có Docker. Dùng PostgreSQL khác cũng được. - Ít nhất một API key của dịch vụ AI. File mẫu chỉ cần
OPENAI_API_KEYđể chạy, hoặc bạn đổi sang nhà cung cấp mà bạn đang có key.
README phần mình đọc được không nói gì về hệ điều hành hay phần cứng cụ thể, và cũng không nhắc cần GPU. Vì app gọi mô hình qua API, máy bạn chủ yếu chạy web và cơ sở dữ liệu. Đây là suy luận của mình từ cách cấu hình, không phải lời README.
API key là chìa khoá tính tiền. Chỉ điền vào file .env.local trên máy bạn, đừng gửi lên nhóm chat hay đưa lên GitHub. Mỗi lần AI sinh bài học đều tốn chi phí của nhà cung cấp mà bạn chọn, nên hãy theo dõi hạn mức dùng.
III.Cài đặt từng bước
- 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 thửpnpm dev rồi mở localhost:3000
- Hoặc dùng Dockerdocker compose up --build thay cho các bước trên
A.Tải mã nguồn và cài thư viện
Mở terminal (PowerShell hoặc Git Bash trên Windows, Terminal trên macOS hoặc Linux) ở thư mục bạn muốn đặt dự án. Sau đó chạy:
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm installgit clone tải mã nguồn về. cd OpenMAIC đi vào thư mục vừa tải. pnpm install cài các thư viện phụ thuộc. Nếu báo không tìm thấy pnpm, nghĩa là bạn chưa cài pnpm. Nếu báo sai phiên bản Node, hãy kiểm tra lại mức 22.19 trở lên.
B.Tạo file cấu hình
Bạn cần hai file. File thứ nhất chứa khoá và tuỳ chọn máy chủ. File thứ hai quy định máy chủ dùng mô hình nào cho việc gì.
cp .env.example .env.local # API keys and server options
cp openmaic.example.yml openmaic.yml # which models the server usesLệnh cp sao chép file mẫu thành file thật. Trong PowerShell, cp cũng chạy được vì là tên ngắn của lệnh sao chép. Phần chú thích sau dấu # chỉ để giải thích, bạn không cần gõ.
Theo README, bản sao chỉ cần OPENAI_API_KEY trong .env.local. Mở file này bằng trình soạn thảo, điền key vào chỗ tương ứng. Các dòng còn lại đang bị comment, để nguyên cho đến khi bạn cần. Nếu bạn dùng nhà cung cấp khác, hãy đổi provider trong file cho khớp với key bạn có.
File openmaic.yml khai báo provider (tài khoản mà máy chủ gọi tới) và gán mô hình cho từng slot (mỗi việc dùng AI: dàn ý, nội dung slide, đọc thành tiếng, tìm web...). Khoá luôn nằm trong .env.local và được gọi lại bằng ${TÊN_BIẾN}. Ví dụ của README:
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 offĐoạn này nói: mô hình chat mặc định là openai:gpt-5.5, dàn ý khoá học dùng mô hình của Anthropic, và video: null nghĩa là tắt khả năng tạo video. Bạn chỉ cần khai báo provider mà bạn có key. Máy chủ kiểm tra file khi khởi động và báo lỗi theo tên trường, hoặc theo số dòng nếu YAML sai cú pháp.
Với người dùng một key cho nhiều việc, README có ví dụ gói token như MiniMax hoặc TokenDance, trong đó một key lo cả chat, ảnh, video, giọng đọc và tìm web. Bạn nên xem các ví dụ đó trong README nếu muốn bật đủ mọi khả năng.
C.Bật cơ sở dữ liệu
pnpm db:upLệnh này bật một PostgreSQL trong Docker, lắng nghe ở 127.0.0.1:5432. Bạn cần mở Docker trước khi chạy. Sau đó mở .env.local và bỏ dấu comment ở dòng DATABASE_URL:
DATABASE_URL=postgres://openmaic:openmaic-dev@127.0.0.1:5432/openmaicĐây là chỗ người mới hay quên. README nói rõ: nếu thiếu DATABASE_URL, máy chủ từ chối khởi động và nhắc bạn cung cấp. Nếu cổng 5432 đã bị chiếm, README cho biết có thể đặt OPENMAIC_DB_PORT để đổi cổng. Lệnh pnpm db:down dừng cơ sở dữ liệu mà vẫn giữ dữ liệu.
D.Chạy thử
pnpm devSau đó mở trình duyệt vào http://localhost:3000.
E.Cách khác: chạy bằng Docker
Nếu bạn không muốn cài Node và pnpm, README có cách chạy cả ứng dụng và PostgreSQL bằng Docker Compose:
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --buildSau khi xong, mở http://localhost:3000. Dữ liệu nằm trong hai volume openmaic-postgres và openmaic-data. Chúng vẫn còn sau docker compose down, nhưng docker compose down -v sẽ xoá sạch.
Bản Compose này là cài đặt cá nhân: chỉ mở ở 127.0.0.1:3000 và mọi trình duyệt thấy chung một thư viện. Muốn cho máy khác truy cập, README yêu cầu bạn đặt ACCESS_CODE dài và ngẫu nhiên trong .env.local trước, rồi đặt PERSISTENCE_POSTGRES_PASSWORD trước lần chạy đầu. Phần chạy chính thức cho máy khác nằm trong README, mục triển khai Docker.
Đừng mở OpenMAIC ra mạng khi chưa đặt ACCESS_CODE. README cảnh báo: thiếu mã này, bất kỳ ai tới được cổng đều có quyền xem, sửa và xoá cả thư viện của bạn.
F.Chạy bản production
Muốn chạy lâu dài, README ghi:
pnpm build && DATABASE_URL=postgres://... pnpm startPhải để máy chủ chạy liên tục (qua 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 máy chủ và vẫn tiếp tục khi bạn đã đóng trình duyệt. Từ bản 1.2.0 trở đi, README nói các dịch vụ serverless như Vercel không còn được hỗ trợ.
IV.Kiểm tra đã chạy được chưa
Khi pnpm dev chạy ổn, mở http://localhost:3000 sẽ thấy giao diện OpenMAIC trong trình duyệt. README không mô tả chi tiết màn hình đầu tiên, nên mình không đoán. Cách kiểm tra chắc chắn nhất là thử một bài ngắn:
- Nhập một chủ đề đơn giản và để AI sinh bài học.
- Nếu bài học xuất hiện, tức là kết nối với mô hình AI đã ổn.
- Nếu máy chủ không lên, đọc dòng báo lỗi trong terminal. README cho biết máy chủ sẽ nêu tên trường sai trong
openmaic.yml, hoặc nhắc bạn cung cấpDATABASE_URL.
Với bản Docker, bạn kiểm tra bằng việc truy cập được địa chỉ trên và cả hai container (ứng dụng và PostgreSQL) đang chạy.
V.Dùng vào việc thật
A.Giáo viên chuẩn bị bài giảng mới
Bạn dạy một môn và cần bài mở đầu cho chương mới. Bạn mô tả chủ đề, hoặc đính kèm giáo trình có sẵn, rồi để OpenMAIC dựng bài. Kết quả là một lớp học có slide, quiz và các hoạt động tương tác. Bạn xem lại, chỉnh phần chưa ưng, rồi xuất sang .pptx để dùng trong lớp thật. README nói file này giữ nguyên các cảnh trong bài.
Đừng bắt đầu từ trang trắng. Hãy để AI dựng khung, còn việc của bạn là chỉnh cho đúng và hay hơn.
Ông T
B.Chủ shop đào tạo nhân viên mới
Shop có bộ tài liệu về quy trình bán hàng, đổi trả và chăm sóc khách. Bạn đính kèm các tài liệu đó và yêu cầu dựng một bài học cho nhân viên mới. Mỗi người học xong sẽ làm quiz. Muốn gửi cho chi nhánh khác, bạn xuất file .html offline: README nói file này phát lại cả bài học mà không cần máy chủ. Nếu muốn chuyển cả lớp sang nơi cài OpenMAIC khác, dùng ZIP lớp học.
C.Lập trình viên tạo bài học từ trong IDE hoặc ứng dụng nhắn tin
Bạn đã dùng một agent workbench như OpenClaw, Codex, DeepSeek hoặc WorkBuddy. README cho biết OpenMAIC Skill hoạt động với các công cụ này, nên bạn có thể yêu cầu tạo lớp học ngay từ IDE, hoặc từ Feishu, Slack, Telegram. Phần phần mình đọc được chưa ghi lệnh cài Skill cụ thể. Bạn xem thư mục skills/ trong repo và phần hướng dẫn OpenClaw trong README đầy đủ.
D.Tự học một chủ đề mới
Bạn muốn hiểu một chủ đề mới, ví dụ nguyên lý hoạt động của một thuật toán. Bạn mô tả chủ đề và nhờ OpenMAIC dựng bài kèm mô phỏng tương tác. Sau đó bạn hỏi giáo viên AI về bất kỳ phần tử nào trên slide hoặc hình trên bảng trắng. Nếu muốn học bằng cách làm, bạn chuyển sang hoạt động học theo dự án để xây một sản phẩm chạy được cùng gia sư AI.
VI.Lỗi hay gặp và cách xử lý
A.Máy chủ không khởi động, báo thiếu DATABASE_URL
Đây là lỗi dễ gặp nhất. Hãy chắc chắn đã chạy pnpm db:up và đã bỏ comment dòng DATABASE_URL trong .env.local. Docker cũng phải đang mở. README nói rõ: không có DATABASE_URL thì máy chủ từ chối chạy.
B.Sai phiên bản Node hoặc pnpm
Nếu pnpm install hay pnpm dev báo lỗi phiên bản, kiểm tra lại Node từ 22.19 và pnpm từ 10. Gỡ bản cũ hoặc dùng công cụ quản lý phiên bản mà bạn quen. Mình không đoán công cụ nào vì README không nêu.
C.Lỗi trong openmaic.yml
File này sai chính tả hoặc thụt lề YAML thường dẫn tới lỗi khi khởi động. README cho biết máy chủ kiểm tra file và nêu tên từng trường sai, hoặc số dòng nếu YAML hỏng. Hãy đọc kỹ thông báo trong terminal, sửa đúng chỗ đó rồi chạy lại.
D.AI không sinh được bài học
Thường do API key sai, hết hạn mức, hoặc provider trong openmaic.yml không khớp với key đã điền. Kiểm tra .env.local, và nhớ rằng mỗi slot phải trỏ tới nhà cung cấp mà bạn thật sự có key. Nếu có slot bạn không dùng, bạn có thể đặt nó thành null để tắt, như ví dụ của video.
E.Cổng 5432 hoặc 3000 bị chiếm
Nếu cơ sở dữ liệu không lên vì cổng 5432 đã có chương trình khác dùng, README cho phép đặt OPENMAIC_DB_PORT sang cổng khác (nhớ sửa DATABASE_URL cho khớp). Với bản Docker, OPENMAIC_PORT nằm trong danh sách biến README nhắc tới, và chúng được đọc từ shell hoặc file .env cạnh docker-compose.yml, không phải .env.local.
VII.Có nên dùng không
Điểm mạnh. OpenMAIC là một trải nghiệm trọn gói: từ chủ đề tới slide, quiz, mô phỏng và dự án, có giáo viên AI và bạn học AI. Giấy phép MIT, nhiều nhà cung cấp mô hình, xuất được ra PPTX, HTML và ZIP. Repo cũng vẫn được cập nhật trong vài tháng gần đây, và bản ghi thay đổi cho thấy nhiều lần vá bảo mật.
Giới hạn. Cài không phải kiểu bấm một nút: bạn cần Node, pnpm, PostgreSQL (thường qua Docker) và API key. Chi phí gọi AI do bạn tự chịu. Từ bản 1.2.0, repo cần một tiến trình chạy liên tục kèm PostgreSQL, nên không chạy trên các dịch vụ serverless. Một số bản nâng cấp là một chiều, nghĩa là không quay lại được, nên hãy đọc ghi chú nâng cấp trước khi cập nhật bản đang dùng thật. Chất lượng bài học còn phụ thuộc vào mô hình bạn chọn, nên nội dung do AI sinh ra cần bạn kiểm tra trước khi đem 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ụ tạo slide thông thường sẽ nhẹ hơn nhiều. Nếu bạn không muốn tự quản trị máy chủ và cơ sở dữ liệu, hãy xem bản demo trực tuyến mà README có nhắc, hoặc cân nhắc dịch vụ trả phí có sẵn. Còn nếu bạn muốn một lớp học AI chạy trên hạ tầng của mình, có thể chỉnh và nối vào các công cụ nhắn tin hay IDE, OpenMAIC là lựa chọn rất đáng thử.
Câu hỏi thường gặp
OpenMAIC có miễn phí không?
Mã nguồn mở, dùng giấy phép MIT nên bạn tải và chạy tự do. Tuy nhiên bạn phải có API key của nhà cung cấp AI như OpenAI, Anthropic hay DeepSeek, và phần gọi AI sẽ tính phí theo nhà cung cấp đó. README cũng nhắc tới Ollama, Lemonade và FunASR chạy cục bộ, nhưng chưa nêu chi phí cụ thể.
Cài OpenMAIC cần những gì?
Cần Node.js từ 22.19 trở lên, pnpm từ 10 trở lên và PostgreSQL 16. Khi chạy thử trên máy cá nhân, lệnh pnpm db:up sẽ bật PostgreSQL trong Docker giúp bạn. Bạn cũng cần ít nhất một API key AI, mặc định trong file mẫu là OPENAI_API_KEY.
Có cần GPU không?
README không nhắc yêu cầu GPU. Ứng dụng gọi mô hình AI qua API của nhà cung cấp mà bạn cấu hình. Nếu bạn muốn chạy mô hình cục bộ qua Ollama hay Lemonade thì yêu cầu phần cứng phụ thuộc vào mô hình, phần này chưa có thông tin trong tư liệu.
Chạy được trên Windows không?
README phần mình đọc được không nêu hệ điều hành cụ thể. Các lệnh dựa vào Node, pnpm và Docker, đều là công cụ chạy được trên Windows. Tuy vậy mình chưa có xác nhận chính thức từ README, nên bạn nên thử bản Docker hoặc xem phần còn lại của README nếu gặp lỗi.
Dữ liệu của tôi có an toàn không?
Khoá học được lưu trong PostgreSQL trên máy chủ của bạn. 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 dài và ngẫu nhiên, nếu không bất kỳ ai tới được cổng đều sửa và xoá được thư viện. Lưu ý nội dung bạn đưa vào vẫn được gửi tới nhà cung cấp AI mà bạn chọn.
OpenMAIC xuất bài học ra định dạng nào?
README nói bạn xuất được file .pptx giữ nguyên các cảnh, một file .html offline phát lại cả bài, hoặc ZIP lớp học để chuyển sang bản triển khai khác. Phần lịch sử bản phát hành còn nhắc tới xuất video MP4 một cú nhấp.
Có dùng được từ Telegram hay Slack không?
Có. README cho biết OpenMAIC Skill hoạt động với OpenClaw và các agent workbench như Codex, DeepSeek, WorkBuddy, để tạo lớp học từ Feishu, Slack, Telegram hoặc trong IDE. Lệnh cài Skill cụ thể chưa có trong phần README mà mình đọc, bạn xem thư mục skills/ và mục OpenClaw trong README.


