インストール
MoAI-ADK 2.x をシステムにインストールする方法を説明します。
前提条件
インストール前に以下を確認してください:
1. Claude Code
MoAI-ADK は Claude Code 上で動作する拡張フレームワークです。先に Claude Code がインストールされている必要があります。
claude --versionまだインストールしていない場合は、Claude Code 公式ドキュメント を参照してください。
2. Git (必須)
MoAI-ADK は Git ベースのワークフローを使用します。システムに Git がインストールされている必要があります。
git --versionWindows ユーザー: Git Bash または WSL 環境で使用してください。コマンドプロンプト (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)
システム要件
| 項目 | 要件 |
|---|---|
| OS | macOS、Linux、Windows (Git Bash / WSL) |
| アーキテクチャ | amd64、arm64 |
| メモリ | 最小 4GB RAM |
| ディスク | 最小 100MB の空き容量 |
インストール方法
方法 1: クイックインストール (推奨)
1 つのコマンドで最新バージョンを自動インストールします。
macOS / Linux / WSL / Git Bash:
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iexインストールスクリプトは自動的にプラットフォームを検出し、GitHub からプリビルドバイナリをダウンロードし、SHA256 チェックサムを検証し、PATH を設定します。Python や別途のランタイムは不要です。
インストール後に確認します:
moai versionインストールオプション
# 特定バージョンをインストール
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash -s -- --version 2.0.0
# カスタムディレクトリにインストール
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash -s -- --install-dir /usr/local/bin方法 2: ソースからビルド
Go 開発環境がある場合、ソースから直接ビルドできます。
git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk
make buildビルドされたバイナリは ./bin/moai に生成されます。PATH が通ったディレクトリにコピーしてください:
cp ./bin/moai ~/.local/bin/インストール場所
インストールスクリプトは以下の順序でインストールディレクトリを決定します:
| プラットフォーム | 優先順位 |
|---|---|
| macOS / Linux | $GOBIN → $GOPATH/bin → ~/.local/bin |
| Windows | %LOCALAPPDATA%\Programs\moai |
1.x からのマイグレーション
MoAI-ADK 1.x (Python 版) ユーザーは、必ず既存バージョンを先にアンインストールしてください。
1.x と 2.x は同じ moai コマンドを使用するため、古いバージョンが残っていると競合が発生します。
ステップ 1: 既存の 1.x を削除
# uv でインストールした場合
uv tool uninstall moai-adk
# pip でインストールした場合
pip uninstall moai-adkステップ 2: 既存設定のバックアップ (任意)
# 既存の設定をバックアップしたい場合
cp -r ~/.moai ~/.moai-v1-backupステップ 3: 2.x をインストール
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bashステップ 4: インストール確認
moai version
# 出力例: moai v2.x.x (commit: abc1234, built: 2026-01-15)2.x は単一の Go バイナリで、Python ランタイムや仮想環境は不要です。起動時間が約 800ms から約 5ms に大幅に改善されました。
WSL サポート
Windows での WSL (Windows Subsystem for Linux) 環境における MoAI-ADK のインストールと使用方法を説明します。
WSL のインストール
WSL がインストールされていない場合、PowerShell (管理者権限) で以下のコマンドを実行してください:
wsl --installインストール後、Windows を再起動すると Ubuntu が自動的にインストールされます。
WSL での MoAI-ADK インストール
WSL ターミナルで Linux と同じコマンドを使用します:
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bashパス処理
Windows パスと WSL パスを区別する必要があります:
| Windows パス | WSL パス |
|---|---|
C:\Users\name\project | /mnt/c/Users/name/project |
D:\Projects\myapp | /mnt/d/Projects/myapp |
推奨: WSL の Linux ファイルシステム (~/projects/) にプロジェクトを作成すると、I/O パフォーマンスが 2-5 倍向上します。Windows ファイルシステム (/mnt/c/) へのアクセスはパフォーマンスが低下する可能性があります。
WSL ベストプラクティス
- Linux ファイルシステムを使用: プロジェクトは
~/projects/ディレクトリに作成 - Git 認証情報の設定: Windows とは別に WSL で Git 認証情報を構成
- 推奨ターミナル: Windows Terminal を使用して複数の WSL ディストリビューションを管理
WSL トラブルシューティング
PATH が読み込まれない
# ~/.bashrc または ~/.zshrc に追加
source ~/.cargo/env
export PATH="$HOME/.local/bin:$PATH"フック/MCP サーバーの実行権限問題
# 実行権限を付与
chmod +x ~/.claude/hooks/moai/*.shWindows パスアクセスの遅延
プロジェクトを Linux ファイルシステムに移動してください:
# Windows から WSL に移動
cp -r /mnt/c/Users/name/project ~/projects/
cd ~/projects/projectpip と uv ツールの競合
MoAI-ADK 1.x (Python 版) ユーザーが直面する一般的な問題です。
問題の説明
pip と uv は異なる場所にパッケージをインストールします。両方のツールを併用すると、moai コマンドが予期しないバージョンを実行する可能性があります。
症状
moai versionを実行すると 1.x バージョンが表示されるcommand not found: moaiエラーが発生which moaiと異なるパスから実行される
原因
- pip はシステム Python パスにインストール
- uv tool は
~/.local/binまたは~/.cargo/binにインストール - 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://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash
# 4. 確認
moai versionシェル設定の更新
# ~/.bashrc または ~/.zshrc に追加
export PATH="$HOME/.local/bin:$PATH"
# 設定を適用
source ~/.bashrc # または source ~/.zshrc予防策
- MoAI-ADK 2.x は Python に依存しない Go バイナリです
- 2.x をインストールする前に 1.x (Python 版) をアンインストールしてください
- pip と uv tool を同時に使用しないでください
トラブルシューティング
問題: コマンドが見つからない
command not found: moai解決策:
- ターミナルを再起動してください
- PATH を確認してください:
echo $PATH- バイナリの場所を確認してください:
which moai || ls ~/.local/bin/moai- PATH に手動で追加してください:
# Bash/Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc問題: 権限エラー
Permission denied解決策:
chmod +x ~/.local/bin/moai問題: 1.x と 2.x の競合
古いバージョンの 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 --config
moai update -c
# バックアップなしで強制アップデート
moai update --force
# 自動承認モード (すべての確認を自動承認)
moai update --yesマージ戦略
# 自動マージを強制 (デフォルト)
moai update --merge
# 手動マージを強制
moai update --manual自動保存項目: ユーザー設定、カスタムエージェント、カスタムコマンド、カスタムスキル、カスタムフック、SPEC ドキュメント、レポートはアップデート時に自動的に保存されます。
詳細はアップデートガイド を参照してください。
アンインストール
MoAI-ADK を完全に削除するには:
# バイナリを削除
rm $(which moai)
# 設定ディレクトリを削除 (任意)
rm -rf ~/.moai次のステップ
初期セットアップウィザードで MoAI-ADK の設定方法を学んでください。