openmaic-classroom

$27

Installation

git clone https://github.com/THU-MAIC/OpenMAIC.git

cd OpenMAIC

pnpm install

Environment Configuration

cp .env.example .env.local

Edit .env.local — at minimum one LLM provider key is required:

# LLM Providers (configure at least one)

OPENAI_API_KEY=$OPENAI_API_KEY

ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY

GOOGLE_API_KEY=$GOOGLE_API_KEY

# Recommended default model (Gemini 3 Flash = best speed/quality balance)

DEFAULT_MODEL=google:gemini-3-flash-preview

# Optional: MinerU for advanced PDF/table/formula parsing

PDF_MINERU_BASE_URL=https://mineru.net

PDF_MINERU_API_KEY=$MINERU_API_KEY

# Optional: access code for hosted mode

ACCESS_CODE=$OPENMAIC_ACCESS_CODE

Provider Config via YAML (alternative to env vars)

Create server-providers.yml in the project root:

providers:

  openai:

    apiKey: $OPENAI_API_KEY

  anthropic:

    apiKey: $ANTHROPIC_API_KEY

  google:

    apiKey: $GOOGLE_API_KEY

  deepseek:

    apiKey: $DEEPSEEK_API_KEY

  # Any OpenAI-compatible endpoint

  custom:

    baseURL: https://your-proxy.example.com/v1

    apiKey: $CUSTOM_API_KEY

Running the App

# Development

pnpm dev

# → http://localhost:3000

# Production build

pnpm build && pnpm start

# Type checking

pnpm tsc --noEmit

# Linting

pnpm lint

Docker Deployment

cp .env.example .env.local

# Edit .env.local with your API keys

docker compose up --build

# → http://localhost:3000

Vercel Deployment

# Fork the repo, then import at https://vercel.com/new

# Set env vars in Vercel dashboard:

#   OPENAI_API_KEY or ANTHROPIC_API_KEY or GOOGLE_API_KEY

#   DEFAULT_MODEL (optional, e.g. google:gemini-3-flash-preview)

One-click deploy button is available in the README; it pre-fills env var descriptions automatically.

Lesson Generation Pipeline

OpenMAIC uses a two-stage pipeline:

Stage

Description

Outline

AI analyzes topic/document and produces a structured lesson outline

Scenes

Each outline item is expanded into a typed scene: slides, quiz, interactive, or pbl

Scene Types

Type

Description

slides

AI teacher lectures with TTS narration, spotlight, laser pointer

quiz

Single/multiple choice or short-answer with AI grading

interactive

HTML-based simulation (physics, flowcharts, etc.)

pbl

Project-Based Learning — choose a role, collaborate with agents

API Usage — Generating a Classroom

REST: Start Generation Job

// POST /api/generate

const response = await fetch('/api/generate', {

  method: 'POST',

  headers: { 'Content-Type': 'application/json' },

  body: JSON.stringify({

    topic: 'Quantum Entanglement',

    // Optional: attach document content

    document: markdownString,

    // Optional: model override

    model: 'google:gemini-3-flash-preview',

  }),

});

const { jobId } = await response.json();

REST: Poll Job Status

// GET /api/generate/status?jobId=<jobId>

const poll = async (jobId: string) => {

  while (true) {

    const res = await fetch(`/api/generate/status?jobId=${jobId}`);

    const data = await res.json();

    if (data.status === 'completed') {

      console.log('Classroom URL:', data.classroomUrl);

      break;

    }

    if (data.status === 'failed') {

      throw new Error(data.error);

    }

    // status === 'pending' | 'running'

    await new Promise(r => setTimeout(r, 3000));

  }

};

REST: Export Slides

// GET /api/export/pptx?classroomId=<id>

const exportPptx = async (classroomId: string) => {

  const res = await fetch(`/api/export/pptx?classroomId=${classroomId}`);

  const blob = await res.blob();

  const url = URL.createObjectURL(blob);

  // trigger download

  const a = document.createElement('a');

  a.href = url;

  a.download = 'lesson.pptx';

  a.click();

};

// GET /api/export/html?classroomId=<id>

const exportHtml = async (classroomId: string) => {

  const res = await fetch(`/api/export/html?classroomId=${classroomId}`);

  const html = await res.text();

  return html;

};

OpenClaw Integration

OpenMAIC ships a skill for OpenClaw, enabling classroom generation from Feishu, Slack, Discord, Telegram, etc.

Install the Skill

# Via ClawHub (recommended)

clawhub install openmaic

# Manual install

mkdir -p ~/.openclaw/skills

cp -R /path/to/OpenMAIC/skills/openmaic ~/.openclaw/skills/openmaic

Configure OpenClaw

Edit ~/.openclaw/openclaw.json:

{

  "skills": {

    "entries": {

      "openmaic": {

        "config": {

          // Hosted mode — get access code from https://open.maic.chat/

          "accessCode": "$OPENMAIC_ACCESS_CODE",

          // Self-hosted mode — local repo + server URL

          "repoDir": "/path/to/OpenMAIC",

          "url": "http://localhost:3000"

        }

      }

    }

  }

}

OpenClaw Skill Lifecycle

Phase

What Happens

Clone

Detect existing checkout or clone fresh

Startup

Choose pnpm dev, pnpm build && pnpm start, or Docker

Provider Keys

Guide user to edit .env.local

Generation

Submit async job, poll, return classroom link

Custom Scene Development Pattern

Scenes are typed React components. To add a new scene type:

// types/scene.ts

export type SceneType = 'slides' | 'quiz' | 'interactive' | 'pbl' | 'custom';

