OpenMAIC 로컬에서 돌리는 법

핵심 요약 (TL;DR)

이 글은 받아서 자기 기계에서 켜는 안내다. OpenMAIC(Open Multi-Agent Interactive Classroom)은 칭화대 THU-MAIC 팀의 오픈소스다. 주제를 넣거나 자료를 올리면, 여러 에이전트—역할이 나뉜 AI 선생님·조교가 장면을 나눠 만드는 프로그램—가 슬라이드·퀴즈·상호작용 장면이 있는 교실을 만든다. 라이선스는 MIT다. 이 글을 확인하는 시각 GitHub 스타는 29,820이다.

공식 Getting started가 말하는 최소 조건은 셋이다. Node.js 20.9.0 이상, pnpm 10.28.0, LLM 프로바이더 하나. 클라우드면 API 키가 필요하고, 로컬 Ollama나 Lemonade면 키가 없어도 된다. LLM은 Large Language Model, 즉 글을 읽고 쓰는 큰 언어 모델이다. 경로도 짧다. git clone → pnpm install → cp .env.example .env.local → 키/주소 넣기 → pnpm dev → http://localhost:3000. Docker는 docker compose up --build다.

단단한 한계를 먼저 적는다. OpenMAIC 자체는 Next.js 앱이다. 공식 Getting started·Deployment·Configuration 어디에도 OpenMAIC용 VRAM 숫자는 없다. GPU 메모리가 필요해지는 지점은 앱이 아니라, 붙인 로컬 모델(Ollama 등) 쪽이다. 그 숫자는 Ollama/모델 카드에서 봐야 한다. 또 저장소 package.json은 engines.node를 >=20.9.0으로 두고 packageManager는 [email protected]이다. 다만 열린 이슈 #1304는 일부 직접 의존성이 Node >=22.19.0을 요구한다고 적고, PR #1337이 그 바닥을 올리려 한다. 이 글은 아직 머지되지 않은 문서를 사실로 쓰지 않는다. 공식 Getting started 문장과, 그 이슈가 열려 있다는 사실만 적는다.

용어를 한 번만 풀어 둔다. pnpm은 Node 패키지 관리자다. 이 저장소는 버전을 10.28.0에 고정한다. Next.js는 React 기반 웹 프레임워크다. OpenMAIC는 Next.js 앱이다. 하네스는 에이전트가 도구·스킬·세션을 붙잡고 코스를 돌리는 실행 뼈대를 말한다(공식 사이트도 Harness라고 쓴다). MCP(Model Context Protocol)는 모델이 외부 도구·데이터에 붙는 규약이다. 이 저장소 package.json에 @modelcontextprotocol/sdk가 의존성으로 들어 있다.

배경 및 맥락

OpenMAIC는 “한 번의 클릭으로 몰입형 멀티 에이전트 학습”을 표방한다. 공식 데모·문서는 open.maic.chat에 있다. 2026년 8월 27일 README는 v1.0.0을 알렸다. 예전 원클릭 생성기 옆에 Pro workbench—채팅으로 커리큘럼을 짜고 페이지를 고치는 에이전트 작업대—가 붙었다. 세션을 서버에 남겨 재시작하고, 문서·오디오·영상을 올리고, 내장 스킬로 슬라이드·퀴즈·PBL(프로젝트 기반 학습)을 돌린다.

한국 쪽에서 눈에 들어온 계기는 트렌드다. TWMS 2026-09-01 GitHub 오늘 트렌드 톱10에서 OpenMAIC가 3위에 올랐다. 이 글은 그 뉴스 해설이 아니다. “로컬에서 돌리는 법” 검색어에 맞춰, 공식 문서에 적힌 설치·실행만 따라간다.

이걸로 할 수 있는 일

공식 Getting started가 열어 둔 첫 화면은 classroom generator다. 주제를 치거나 학습 자료를 올린 뒤 Generate를 누르면, AI 선생님들이 멀티 씬 교실을 만든다. 지원 형식은 고른 파서에 달렸고, 문서는 보통 PDF·Office·Markdown/텍스트·이미지·일부 오디오/비디오라고 적는다. 정확한 범위는 파서 문서를 보라.

README·사이트가 보여 주는 칸은 더 넓다. 슬라이드 수업, 퀴즈, 딥 인터랙티브(시뮬레이션·마인드맵·온라인 코딩), PBL, Pro 모드에서 에이전트와 대화하며 코스를 고치기, 선택적으로 MP4 내보내기·PostgreSQL 서버 지속성. 로컬 가이드의 핵심은 “그 앱을 내 포트 3000에 올리는 것”이다. 모델 품질·요금은 붙인 LLM 프로바이더에 달렸다.

필요한 것

