Munk AI logoMunk AI
安装
返回文档
快速开始

快速开始

安装 Munk AI，检查环境，跑通第一次工作流，并了解常用命令与 Web UI 入口。

这篇文档会带你从安装开始，启动第一次本地 Web UI 会话，并快速了解日常最常用的几个入口。

你将完成什么

在这篇文档里，你会完成五件事：

  1. 安装 Munk AI
  2. 检查本地环境是否准备完成
  3. 启动 Web UI
  4. 知道几个最核心的命令分别做什么

安装 Munk AI

curl -fsSL https://get.munk.sh | sh

安装完成后，先确认 shell 中已经可以使用 munk 命令。

可以顺手检查版本：

munk version

检查环境

运行：

munk doctor

这一步用来确认本地 runtime、依赖以及基础验证环境已经准备好，避免你在更复杂的工作流里才发现环境问题。

启动 Web UI

当前推荐的第一次体验方式，是先启动本地服务并打开 Web UI：

munk serve --host 127.0.0.1 --port 16888

然后打开：

http://127.0.0.1:16888/

这条路径最适合第一次了解 Munk AI，再逐步进入正式的执行与验证工作流。

下面这组页面截图，可以帮助你快速建立对 Web UI 主流程的整体认识。推荐按下面的顺序浏览：

1. 在 Settings 完善 AI provider 配置

第一次进入 Web UI 后，建议先打开 Settings。这里可以选择默认 provider，并补齐模型连接所需的关键信息，例如 base_url、model、api_key，以及需要时再补充 agent override 和 runtime 默认参数。

Settings 页面截图

2. 在 Apps 创建第一个 App 项目

配置好模型后，进入 Apps 页面创建你的第一个 App。这里是长期测试资产的入口，你可以为目标应用填写 app_id、平台类型以及基础介绍，后续生成的 plan、case 和 run 都会围绕这个 App 组织。

Apps 页面截图

3. 回到 Dashboard，创建第一个测试计划

Dashboard 是默认首页，用来快速查看当前的 plan、case、recent runs 和 connected devices 概览。首次上手时，可以从这里进入创建测试计划的入口，开始生成你的第一个 plan。右上角 「运行测试」 按钮可进入批量运行与定时任务界面，详见 批量运行与定时任务。

Dashboard 页面截图

4. 或者去 Recording，通过录制生成测试 Case

如果你更想从真实交互出发，也可以直接进入 Recording。这个页面提供录制工作区，你可以连接设备、开始录制、分析结果，并把录制流程导出成正式测试 case，再接回主测试资产链路。

Recording 页面截图

5. 在 Tests 查看已创建的测试计划和 Case

Tests 页面用于集中查看和管理测试资产。你可以浏览已生成的 plans，也可以切换到搜索视图，按 app_id、plan_id、case_id 查找已有 case。

Tests 页面截图

6. 在 Runs 查看测试运行记录

当你开始执行 run plan、verify change 或 replay 之后，Runs 页面会集中展示运行记录。这里可以按类型、平台、状态、判定结果等维度过滤，并继续进入单次运行的详细结果页。

Runs 页面截图

常用核心命令

如果你只想先对整体命令面有一个感觉，下面这些最值得优先记住：

  • munk doctor：检查本地 runtime、依赖和基础环境是否可用
  • munk serve：启动本地 Local API 和 Web UI
  • munk plan：先生成测试计划和 case，默认停在 planning 阶段供 review
  • munk run plan：执行一个已经确认过的 plan
  • munk verify change：围绕代码改动生成验证计划；显式加 --auto-run 时再继续执行

几个最小示例：

munk plan \
  --app-id app-1 \
  --requirement-doc /path/to/PRD.md \
  --technical-doc /path/to/TECHNICAL_DESIGN.md \
  --config /path/to/config.yaml

munk run plan \
  --app-id app-1 \
  --plan-id plan-20260518160714 \
  --package com.example.app \
  --serial <device-serial> \
  --config /path/to/config.yaml

munk verify change \
  --app-id app-1 \
  --change-summary "Fix task save flow" \
  --changed-file src/task.py \
  --config /path/to/config.yaml

高级配置

