Skip to main content

Windows 利用ガイド

更新 2026-08-13 4分で読めます GitHub で編集 ↗

Windows で MoAI-ADK を使う際に知っておくべき環境要件と、よくある落とし穴をまとめました。いちばん快適なのは WSL です。ネイティブ Windows 環境で遭遇するパス・権限の問題のほとんどは、WSL では発生しません。

MoAI-ADK は単一の Go バイナリなので Windows でも直接実行できますが、Claude Code が扱うシェルスクリプト・パス区切り文字・文字エンコーディングは Linux/macOS の慣行に従います。そのため Windows のコマンドプロンプト (cmd.exe) やレガシー PowerShell 5.x では、パス処理がずれたりフックスクリプトが失敗しやすくなります。WSL は Windows の中で Linux 環境をそのまま使わせてくれ、この隔たりを一気に無くしてくれます。

このページは WSL のインストールからプロジェクトを開くところ、(オプションで) CG モードの構成までをひとつの流れで案内します。すでに WSL をお使いなら moai-adk のインストール手順 から直接始めてもかまいません。

サポート環境

環境サポート状況備考
WSL (推奨) 完全サポート最適な体験
PowerShell 7.x+ サポート代替環境
PowerShell 5.x (レガシー) 非サポートWindows PowerShell
cmd.exe 非サポートコマンドプロンプト

必須要件:

  • Git for Windows のインストール必須
  • WSL または PowerShell 7.x 以上

インストール方法

WSL (推奨)

WSL は Windows 上で Linux 環境を提供し、MoAI-ADK のすべての機能を完全にサポートします。

bash 
# WSL のインストール (管理者 PowerShell で実行)
wsl --install

# WSL 内で MoAI-ADK をインストール
curl -fsSL https://adk.mo.ai.kr/install.sh \
  | bash

PowerShell 7.x+

参考: 最適な体験のために WSL の利用を推奨します。

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

非 ASCII ユーザー名のパスエラー

問題の症状

Windows のユーザー名に日本語、韓国語、中国語などの非 ASCII 文字が含まれる場合、EINVAL エラーが発生することがあります。これは Windows の 8.3 短縮ファイル名変換の過程で発生する問題です。

text 
Error: EINVAL: invalid argument, open 'C:\Users\山田太郎\AppData\Local\Temp\...'

解決方法 1: 代替一時ディレクトリの設定 (推奨)

ASCII 文字のみを含むパスに一時ディレクトリを作成します:

bash 
# Command Prompt
set MOAI_TEMP_DIR=C:\temp
mkdir C:\temp 2>/dev/null
powershell 
# PowerShell
$env:MOAI_TEMP_DIR="C:\temp"
New-Item -ItemType Directory -Path "C:\temp" -Force

環境変数を恒久的に設定するには、システム環境変数に MOAI_TEMP_DIR を追加してください。

解決方法 2: 8.3 ファイル名生成の無効化

管理者権限で実行:

bash 
fsutil 8dot3name set 1

注意: この設定はシステム全体に影響します。一部のレガシープログラムに影響が及ぶ可能性があります。

解決方法 3: ASCII ユーザーアカウントの作成

英語名で新しい Windows ユーザーアカウントを作成すれば、パス問題を根本的に解決できます。

WSL セットアップガイド

WSL のインストール

powershell 
# 管理者 PowerShell で実行
wsl --install

# 既定ディストリビューション: Ubuntu (推奨)
# 再起動後、ユーザー名とパスワードを設定

プロジェクトファイルへのアクセス

WSL から Windows のファイルにアクセス:

bash 
# Windows ファイルシステムへのアクセス
cd /mnt/c/Users/ユーザー名/projects/

# WSL ネイティブファイルシステムを使用 (より高速)
cd ~/projects/

パフォーマンスのヒント: WSL ネイティブファイルシステム(~/ 配下)で作業すると、クロスファイルシステムのオーバーヘッドなしに最適なパフォーマンスが得られます。

VS Code 連携

  1. VS Code に WSL 拡張機能 をインストール
  2. WSL ターミナルで code . を実行
  3. VS Code が自動的に WSL モードで開く

CG モードでの tmux 利用

CG モードを使うには tmux が必要です。WSL でのインストール:

bash 
# Ubuntu/Debian
sudo apt install tmux

# tmux セッションの開始
tmux new -s moai

# CG モードの実行
moai cg

トラブルシューティング

問題原因解決
moai: command not foundPATH に Go bin ディレクトリが未登録export PATH="$HOME/go/bin:$PATH" を .bashrc に追加
EINVAL エラー非 ASCII ユーザー名上記の 非 ASCII ユーザー名のパスエラー を参照
権限拒否インストールスクリプトの権限chmod +x install.sh の後に再実行
Git コマンドの失敗Git for Windows 未インストールGit for Windows をインストール
tmux がないCG モードを実行できないsudo apt install tmux (WSL で)

次のステップ