설치

MoAI-ADK를 시스템에 설치하는 방법을 안내합니다. 설치되는 것은 Go로 빌드한 단일 바이너리 하나뿐입니다. Python도, 가상환경도, 패키지 매니저도 필요 없습니다.

MoAI-ADK v3.1.3 이상은 Apache-2.0 라이선스로 배포됩니다.

상업적 사용, 수정, 배포가 자유로우며, 소스 코드 공개 의무가 없습니다. 자세한 내용은 Apache License 2.0을 참조하세요.

정보

참고: MoAI-ADK 1.x (Python 버전)은 GPL-3.0 라이선스였습니다. v2.0.0에서 Go로 재작성하면서 Apache-2.0으로 바꿨습니다.

설치 전 다음 항목을 확인하세요:

MoAI-ADK는 Claude Code 위에서 동작하는 확장 프레임워크입니다. 먼저 Claude Code가 설치되어 있어야 합니다.

claude --version

아직 설치하지 않았다면 Claude Code 공식 문서를 참조하세요.

MoAI-ADK는 Git 기반 워크플로우를 사용합니다. 시스템에 Git이 설치되어 있어야 합니다.

git --version

주의

Windows 사용자: 반드시 Git Bash 또는 WSL 환경에서 사용하세요. Command Prompt (cmd.exe)는 지원하지 않습니다.

Git이 설치되어 있지 않다면:

• Windows: git-scm.com에서 Git for Windows를 설치하세요. Git Bash가 함께 설치됩니다.
• macOS: xcode-select --install 또는 git-scm.com
• Linux: sudo apt install git (Ubuntu/Debian) 또는 sudo dnf install git (Fedora)

MoAI-ADK 는 두 가지 경로로 설치할 수 있습니다. 대부분의 사용자는 한 줄 설치 스크립트로 충분하고, Go 개발 환경이 이미 있거나 특정 버전을 직접 빌드해야 하는 경우에는 소스 빌드를 씁니다.

