# OpenMAIC: tạo lớp học AI có giáo viên và bạn học ảo từ một chủ đề — hướng dẫn cài đặt và dùng

> OpenMAIC (Open Multi-Agent Interactive Classroom) là nền tảng mã nguồn mở, giấy phép MIT, biến một chủ đề hoặc tài liệu thành lớp học tương tác với giáo viên AI và bạn học AI. Bạn tự chạy trên máy mình bằng Node.js, pnpm và PostgreSQL, hoặc bằng Docker. Cài không quá khó nhưng cần có API key của một nhà cung cấp mô hình AI.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-31 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/openmaic-lop-hoc-ai-da-tac-nhan-huong-dan-cai-dat

**OpenMAIC** (Open Multi-Agent Interactive Classroom) 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 thành lớp học tương tác. Bạn nhập chủ đề, AI dựng bài giảng gồm slide, câu hỏi kiểm tra, mô phỏng tương tác. Giáo viên AI sẽ giảng, vẽ lên bảng trắng và nói thành tiếng. Bên cạnh còn có các bạn học AI để thảo luận cùng bạn.

Repo này hợp với ba nhóm người. Thứ nhất là giáo viên, người làm đào tạo nội bộ trong doanh nghiệp, cần dựng bài giảng nhanh. Thứ hai là người tự học, muốn có một lớp học chạy riêng theo đúng chủ đề mình quan tâm. Thứ ba là lập trình viên muốn tự host một hệ thống học tập có AI. Repo viết bằng TypeScript, dùng giấy phép MIT, hiện có khoảng 43.435 sao và 6.698 fork, và vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất là bạn không chỉ nhận một bộ slide. Bạn nhận cả một buổi học có người giảng, có người hỏi lại, có bài tập dự án. Kết quả còn xuất ra được file `.pptx`, file `.html` chạy offline, hoặc gói ZIP để chuyển sang máy khác.

```repo
- repo | THU-MAIC/OpenMAIC
- kind | Ứng dụng
- desc | 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à vẽ bảng trắng.
- stars | 43k
- lang | TypeScript
- license | MIT
```

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

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

- **Tạo bài giảng chỉ với một lần mô tả.** Bạn nêu chủ đề hoặc đính kèm tài liệu, AI dựng cả bài học trong vài phút. Người làm văn phòng đỡ phải ngồi chỉnh từng slide.
- **Lớp học nhiều tác tử.** Giáo viên AI và bạn học AI cùng giảng, thảo luận và tương tác với bạn theo thời gian thực. Học có đối thoại dễ nhớ hơn đọc một chiều.
- **Nhiều loại cảnh học.** Gồm slide, quiz, mô phỏng HTML tương tác và học theo dự án (PBL). Bản PBL mới nhất cho bạn làm ra một sản phẩm chạy được cùng gia sư AI, theo từng mốc.
- **Bảng trắng và giọng nói.** 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.** Có file `.pptx` giữ đủ các cảnh, một file `.html` offline phát được cả bài, hoặc ZIP lớp học để chuyển sang nơi khác.
- **Kết nối với trợ lý khác.** Skill OpenMAIC có sẵn chạy được với OpenClaw và một số agent workbench như Codex, DeepSeek, WorkBuddy. Nhờ đó bạn tạo lớp học từ ứng dụng nhắn tin như Feishu, Slack, Telegram, hoặc ngay trong IDE.
- **Chọn mô hình AI linh hoạt.** Hỗ trợ OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok, OpenRouter, Ollama và nhiều bên khác, kể cả mọi API tương thích OpenAI.

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

Theo README và `package.json`, bạn cần:

