CLI 参考
参考 MoAI-ADK 命令行界面的所有命令和选项。
命令列表
moai --help输出示例:
MoAI-ADK - Agentic Development Kit for Claude Code
Usage:
moai [command]
Available Commands:
init Interactive project setup (auto-detects language/framework/methodology)
doctor System health diagnosis and environment verification
status Project status summary including Git branch, quality metrics, etc.
update Update to the latest version (with automatic rollback support)
worktree Manage Git worktrees for parallel SPEC development
hook Claude Code hook dispatcher
glm Switch to GLM backend (cost-effective) or update API key
claude Switch to Claude backend (Anthropic API)
version Display version, commit hash, and build date
Flags:
-h, --help help for moai
-v, --version version for moai| 命令 | 描述 |
|---|---|
moai init | 项目初始化 (自动检测语言/框架/方法论) |
moai doctor | 系统诊断和环境验证 |
moai status | 项目状态概览 (Git 分支、质量指标等) |
moai update | 更新到最新版本 (支持自动回滚) |
moai worktree | Git worktree 管理 (并行 SPEC 开发) |
moai hook | Claude Code 钩子调度器 |
moai glm | 切换到 GLM 后端 (--team: GLM Worker 模式) |
moai claude、moai cc | 切换到 Claude 后端 |
moai cg | 启用 CG 模式 — Claude 领导 + GLM 团队成员 (需要 tmux) |
moai version | 显示版本、提交哈希、构建日期 |
moai init
初始化项目。
moai init [PATH] [OPTIONS]选项
| 选项 | 描述 |
|---|---|
-y, --non-interactive | 非交互模式 (使用默认值) |
--mode [personal|team] | 项目模式 |
--locale [ko|en|ja|zh] | 首选语言 (默认: en) |
--language TEXT | 编程语言 (如果指定则自动检测) |
--force | 强制重新初始化而无需确认 |
示例
# 初始化新项目
moai init my-project
# 韩语、团队模式
moai init my-project --locale ko --mode team
# Python 项目
moai init --language pythonmoai update
将 MoAI-ADK 更新到最新版本。
moai update [OPTIONS]选项
| 选项 | 描述 |
|---|---|
--path PATH | 项目路径 (默认: 当前目录) |
--force | 强制更新而不备份 |
--check | 仅检查版本 (不更新) |
--project | 仅同步项目模板 |
--templates-only | 仅同步模板 (跳过包升级) |
--yes | 自动确认 (CI/CD 模式) |
-c, --config | 编辑项目配置 (与初始设置向导相同) |
--merge | 自动合并 (保留用户更改) |
--manual | 手动合并 (创建指南) |
示例
# 检查更新
moai update --check
# 强制更新
moai update --force
# 自动合并
moai update --merge重要: --force 选项不创建备份。用户更改可能会丢失。
moai doctor
运行系统诊断。
moai doctor [OPTIONS]选项
| 选项 | 描述 |
|---|---|
-v, --verbose | 显示详细的工具版本和语言检测 |
--fix | 为缺失的工具建议修复 |
--export PATH | 导出到 JSON 文件 |
--check TEXT | 仅检查特定工具 |
--check-commands | 诊断斜杠命令加载问题 |
--shell | 诊断 shell 和 PATH 配置 (WSL/Linux) |
示例
# 完整诊断
moai doctor
# 详细诊断
moai doctor --verbose
# 建议修复
moai doctor --fixmoai glm
切换到 GLM 后端或更新 API 密钥。
moai glm [OPTIONS] [API_KEY]选项
| 选项 | 描述 |
|---|---|
--team | 启动 GLM Worker 模式 (Opus 领导 + GLM-5 团队成员) |
--help | 显示帮助 |
用法
# 切换到 GLM 后端
moai glm
# 更新 API 密钥
moai glm <api-key>
# 启动 GLM Worker 模式 (经济高效的团队开发)
moai glm --team
# 从 z.ai 获取 API 密钥
# https://z.ai/subscribe?ic=1NDV03BGWUGLM Worker 模式
使用 --team 选项可启动经济高效的 GLM Worker 模式:
- 配置: Opus 模型的领导代理 + GLM-5 模型的团队成员代理
- 优势: 相比 Claude 节省 70% 成本，性能相当
- 用途: 大规模团队开发时优化令牌成本
基于配置文件的登录 (v2.7.0+)
moai glm、moai cc 和 moai cg 现在是支持持久配置文件的登录命令。配置文件存储在 ~/.moai/claude-profiles/。
- 首次运行时提供交互式配置文件设置向导
- 配置文件跨会话持久化
- 从
moai glm切换到moai cg时自动重置 GLM 设置
moai claude
切换到 Claude 后端 (Anthropic API)。
$ moai claude
# 或简写
$ moai ccmoai cg
启用 CG 模式 (Claude + GLM 混合)。领导使用 Claude API，团队成员使用 GLM API，通过 tmux 会话级别环境变量隔离实现。
moai cgv2.7.1 变更: CG 模式现在是默认团队模式。使用 --team 时，无需额外设置即以 CG 模式运行。
工作原理
- 将 GLM 配置注入 tmux 会话环境
- 从 settings 中移除 GLM 环境 — 领导窗格使用 Claude API
- 设置
CLAUDE_CODE_TEAMMATE_DISPLAY=tmux— 团队成员在新窗格中继承 GLM 环境
用法
# 1. 保存 GLM API 密钥 (仅首次)
moai glm sk-your-glm-api-key
# 2. 启用 CG 模式 (必须在 tmux 中)
moai cg
# 3. 在同一窗格中启动 Claude Code
claude
# 4. 运行团队工作流
/moai --team "任务描述"注意事项
| 项目 | 描述 |
|---|---|
| 需要 tmux | 必须在 tmux 会话内运行。将 VS Code 终端默认设置为 tmux 更方便。 |
| 领导启动位置 | 必须在运行 moai cg 的同一窗格中启动 Claude Code。 |
| 会话结束 | session_end 钩子自动清理 tmux 会话环境。 |
模式比较
| 命令 | 领导 | 工作者 | 需要 tmux | 成本节省 | 用途 |
|---|---|---|---|---|---|
moai cc | Claude | Claude | 否 | - | 最高质量 |
moai glm | GLM | GLM | 推荐 | ~70% | 成本优化 |
moai cg | Claude | GLM | 必须 | ~60% | 质量 + 成本平衡 |
显示模式
| 模式 | 描述 | 通信 | 领导/工作者分离 |
|---|---|---|---|
in-process | 默认模式 | SendMessage | 相同环境 |
tmux | 分屏显示 | SendMessage | 会话环境隔离 |
注意: CG 模式仅在 tmux 显示模式下支持领导/工作者 API 分离。
moai status
检查项目状态。
moai status输出示例:
╭────── 项目状态 ──────╮
│ 模式 personal │
│ 区域 unknown │
│ SPECs 1 │
│ 分支 main │
│ Git 状态 Modified │
╰────────────────────────────╯输出信息:
- 模式: 工作模式 (personal、team、manual)
- 区域: 语言设置
- SPECs: 活动 SPEC 数量
- 分支: 当前分支
- Git 状态: Git 状态 (Clean、Modified)
moai worktree
管理用于并行 SPEC 开发的 Git worktrees。
moai worktree [OPTIONS] COMMAND [ARGS]...子命令
| 命令 | 描述 |
|---|---|
moai worktree new | 创建新 worktree |
moai worktree list | 列出活动 worktrees |
moai worktree switch | 切换到 worktree |
moai worktree go | 导航到 worktree 目录 |
moai worktree sync | 与上游同步 |
moai worktree remove | 删除 worktree |
moai worktree clean | 清理过时的 worktrees |
moai worktree recover | 从现有目录恢复 |
moai worktree new
创建新 worktree。
moai worktree new [OPTIONS] SPEC_ID选项
| 选项 | 描述 |
|---|---|
-b, --branch TEXT | 用户分支名称 |
--base TEXT | 基础分支 (默认: main) |
--repo PATH | 仓库路径 |
--worktree-root PATH | Worktree 根路径 |
-f, --force | 即使存在也强制创建 |
--glm | 使用 GLM LLM 设置 |
--llm-config PATH | 用户 LLM 配置文件路径 |
示例
# 为 SPEC-001 创建 worktree
moai worktree new SPEC-001
# 指定用户分支
moai worktree new SPEC-001 --branch feature-auth
# 更改基础分支
moai worktree new SPEC-001 --base developmoai worktree list
列出活动 worktrees。
moai worktree list [OPTIONS]选项
| 选项 | 描述 |
|---|---|
--format [table|json] | 输出格式 |
--repo PATH | 仓库路径 |
--worktree-root PATH | Worktree 根路径 |
moai worktree remove
删除 worktree。
moai worktree remove [OPTIONS] SPEC_ID选项
| 选项 | 描述 |
|---|---|
-f, --force | 强制删除未提交的更改 |
--repo PATH | 仓库路径 |
--worktree-root PATH | Worktree 根路径 |
worktree 工作流
moai hook
MoAI-ADK 事件的 Claude Code 钩子调度器。
moai hook <event>支持的事件（16 个）
| 事件 | 描述 |
|---|---|
PreToolUse | 工具执行前 |
PostToolUse | 工具执行后 |
Notification | 系统通知 |
Stop | 会话结束 |
SubagentStop | 子代理结束 |
UserPromptSubmit | 用户提示提交 |
PreCompact | 上下文压缩前 |
PostCompact | 上下文压缩后 |
PermissionRequest | 权限请求 |
PostToolFailure | 工具执行失败后 |
SubagentStart | 子代理启动 |
TeammateIdle | 团队成员空闲状态 |
TaskCompleted | 任务完成 |
WorktreeCreate | 工作树创建 |
WorktreeRemove | 工作树删除 |
model | 模型选择 |
示例
# 运行 PreToolUse 钩子
moai hook PreToolUse
# 运行 PostToolUse 钩子
moai hook PostToolUse
# 用户提示提交钩子
moai hook UserPromptSubmit任务指标日志
MoAI-ADK 在开发会话期间自动捕获 Task 工具指标。
日志文件
- 位置:
.moai/logs/task-metrics.jsonl - 格式: JSONL (JSON Lines)
捕获指标
| 指标 | 描述 |
|---|---|
| 令牌使用量 | 输入/输出令牌数量 |
| 工具调用 | 使用的工具列表及调用次数 |
| 持续时间 | 任务执行时间 |
| 代理类型 | 执行的代理类型 |
用途
- 会话分析与性能优化
- 代理效率分析
- 令牌消耗追踪与成本管理
Task 工具完成时，PostToolUse 钩子会自动记录指标。
模型策略设置
MoAI-ADK 根据 Claude Code 订阅计划为代理分配最优的 AI 模型。
策略层级
| 策略 | 计划 | 🟣 Opus | 🔵 Sonnet | 🟡 Haiku |
|---|---|---|---|---|
| High | Max $200/月 | 23 | 1 | 4 |
| Medium | Max $100/月 | 4 | 19 | 5 |
| Low | Plus $20/月 | 0 | 12 | 16 |
配置方法
# 项目初始化时 (交互式向导)
moai init my-project
# 重新配置现有项目
moai update -c
# 手动配置 (.moai/config/sections/user.yaml)
# model_policy: high | medium | low注意: 默认策略为
High。运行moai update后，通过moai update -c配置设置。
环境变量
| 变量 | 描述 |
|---|---|
MOAI_API_KEY | API 密钥 (Claude/GLM) |
MOAI_MODE | 执行模式 (development/production) |
MOAI_LOCALE | 语言设置 (ko/en/ja/zh) |
MOAI_WORKTREE_ROOT | Worktree 根路径 |
另请参阅
Last updated on