export interface CustomScene {

  type: 'custom';

  title: string;

  content: string;

  // your fields

  metadata: Record<string, unknown>;

}

// components/scenes/CustomScene.tsx

'use client';

import { type CustomScene } from '@/types/scene';

interface Props {

  scene: CustomScene;

  onComplete: () => void;

}

export function CustomSceneComponent({ scene, onComplete }: Props) {

  return (

    <div className="flex flex-col gap-4 p-6">

      <h2 className="text-2xl font-bold">{scene.title}</h2>

      <div dangerouslySetInnerHTML={{ __html: scene.content }} />

      <button

        className="mt-4 rounded-lg bg-blue-600 px-6 py-2 text-white"

        onClick={onComplete}

      >

        Continue

      </button>

    </div>

  );

}

Multi-Agent Interaction Modes

Mode

Trigger

Description

Classroom Discussion

Automatic

Agents proactively start discussions; user can jump in or get called on

Roundtable Debate

Scene config

Multiple agent personas debate a topic with whiteboard illustrations

Q&A

User asks question

AI teacher responds with slides, diagrams, or whiteboard drawings

Whiteboard

During any scene

Agents draw equations, flowcharts, or concept diagrams in real time

MinerU Advanced Document Parsing

For complex PDFs with tables, formulas, or scanned images:

# Use MinerU hosted API

PDF_MINERU_BASE_URL=https://mineru.net

PDF_MINERU_API_KEY=$MINERU_API_KEY

# Or self-hosted MinerU instance (Docker)

PDF_MINERU_BASE_URL=http://localhost:8888

Without MinerU, OpenMAIC falls back to standard PDF text extraction.

Supported LLM Providers & Model Strings

// Model string format: "provider:model-name"

const models = {

  // Google (recommended)

  geminiFlash: 'google:gemini-3-flash-preview',   // best speed/quality

  geminiPro: 'google:gemini-3.1-pro',             // highest quality

  // OpenAI

  gpt4o: 'openai:gpt-4o',

  gpt4oMini: 'openai:gpt-4o-mini',

  // Anthropic

  claude4Sonnet: 'anthropic:claude-sonnet-4-5',

  claude4Haiku: 'anthropic:claude-haiku-4-5',

  // DeepSeek

  deepseekChat: 'deepseek:deepseek-chat',

  // OpenAI-compatible (custom base URL)

  custom: 'custom:your-model-name',

};

Export Formats

Format

Endpoint

Notes

PowerPoint .pptx

GET /api/export/pptx?classroomId=

Fully editable slides

Interactive .html

GET /api/export/html?classroomId=

Self-contained HTML page

Common Patterns

Generate a Classroom from a Document String

const generateFromDocument = async (markdownContent: string, topic: string) => {

  const res = await fetch('/api/generate', {

    method: 'POST',

    headers: { 'Content-Type': 'application/json' },

    body: JSON.stringify({

      topic,

      document: markdownContent,

      model: process.env.DEFAULT_MODEL ?? 'google:gemini-3-flash-preview',

    }),

  });

  const { jobId } = await res.json();

  // Poll until done

  let classroomUrl: string | null = null;

  while (!classroomUrl) {

    await new Promise(r => setTimeout(r, 4000));

    const status = await fetch(`/api/generate/status?jobId=${jobId}`).then(r => r.json());

    if (status.status === 'completed') classroomUrl = status.classroomUrl;

    if (status.status === 'failed') throw new Error(status.error);

  }

  return classroomUrl;

};

Check Provider Health

// GET /api/providers

const checkProviders = async () => {

  const res = await fetch('/api/providers');

  const { providers } = await res.json();

  // providers: Array<{ name: string; available: boolean; models: string[] }>

  return providers.filter((p: { available: boolean }) => p.available);

};

Troubleshooting

Problem

Solution

No LLM provider configured

Set at least one of OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY in .env.local

Generation hangs at outline stage

Check API key quota; try switching to google:gemini-3-flash-preview for higher rate limits

TTS not working

TTS requires a browser with Web Speech API support; check browser console for errors

PDF parsing produces garbled text

Enable MinerU by setting PDF_MINERU_BASE_URL in .env.local

Vercel timeout during generation

Increase function timeout in vercel.json; generation is async so the API should return a jobId immediately

Docker build fails

Ensure DOCKER_BUILDKIT=1 and that .env.local exists before running docker compose up --build

OpenClaw skill not found

Run clawhub install openmaic or manually copy skills/openmaic to ~/.openclaw/skills/

pnpm install fails on Node < 20

Upgrade Node.js to >= 20 (nvm use 20)

Port 3000 already in use

Set PORT=3001 in .env.local or run PORT=3001 pnpm dev

Key File Structure

OpenMAIC/

├── app/                    # Next.js App Router pages & API routes

│   ├── api/

│   │   ├── generate/       # POST lesson generation, GET status

│   │   ├── export/         # pptx / html export endpoints

│   │   └── providers/      # LLM provider health check

│   └── classroom/          # Classroom viewer pages

├── components/

│   ├── scenes/             # Slide, Quiz, Interactive, PBL components

│   ├── whiteboard/         # Real-time whiteboard rendering

│   └── agents/             # Agent avatar & TTS components

├── lib/

│   ├── agents/             # LangGraph agent graph definitions

│   ├── providers/          # LLM provider abstractions

│   └── generation/         # Outline + scene generation pipeline

├── skills/

│   └── openmaic/           # OpenClaw skill definition

├── server-providers.yml    # Optional YAML provider config

├── .env.example            # Environment variable template

└── docker-compose.yml      # Docker deployment config