- **Node.js** từ 22.19 trở lên.
- **pnpm** từ 10 trở lên.
- **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:up` sẽ dựng giúp một PostgreSQL trong Docker. Vậy bạn cần cài thêm Docker nếu dùng cách này.
- **API key** của ít nhất một nhà cung cấp mô hình. Bản cấu hình mẫu chỉ cần `OPENAI_API_KEY`, hoặc bạn đổi sang nhà cung cấp khác mà bạn có key.
- Git để tải mã nguồn về.

README phần đã cung cấp không nói rõ hệ điều hành nào được hỗ trợ và không nêu yêu cầu card đồ hoạ. Mô hình AI được gọi qua API của các nhà cung cấp, trừ khi bạn tự chọn chạy cục bộ bằng Ollama hoặc Lemonade. Phần phần cứng cho trường hợp đó README chưa nói trong đoạn mình có.

```note
API key là thứ tính tiền. Chỉ điền vào file .env.local trên máy bạn, không dán vào chat, không đưa lên GitHub. Mỗi lần tạo bài giảng sẽ gọi mô hình nhiều lần nên có thể tốn phí tuỳ nhà cung cấp.
```

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

```steps
- Tải mã nguồn | Clone repo và cài thư viện bằng pnpm
- Tạo file cấu hình | Sao chép .env.example và openmaic.example.yml
- Điền API key | Ghi key vào .env.local, chọn mô hình trong openmaic.yml
- Bật cơ sở dữ liệu | Chạy pnpm db:up rồi bỏ comment dòng DATABASE_URL
- Chạy ứng dụng | Chạy pnpm dev và mở localhost:3000
```

### Tải mã nguồn và cài thư viện

Mở terminal (PowerShell trên Windows, Terminal trên macOS hay Linux) ở thư mục bạn muốn lưu dự án, rồi chạy:

```bash
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
```

Lệ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. Nếu máy báo không có `pnpm`, bạn cần cài pnpm trước. README phần đã cung cấp không ghi cách cài pnpm, bạn xem hướng dẫn trên trang chính thức của pnpm.

### Tạo file cấu hình

Hai lệnh sau sao chép file mẫu thành file thật:

```bash
cp .env.example .env.local            # API keys and server options
cp openmaic.example.yml openmaic.yml  # which models the server uses
```

File `.env.local` chứa key và tuỳ chọn máy chủ. File `openmaic.yml` nói máy chủ dùng mô hình nào. Phần sau `#` chỉ là chú thích, bạn không cần gõ. Trên PowerShell, `cp` là bí danh của lệnh sao chép nên dùng được. Nếu bị lỗi, bạn có thể copy file bằng tay trong File Explorer và đổi tên.

### Điền API key và chọn mô hình

Mở `.env.local` và điền `OPENAI_API_KEY` (hoặc key của nhà cung cấp khác). Mọi dòng còn lại trong file mẫu đang được comment, chưa cần động tới.

File `openmaic.yml` khai báo hai thứ. **Providers** là các tài khoản mà máy chủ được gọi. **Slots** là từng việc dùng AI (dựng dàn ý, nội dung slide, đọc thành tiếng, tìm web...), mỗi việc gắn một mô hình. Key luôn nằm trong `.env.local` và được gọi lại bằng `${TÊN_BIẾN}`. Ví dụ từ README:

```yaml
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
```

Dòng `llm` là mô hình chat mặc định. Dòng `video: null` là tắt hẳn một khả năng. Nếu bạn chỉ có key OpenAI, hãy đổi các slot đang trỏ sang Anthropic cho khớp với nhà cung cấp bạn có, hoặc bỏ phần Anthropic. Sai chỗ nào, máy chủ sẽ báo đúng tên trường lỗi (hoặc số dòng nếu YAML hỏng) khi khởi động.

Tác giả gợi ý bật đủ các khả năng (ảnh minh hoạ, giọng đọc, video, tìm web) và chọn mô hình nhanh, ngữ cảnh dài làm mặc định. Một số nhà cung cấp có gói token dùng một key cho nhiều khả năng. Ví dụ với MiniMax:

```yaml
providers:
  minimax:
    preset: minimax
    apiKey: ${MINIMAX_API_KEY}

slots:
  llm: minimax:MiniMax-M3
  image: minimax                   # a provider id alone: the plan's default model
  video: minimax
  tts: minimax
  webSearch: minimax
```

Bạn có thể bỏ qua bước này lúc mới thử. Chỉ cần một key chạy được là đủ.

### Bật cơ sở dữ liệu

Khoá học được lưu ở máy chủ, nên cần PostgreSQL. Có Docker thì chạy:

```bash
pnpm db:up
```

Lệnh này dựng một PostgreSQL phát triển tại `127.0.0.1:5432`. Nếu cổng 5432 đã bị chiếm, README cho biết đặt biến `OPENMAIC_DB_PORT` để dùng cổng khác. Dừng DB mà giữ dữ liệu thì dùng `pnpm db:down`. Sau đó mở `.env.local`, bỏ dấu comment ở dòng `DATABASE_URL`:

```env
DATABASE_URL=postgres://openmaic:openmaic-dev@127.0.0.1:5432/openmaic
```

Bạn dùng PostgreSQL khác cũng được, miễn điền đúng địa chỉ vào `DATABASE_URL`.

### Chạy ứng dụng

```bash
pnpm dev
```

Để cửa sổ terminal này mở trong lúc dùng. Tắt terminal là ứng dụng tắt theo.

### Cách khác: chạy bằng Docker

Nếu không muốn cài Node và pnpm, README có sẵn cách chạy bằng Docker Compose gồm hai container: ứng dụng và PostgreSQL.

