初始设置

通过 MoAI-ADK 的交互式设置向导完成首次设置。向导只询问必须由人来决定的 5 项 —— 对话语言、姓名、要部署的代理框架、会话权限模式，以及是否启用 Jev 类型化判断。其余设置(模型策略、报告格式、质量门禁、设计工作流等)按推荐默认值保存，之后需要时可以更改。

大多数设置保存为 .moai/config/sections/ 下的 YAML 文件，每个文件只负责一个关注点，修改某个值时只需打开对应文件。会话权限模式是例外，它写入用户级的 Claude Code 设置(见下方 Page 2)。

想在创建新项目的同时初始化:

moai init my-project

该命令会创建 my-project 文件夹并初始化 MoAI-ADK。

想在既有项目中安装 MoAI-ADK,请移动到该文件夹后运行:

cd my-existing-project
moai init

信息

moai init 会直接安装到当前文件夹。新项目请用 moai init <项目名> 创建。

初始化向导不提供模式选择，始终按同一流程运行。没有扩大或缩小问题范围的标志，每个人看到的问题都一样。问题共 5 个，分为 3 页。屏幕顶部的进度指示(● ● ● ○ ○ 3 / 5)统计的是问题数，不是页数。

moai init my-project

信息

向导不会询问 Git 自动化模式和提供商。moai init 会根据仓库中已配置的 Git 远程自动判断。之后要更改 Git 设置，请运行 moai update -c (--config)。Git 相关问题(自动化模式、提供商、认证信息)只会在这条路径中出现。

设置对话语言和姓名两项。对话语言有预填的默认值，姓名只有在配置文件中已保存时才会预填。无论哪种情况，直接按 Enter 即可继续。

对话语言 —— MoAI 与你对话时使用的语言。选择后向导界面会立即切换为该语言。

? 选择对话语言
▸ English
  Korean (한국어)
  Japanese (日本語)
  Chinese (中文)

该设置保存到 .moai/config/sections/language.yaml。

姓名 —— MoAI 称呼你时使用的名字。留空则跳过。

? 输入您的姓名: [姓名]

该设置保存到 .moai/config/sections/user.yaml 的 user.name 字段。

信息

向导不询问项目名称。moai init <项目名> 会使用你传入的名称，不传则使用当前文件夹名称。也可以用 --name 标志直接指定。

选择要为此项目部署并接入哪个代理框架。选择不同，放到项目根目录的文件也不同。

? 选择要部署并接入的代理框架
▸ 仅 Claude (推荐) - 部署 .claude/ 表面与 AGENTS.md（沿用至今的默认行为）
  仅 Codex         - 仅部署 AGENTS.md 与 Codex 表面 — 不会生成 .claude/ 目录、CLAUDE.md 和 .mcp.json
  Claude + Codex   - 在相同的 .claude/ 部署之上追加 .codex/ 接入，并强制开启 .mcp.json 供应

指定 --llm claude|gpt|both 标志时，标志优先于此处的回答。

选择 Claude Code 会话以哪种权限模式启动。

? 选择会话权限模式
▸ 自动接受编辑 (推荐) - 自动接受文件编辑;其他工具仍需确认
  自动模式            - 在分类器安全检查下自动批准工具调用
  跳过权限检查        - 跳过所有提示;需要沙箱证明 (Docker/gVisor 等)

该设置不写入项目 YAML，而是写入用户级的 Claude Code 设置(defaultMode)。默认的"自动接受编辑"对应 defaultMode: acceptEdits。“跳过权限检查"只有在存在沙箱证明且终止开关关闭时才会生效，否则会降为自动模式应用。指定 --autonomy-tier semi-auto|automatic|fully-autonomous 标志时，标志优先于此处的回答。

Jev 针对传入的状态回答类型化问题并返回概率，它本身不做任何决定，答案由人来读。即使被自动使用，也只作为信号 — 例如 moai todo --auto 查看待办卡片的顺序，或只能确认或移交给人的可选启动交叉验证；仅凭该信号不会批准、合并或更改卡片。

? 要启用 Jev 类型化判断吗？（可选，默认关闭）

默认值为关闭。启用后，卡片正文或请求正文会发送到外部厂商的服务器，请在了解这一点后再选择。该设置保存到 .moai/config/sections/workflow.yaml 的 workflow.jev.enabled 字段。

注意

此问题只在 moai init 中出现。moai update -c 不会询问，之后要更改请打开 moai web 设置页面。

以下各项不经询问、直接按默认值保存。要更改，请传入标志，或在设置完成后使用 moai update -c 或 moai web。

询问逐智能体模型分配的向导问题已经退役。v3.2 起子代理沿用主会话的模型与推理深度，所以 moai init 不再询问模型策略 —— 已经没有需要逐智能体挑选的东西了。配置文件保留的是会话模型策略一项：以此配置启动的 Claude 会话的默认推理强度，仅在未单独选择推理强度时生效。请在 moai profile setup 的"会话模型策略"问题中设置。已退役的 --model-policy / --profile 旗标是只打印警告的弃用桩。继承规则见模型策略页面，逐智能体矩阵的退役见配置矩阵页面。

用标志指定所有值，即可不经向导完成初始化:

moai init my-project \
  --non-interactive \
  --llm claude \
  --autonomy-tier semi-auto \
  --enable-lsp=false \
  --enforce-quality

完成所有步骤后会生成配置文件:

graph TD
    A[".moai/"] --> B["config/"]
    A --> C["specs/"]
    A --> D["memory/"]
    B --> E["sections/"]
    E --> F["user.yaml"]
    E --> G["language.yaml"]
    E --> H["quality.yaml"]
    E --> I["llm.yaml"]
    E --> J["git-strategy.yaml"]

安装部署技能镜像时优先使用符号链接。在无法创建链接的环境里会改为复制部署,此时 moai init 的完成摘要会一并注明 —— 只需知道一点:副本不像链接那样跟着源头走。

# 用户设置
vim .moai/config/sections/user.yaml

# 语言设置
vim .moai/config/sections/language.yaml

# 会话模型策略 (effort 回退)
moai profile setup

# 质量设置
vim .moai/config/sections/quality.yaml

可重新运行设置向导来更改配置:

# 重新运行设置向导(推荐)
moai update -c

信息

moai update -c 命令可在保留既有设置的同时,只选择性地重新设置想更改的项目。

确认设置是否正确配置:

moai doctor

该命令会验证 Git 是否安装、项目结构(.moai/ 文件夹)、配置文件、各语言的开发工具。可用 --verbose 确认详情。

设置完成后,请跟随快速开始指南创建你的第一个项目。

moai --help