flowchart TD
    A["설치 시작"] --> B{"Go 환경이 있고
특정 빌드가 필요?"}
    B -->|아니오| C["방법 1: 빠른 설치
(install.sh / install.ps1)"]
    B -->|예| D["방법 2: 소스 빌드
(make build)"]
    C --> E["moai version 으로 확인"]
    D --> E
    style C fill:#cc785c,color:#fff

하나의 명령어로 최신 버전을 자동 설치합니다.

macOS / Linux / WSL / Git Bash:

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

Windows (PowerShell):

irm https://adk.mo.ai.kr/install.ps1 | iex

정보

설치 스크립트는 자동으로 플랫폼을 감지하고, GitHub에서 사전 빌드된 바이너리를 다운로드하며, SHA256 체크섬을 검증하고, PATH를 설정합니다. Python이나 별도의 런타임은 필요하지 않습니다.

설치가 완료되면 확인하세요:

moai version

# 특정 버전 설치 (원하는 릴리스 태그 지정)
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --version <릴리스-태그>

# 커스텀 디렉터리에 설치
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --install-dir /usr/local/bin

정보

MoAI-ADK 설치 후에는 moai update --version <tag>로 다른 릴리스 태그(stable, rc, 이전 버전)로 인프로세스 전환할 수 있습니다. 자세한 내용은 Update — 특정 버전 설치를 참고하세요.

Go 개발 환경이 있는 경우 소스에서 직접 빌드할 수 있습니다.

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk
make build

빌드한 바이너리는 ./bin/moai에 생깁니다. PATH에 잡혀 있는 위치로 복사하세요:

cp ./bin/moai ~/.local/bin/

설치 스크립트는 다음 순서로 설치 디렉터리를 결정합니다:

경고

MoAI-ADK 1.x (Python 버전) 사용자는 반드시 먼저 기존 버전을 제거하세요.

1.x와 2.x는 같은 moai 명령어를 쓰기 때문에, 기존 버전이 남아 있으면 서로 충돌합니다.

# uv로 설치한 경우
uv tool uninstall moai-adk

# pip로 설치한 경우
pip uninstall moai-adk

# 기존 설정을 백업하고 싶다면
cp -r ~/.moai ~/.moai-v1-backup

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

moai version

╭────────────────────────╮
│                        │
│    moai-adk v3.0.0     │
│                        │
│                        │
╰────────────────────────╯
 v3.0.0   none   built unknown

정보

Go 에디션 (v2.0+) 은 단일 바이너리라 Python 런타임도, 가상환경도 필요하지 않습니다. 시작 시간은 약 800ms에서 5ms로 줄었습니다.

Windows 사용자를 위해 WSL(Windows Subsystem for Linux) 환경에서 설치하고 사용하는 방법을 안내합니다.

WSL이 설치되어 있지 않다면, PowerShell (관리자 권한)에서 다음 명령어를 실행하세요:

wsl --install

설치 후 Windows를 재시작하면 Ubuntu가 자동으로 설치됩니다.

WSL 터미널에서 Linux와 동일한 명령어를 사용합니다:

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

WSL에서는 Windows 경로와 WSL 경로를 구분해야 합니다:

정보

권장: WSL의 Linux 파일시스템 (~/projects/)에 프로젝트를 만들면 I/O 성능이 2-5배 빨라집니다. Windows 파일시스템 (/mnt/c/)을 오가면 오히려 느려질 수 있습니다.

1. Linux 파일시스템 사용: 프로젝트는 ~/projects/ 디렉터리에 만들기
2. Git 자격증명 설정: Windows와는 별도로 WSL에서 Git 자격증명 구성하기
3. 터미널 권장: Windows Terminal로 여러 WSL 배포판 관리하기

# ~/.bashrc 또는 ~/.zshrc에 추가
source ~/.cargo/env
export PATH="$HOME/.local/bin:$PATH"

# 실행 권한 부여
chmod +x ~/.claude/hooks/moai/*.sh

Linux 파일시스템으로 프로젝트를 이동하세요:

# Windows에서 WSL로 이동
cp -r /mnt/c/Users/name/project ~/projects/
cd ~/projects/project

MoAI-ADK 1.x (Python 버전) 사용자가 자주 겪는 문제입니다.

pip와 uv는 패키지를 서로 다른 위치에 설치합니다. 두 도구를 섞어 쓰면 moai 명령어가 엉뚱한 버전을 실행할 수 있습니다.

• moai version을 실행했을 때 1.x 버전이 표시됨
• command not found: moai 오류 발생
• which moai와 다른 경로에서 실행됨

1. pip는 시스템 Python 경로에 설치
2. uv tool은 ~/.local/bin 또는 ~/.cargo/bin에 설치
3. PATH 순서에 따라 다른 버전이 실행됨

# 1. 모든 기존 버전 제거
uv tool uninstall moai-adk 2>/dev/null || true
pip uninstall moai-adk -y 2>/dev/null || true

# 2. 남은 바이너리 확인 및 삭제
which moai && rm $(which moai) 2>/dev/null || true
ls ~/.local/bin/moai && rm ~/.local/bin/moai 2>/dev/null || true

# 3. 2.x 설치
curl -fsSL https://adk.mo.ai.kr/install.sh | bash

# 4. 확인
moai version

# ~/.bashrc 또는 ~/.zshrc에 추가
export PATH="$HOME/.local/bin:$PATH"

# 설정 적용
source ~/.bashrc  # 또는 source ~/.zshrc

1. MoAI-ADK 2.x는 Python과 무관한 Go 바이너리입니다
2. 1.x (Python 버전)를 제거한 후 2.x를 설치하세요
3. pip와 uv tool을 동시에 사용하지 마세요

command not found: moai

해결 방법:

1. 터미널을 재시작하세요
2. PATH 설정을 확인하세요:

echo $PATH

3. 바이너리가 설치된 위치를 확인하세요:

which moai || ls ~/.local/bin/moai

4. PATH에 수동으로 추가하세요:

# Bash/Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission denied

해결 방법:

chmod +x ~/.local/bin/moai

이전 버전의 moai 명령이 실행되는 경우:

# 어떤 moai가 실행되는지 확인
which moai

# 1.x가 남아있다면 제거
uv tool uninstall moai-adk
# 또는
pip uninstall moai-adk

# 터미널 재시작 후 2.x 확인
moai version

설치가 완료되면 프로젝트를 초기화하세요:

moai init my-project

cd my-existing-project
moai init

최신 버전으로 업그레이드하려면:

moai update

# 버전 확인만 (업데이트 안 함)
moai update --check

# 템플릿 동기화만 (바이너리 업데이트 건너뜀)
moai update --templates-only

# 설정 편집 모드 (초기화 마법사 다시 실행)
moai update -c

# 강제 업데이트 (사용자 변경 사항은 백업 후 덮어쓰기)
moai update --force

# 자동 승인 모드 (CI/CD)
moai update --yes

정보

자동 보존 항목: 사용자 설정, 커스텀 에이전트, 커스텀 명령어, 커스텀 스킬, 커스텀 훅, SPEC 문서, 보고서는 업데이트 시 자동으로 보존됩니다. 사용자가 수정한 템플릿 파일은 백업 후 3-way 병합됩니다.

자세한 내용은 업데이트 가이드를 참조하세요.

MoAI-ADK를 완전히 지우려면 바이너리와 설정 디렉터리를 삭제하세요:

# 바이너리 삭제 (which moai 결과로 삭제)
rm "$(which moai)"

# 설정 디렉토리 삭제 (선택사항)
rm -rf "$HOME/.moai"

초기 설정 마법사에서 MoAI-ADK 구성 방법을 알아보세요.