```bash
cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --build
```

Dữ liệu nằm trong hai volume `openmaic-postgres` và `openmaic-data`, vẫn còn sau `docker compose down`. Lệnh `docker compose down -v` thì xoá sạch chúng, nên đừng chạy nếu chưa muốn mất bài học. Bản Compose này là cài đặt cá nhân: chỉ lắng nghe ở `127.0.0.1:3000`, mọi trình duyệt trên máy thấy chung một thư viện.

```note
Muốn cho máy khác truy cập, README yêu cầu đặt trước ACCESS_CODE dài và ngẫu nhiên trong .env.local, cùng PERSISTENCE_POSTGRES_PASSWORD. Không có ACCESS_CODE thì ai tới được cổng cũng sửa và xoá được toàn bộ thư viện.
```

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

Sau khi `pnpm dev` (hoặc `docker compose up --build`) chạy xong, mở trình duyệt vào **http://localhost:3000**. Nếu thấy giao diện OpenMAIC hiện ra là cài thành công. README viết đúng câu "Open http://localhost:3000 and start learning".

Nếu quên khai báo `DATABASE_URL`, máy chủ sẽ từ chối khởi động và in hướng dẫn cách cung cấp. Đây không phải lỗi lạ. Đó là cách repo nhắc bạn làm nốt bước cơ sở dữ liệu.

Bước thử đầu tiên nên là một chủ đề nhỏ, ví dụ "nguyên tắc cơ bản của bảng cân đối kế toán". Nếu bài giảng được dựng ra thì key và mô hình đã nối đúng.

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

### Dựng bài đào tạo nhân viên mới

Chị Lan làm hành chính nhân sự ở một công ty nhỏ, tuần nào cũng giới thiệu quy trình cho nhân viên mới. Chị đính kèm tài liệu quy trình nội bộ vào OpenMAIC và nhập yêu cầu: "Dựng bài giới thiệu quy trình xin nghỉ phép và hoàn ứng, kèm vài câu hỏi kiểm tra". Kết quả là một lớp học có slide, có quiz, có giáo viên AI giảng. Chị xuất file `.pptx` để chỉnh thêm hoặc file `.html` offline để gửi cho nhân viên xem lại.

> Một lớp học có người giảng, có người hỏi lại, chứ không chỉ là xấp slide.
>
> — Ông T

### Tự học một chủ đề mới

Anh Minh làm kinh doanh, muốn hiểu cơ bản về dòng tiền. Anh nhập chủ đề, bật thêm tìm web nếu đã cấu hình slot `webSearch`, rồi vào học. Giữa chừng anh hỏi bạn học AI những chỗ chưa hiểu, xem giáo viên vẽ sơ đồ trên bảng trắng. Bản mới có chat trong lớp, cho phép hỏi về từng phần tử của slide. Kết quả là buổi học theo tốc độ của anh, không phải xem video dài.

### Học lập trình qua một dự án nhỏ

Bạn là lập trình viên mới và muốn có sản phẩm thật. Chọn chế độ học theo dự án (PBL), mô tả thứ bạn muốn làm. Gia sư AI dẫn bạn đi qua từng mốc để ra một dự án chạy được. README ghi rõ PBL v3 là nâng cấp một chiều, nên nếu bạn nâng từ bản cũ thì nên sao lưu dữ liệu trước.

### Tạo lớp học ngay từ ứng dụng nhắn tin hoặc IDE

Dev trong nhóm muốn gõ yêu cầu ngay trong Slack, Telegram hoặc IDE. README nói skill OpenMAIC dùng được với OpenClaw, Codex, DeepSeek, WorkBuddy. Cách cài skill không nằm trong phần README mình có, nên bạn hãy xem thư mục `skills/` và mục OpenClaw trong README của repo.

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

**Server không khởi động, báo thiếu DATABASE_URL.** Bạn chưa bật PostgreSQL hoặc chưa bỏ comment dòng `DATABASE_URL` trong `.env.local`. Chạy `pnpm db:up`, mở `.env.local` và bỏ dấu comment như hướng dẫn ở trên.

**pnpm install hoặc chạy lỗi vì phiên bản Node.** Repo yêu cầu Node từ 22.19 trở lên. Kiểm tra bằng `node -v`. Nếu thấp hơn, hãy nâng cấp Node rồi cài lại.

**Cổng 5432 đang bị chiếm.** Máy bạn có thể đang chạy một PostgreSQL khác. Dùng biến `OPENMAIC_DB_PORT` để đổi cổng, rồi sửa số cổng tương ứng trong `DATABASE_URL`. Hoặc dùng luôn PostgreSQL đó.

