安装
了解如何在您的系统上安装 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)
系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS、Linux、Windows (Git Bash / WSL) |
| 架构 | amd64、arm64 |
| 内存 | 最低 4GB RAM |
| 磁盘 | 最低 100MB 可用空间 |
安装方法
方法 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/) 中创建项目可获得 2-5 倍的 I/O 性能提升。访问 Windows 文件系统 (/mnt/c/) 可能导致性能下降。
WSL 最佳实践
- 使用 Linux 文件系统: 在
~/projects/目录中创建项目 - 配置 Git 凭据: 在 WSL 中独立于 Windows 配置 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更新 Shell 配置
# 添加到 ~/.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。