아래 표는 공식 Getting started·Deployment·저장소 package.json에서 확인한 값이다. 없는 칸은 “문서에 없음”으로 적는다.

Configuration 문서가 나열한 LLM 접두사는 많다. OPENAI_, AZURE_OPENAI_, ANTHROPIC_, GOOGLE_, DEEPSEEK_, QWEN_, KIMI_, MINIMAX_, GLM_, SILICONFLOW_, DOUBAO_, OPENROUTER_, GROK_, TENCENT_, XIAOMI_/MIMO_, OLLAMA_, LEMONADE_ 등. 전부 켤 필요는 없다. “쓰는 것 하나만”이면 된다.

단계: 로컬 pnpm

1) 클론과 설치

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

Getting started는 첫 설치가 워크스페이스 패키지를 빌드해서 시간이 걸릴 수 있다고 적는다. package.json의 postinstall이 packages/ 아래 mathml·pptx·@openmaic/* 등을 이어서 빌드한다. 중간에 끊으면 나중에 PPTX·수식 쪽에서 이상한 오류가 날 수 있다. 공식 문장이 “시간이 걸린다”까지이고, 분 단위 숫자는 적지 않는다.

2) 환경 파일

cp .env.example .env.local

.env.local을 열고 쓰는 프로바이더만 채운다. Getting started 예시는 OPENAI_API_KEY 또는 ANTHROPIC_API_KEY, 또는 로컬 Ollama면 OLLAMA_BASE_URL=http://localhost:11434/v1 이다. 키 값 자체를 이 글에 박지 않는다. 공식 문서의 자리 표시를 그대로 따르면 된다.

로컬 Ollama·Lemonade는 Configuration이 API 키 없이 base URL만 서버 설정에 넣으면 SSRF 검증을 통과한다고 적는다. Docker 안에서 호스트 Ollama에 붙을 때는 Deployment가 host.docker.internal을 쓰라고 하고, Linux면 extra_hosts에 host.docker.internal:host-gateway가 보통 필요하다고 적는다. 사설망 주소를 허용하려면 ALLOW_LOCAL_NETWORKS=true 다.

선택 항목은 많다. TTS·ASR·이미지/비디오 생성·문서 파서·웹 검색·ACCESS_CODE(사이트 전체 암호)·DEFAULT_MODEL=provider:model-id 형식. 자세한 목록은 Configuration과 저장소 .env.example이다. 이 가이드는 “최소 하나”만 강제한다.

3) 개발 서버

pnpm dev

브라우저에서 http://localhost:3000 을 연다. 교실 생성기가 보이면, 주제를 넣고 Generate를 누르면 된다.

4) 프로덕션 빌드(선택)

pnpm build
pnpm start

Deployment의 셀프호스트 절도 같은 명령이다. 앞단에 nginx나 Caddy로 TLS를 붙이라고 적는다. 기본 교실 상태는 브라우저 IndexedDB에 남는다. 서버 쪽 지속성이 필요하면 PostgreSQL 프로필로 간다.

단계: Docker Compose

공식 추천은 Compose다. Deployment 문장 그대로다.

cp .env.example .env.local
# Edit .env.local and configure at least one LLM provider, then:
docker compose up --build

기본 Compose는 OpenMAIC 앱을 띄우고 openmaic-data 볼륨을 마운트한다. 이미지 단독 빌드도 문서에 있다.

docker build -t openmaic .
docker run --env-file .env.local -p 3000:3000 openmaic

Dockerfile은 내부적으로 Node.js 22를 쓴다. NEXT_PUBLIC_* 피처 플래그는 빌드 시점에 주입된다. 런타임 .env.local만 바꿔서는 안 먹고, Compose라면 빌드 arg로 넘겨야 한다.

문서 예시는 비디오 내보내기·실험적 PPTX 임포트다. NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true 와 NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true 를 앞에 두고 docker compose --profile video-export up --build 를 실행한다.

서버 지속성(PostgreSQL) 프로필은 Deployment가 이렇게 적는다. 먼저 .env.local에 DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic 과 PERSISTENCE_DEV_TOKEN=openmaic-local-dev 를 넣고, NEXT_PUBLIC_PERSISTENCE=1 과 NEXT_PUBLIC_PERSISTENCE_TOKEN=openmaic-local-dev 를 앞에 두고 docker compose --profile server-persistence up --build 한다.

문서는 PERSISTENCE_DEV_TOKEN이 로컬·신뢰 사설망용이며, 공개 프로덕션 인증으로 쓰면 안 된다고 못 박는다. Vercel 원클릭은 README Deploy 버튼 경로다. Vercel은 기본이 브라우저 쪽 지속성이고, 서버 지속성은 외부 PostgreSQL과 서버 배포가 필요하다고 적는다.

막히는 지점 / 왜 막히나

첫 층은 프로바이더 없음이다. 키도 로컬 base URL도 없으면 교실 생성이 돌지 않는다. Getting started가 “at least one”을 전제로 한다.

둘째는 로컬 모델과 SSRF 가드다. Docker 컨테이너 안의 localhost는 컨테이너 자신이다. 호스트 Ollama에 붙이려면 Deployment의 host.docker.internal 문장을 따른다. 사설망이 막히면 ALLOW_LOCAL_NETWORKS=true 를 본다.

셋째는 첫 설치·툴체인이다. pnpm install의 postinstall이 워크스페이스를 빌드한다. 공식은 “some time”이라고만 한다. Node 문서는 20.9.0+인데, 이슈 #1304와 PR #1337은 직접 의존성 바닥이 22.19.0일 수 있다고 주장한다. CI·Dockerfile·.nvmrc는 이미 22를 가리킨다고 이슈 본문이 적는다. Node 20만 쓰고 이상하면 그 이슈를 먼저 열어 보라.

넷째는 Windows 줄바꿈이다. 이슈 #1293은 core.autocrlf=true인 Windows 클린 체크아웃에서 pnpm check(Prettier)가 LF 정책과 충돌해 실패한다고 보고했고, 이후 닫혔다. 기여자 워크플로 이야기다. 앱 실행 자체의 필수 조건은 아니다.

다섯째는 피처 플래그 착각이다. NEXT_PUBLIC_* 는 빌드 타임이다. Docker에서 런타임 env만 바꾸고 기대한 UI가 안 보이면, Deployment의 build-arg / Compose profile 절을 다시 본다.

실사용자 반응

이 칸은 지어내지 않는다. 공개 이슈·트렌드만 옮긴다. TWMS 트렌드 글에서 OpenMAIC는 2026-09-01 기준 톱10 3위였다. 저장소 이슈 쪽은 설치 마찰과 품질 이슈가 섞여 있다. #1293(Windows CRLF·pnpm check, 닫힘), #1304(문서상 Node 20.9.0과 의존성 engines 불일치, 열림), #1277(커스텀 SiliconFlow 주소에서 Invalid JSON), #1295(Windows 경로에서 내장 스킬 로딩) 같은 티켓이 보인다. 별점 숫자나 “쉽다/어렵다” 여론을 지어내지 않는다. 공식 Discord·Feishu 커뮤니티 링크는 README에 있으나, 이 글이 그 안의 대화를 인용하지는 않는다.

의미와 시사점

로컬 LLM 가중치를 받는 글과, 로컬 교실 앱을 켜는 글은 다르다. GLM-Flash 가이드는 GiB와 서빙 엔진이 본체였다. OpenMAIC는 Node·pnpm·클라우드 자격 증명(또는 Ollama URL)이 본체다. 무거운 GPU가 “필수”라고 공식 문서가 말하지 않는다. 반대로, 교실 품질은 붙인 모델·파서·TTS에 그대로 묶인다. 무료 로컬만으로 가려면 Ollama/Lemonade 경로가 문서에 열려 있고, 클라우드 자격 증명 하나면 Getting started 경로가 열린다.

v1.0의 하네스·스킬·Pro workbench는 “한 번 Generate”를 넘어, 코스를 고치고 자료를 물리는 쪽으로 넓혔다. 로컬에 올리는 이유는 데이터가 밖으로 덜 나가게 하거나, 학교·팀 데모에 ACCESS_CODE를 걸거나, Docker로 재현 가능한 스택을 만들기 위해서다. 공개 데모만 필요하면 open.maic.chat을 쓰면 된다.

마치며

OpenMAIC를 로컬에서 돌리는 법은 공식 Getting started가 이미 짧게 적어 두었다. Node 20.9.0+, pnpm 10.28.0, LLM 하나. pnpm install → .env.local → pnpm dev → localhost:3000. Docker면 docker compose up --build. OpenMAIC 자체 VRAM 숫자는 공식 문서에 없다. Node 바닥이 곧 22.19로 올라갈지는 이슈 #1304·PR #1337을 보면 된다. 오늘은 문서에 있는 명령만 복사하면 된다.

출처

• GitHub: THU-MAIC/OpenMAIC (스타 29,820 · MIT · 이 글 확인 시각)
• 공식 사이트: open.maic.chat
• Getting started: docs/getting-started
• Deployment: docs/deployment
• Configuration: docs/configuration
• 저장소 package.json engines / packageManager (raw main)
• 이슈: #1304 · PR #1337 · #1293
• TWMS 트렌드: 2026-09-01 GitHub 오늘 트렌드 톱10

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.