**Máy chủ báo lỗi cấu hình `openmaic.yml`.** README cho biết máy chủ kiểm tra file lúc khởi động và nêu tên trường sai, hoặc số dòng nếu YAML hỏng. Thường là thụt lề sai, hoặc slot trỏ tới nhà cung cấp bạn chưa khai báo key. Sửa đúng chỗ báo rồi chạy lại.

**Tạo bài giảng không được dù đã mở được trang.** Thường là key sai, hết hạn mức, hoặc mô hình ghi trong slot không có trong tài khoản của bạn. Kiểm tra lại key trong `.env.local` và tên mô hình trong `openmaic.yml`.

**Định đưa lên Vercel.** Hosting serverless chỉ hỗ trợ đến bản 1.1.x. Từ 1.2.0, việc tạo bài giảng chạy trong một tiến trình sống lâu trên máy chủ, nên cần Node.js chạy liên tục cùng PostgreSQL (Docker hoặc `pnpm start`).

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

**Điểm mạnh.** Giấy phép MIT, tự chạy trên máy mình. Hỗ trợ rất nhiều nhà cung cấp mô hình, kể cả mô hình chạy cục bộ. Xuất được `.pptx`, `.html` offline và ZIP nên không bị khoá vào một nơi. Dự án cập nhật đều, có nhiều bản vá bảo mật được ghi trong lịch sử phát hành.

**Giới hạn.** Bạn phải tự lo Node, pnpm, PostgreSQL (hoặc Docker) và API key, nên không phải ứng dụng bấm cài là xong. Chất lượng bài giảng phụ thuộc mô hình bạn chọn, và chi phí gọi API do bạn chịu. Bản Docker mặc định là cho một người dùng, muốn mở cho nhiều người phải tự thiết lập ACCESS_CODE và mật khẩu. Một số cập nhật là nâng cấp một chiều, nên cần đọc ghi chú phát hành trước khi nâng.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần vài slide nhanh một lần, một công cụ tạo slide có sẵn sẽ gọn hơn. Nếu bạn không có người hỗ trợ kỹ thuật và không quen terminal, hãy thử bản chạy Docker trước, hoặc nhờ một bạn kỹ thuật cài giúp. Nếu cần hệ thống nhiều người dùng với phân quyền, hãy đọc kỹ phần Hosting and identity trong tài liệu của repo trước khi quyết định.

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

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

Mã nguồn dùng giấy phép MIT nên bạn tải và chạy miễn phí. Tuy nhiên bạn cần API key của nhà cung cấp mô hình AI, và chi phí gọi API do bạn trả tuỳ nhà cung cấp. Bảng giá cụ thể repo không nêu.

### Cần GPU không?

Tư liệu không yêu cầu GPU. Mô hình AI được gọi qua API của nhà cung cấp mà bạn cấu hình. README có nhắc Ollama, Lemonade và FunASR cho trường hợp chạy cục bộ, nhưng phần yêu cầu phần cứng của các mục đó chưa có trong thông tin mình có.

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

README phần đã cung cấp không nêu rõ hệ điều hành hỗ trợ. Yêu cầu chỉ ghi Node.js từ 22.19, pnpm từ 10 và PostgreSQL 16. Có cả cách chạy bằng Docker Compose, thường tiện hơn nếu bạn không muốn cài từng thứ.

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

Key nằm trong file .env.local trên máy chủ của bạn, và khoá học lưu trong PostgreSQL do bạn quản lý. Bản Docker mặc định chỉ lắng nghe ở 127.0.0.1. Nếu mở cho máy khác, README yêu cầu đặt ACCESS_CODE dài ngẫu nhiên, nếu không ai tới được cổng cũng sửa và xoá được thư viện. Nội dung bạn gửi cho nhà cung cấp mô hình thì theo chính sách của họ.

### Có cần cài PostgreSQL riêng không?

Có, cần PostgreSQL 16 vì khoá học lưu trên máy chủ. Khi phát triển trên máy cá nhân, lệnh pnpm db:up dựng giúp một bản trong Docker. Không có DATABASE_URL thì máy chủ từ chối khởi động.

### Xuất bài giảng ra được những định dạng nào?

Theo README, bạn xuất được file .pptx giữ đủ các cảnh, một file .html offline phát cả bài học, hoặc ZIP lớp học để chuyển sang nơi triển khai khác.

### Có chạy được trên Vercel không?

Chỉ bản đến 1.1.x. Từ 1.2.0, việc tạo bài giảng chạy trong tiến trình sống lâu, nên cần Node.js chạy liên tục cùng PostgreSQL, bằng Docker hoặc pnpm start. Vercel và các host serverless khác không được hỗ trợ.