当你准备进一步深入时，可以开始准备配置文件。Munk AI 会通过 config.yaml 知道：

  • 使用哪个模型 provider
  • 使用哪个模型
  • 如何连接到模型服务
  • 执行链默认使用哪些 runtime 参数

全局配置 vs 当前工作区配置

Munk AI 支持两种常见配置方式：

  1. 全局配置
  2. 当前工作区配置

你可以这样理解它们的区别：

  • 全局配置：适合你平时长期使用的一套默认模型和参数
  • 当前工作区配置：适合某个项目单独覆盖自己的模型、超时或执行参数

默认查找顺序是：

  1. MUNK_CONFIG
  2. 当前工作区的 .munk/config.yaml
  3. 全局配置目录下的 config/config.yaml

这意味着：

  • 如果你显式设置了 MUNK_CONFIG，它优先级最高
  • 如果当前工作区里已经有 .munk/config.yaml，就会优先使用工作区配置
  • 如果前两者都没有，才会回退到全局配置

全局配置目录在不同系统上的默认位置是：

  • macOS：~/Library/Application Support/MunkAI/config/config.yaml
  • Linux：${XDG_DATA_HOME:-~/.local/share}/munk/config/config.yaml
  • Windows：%LOCALAPPDATA%/MunkAI/config/config.yaml

如果你是第一次使用，推荐先准备一份全局配置；如果某个项目有自己的模型或执行需求，再在该项目里加一份工作区配置。

config.yaml 的结构

一个常见的 config.yaml 可以理解为三层：

provider: <默认 provider 名称>

<provider 名称>:
  # provider 自己的连接参数
  model: ...
  timeout_sec: ...

runtime:
  # 可选：执行链默认参数
  max_steps: 30
  max_seconds: 300

agents:
  # 可选：为 judge / review 等阶段单独覆盖模型

先记住一个最重要的规则：

  • provider 决定默认使用哪一组模型配置
  • 同名配置块里填写这个 provider 的连接参数
  • runtime 是可选的执行默认值
  • agents 是可选的阶段级覆盖；不配也可以先跑通

一个最小可用示例

如果你用的是本地 LM Studio 兼容接口，一个最小可用配置通常像这样：

provider: openai_compatible

openai_compatible:
  base_url: "http://127.0.0.1:1234/v1"
  api_key: null
  model: "google/gemma-4-26b-a4b"
  timeout_sec: 300

如果你用的是 Gemini 直连，可以写成：

provider: gemini

gemini:
  api_key: "YOUR_GEMINI_API_KEY"
  model: "gemini-2.5-flash"
  timeout_sec: 120

需要注意：

  • 执行链需要支持图像输入的 Vision 模型
  • base_url、api_key、model 这几个字段通常最关键
  • 如果你还不熟悉完整结构，先从最小配置开始就够了

完整的 runtime 配置示例

如果你想把执行链默认参数也一起配好，可以在 config.yaml 里补上完整的 runtime 段：

runtime:
  max_tokens: 8192
  temperature: 0.2
  max_steps: 30
  max_seconds: 300
  interval: 0.5
  max_side: 1024
  vl_max_side: 768
  icon_conf: 0.12

这些参数会作为 run case、run plan、verify change 的默认值；如果你在命令行里显式传了参数，CLI 参数会覆盖这里的配置。

可以这样理解每个字段：

  • max_tokens：单次模型调用可使用的最大输出 token 上限
  • temperature：模型输出的发散程度；越低越稳定，越高越开放
  • max_steps：一次执行里最多允许 agent 走多少步
  • max_seconds：一次执行允许持续的最长时间
  • interval：执行循环中相邻观察/动作之间的间隔秒数
  • max_side：通用截图处理时允许的最大边长
  • vl_max_side：发给视觉模型时使用的图像最大边长
  • icon_conf：图标检测结果的置信度阈值

如果你刚开始使用，不确定怎么调，推荐先用这组默认值。等你遇到更长流程、更慢页面或更复杂 UI 时，再按场景微调。

如果你暂时不想放到全局或工作区默认位置，也可以先手动准备一份 /path/to/config.yaml，然后在命令里显式传入 --config /path/to/config.yaml。

下一步读什么

当你已经完成第一次运行之后，推荐继续阅读：