跳到主要内容

快速开始（10 分钟）

本节带你从“一台干净的电脑”到“在 UI 里看到第一个项目跑出结果”。全程约 10 分钟（不含模型调用本身的时间）。

先记一个最重要的选择题：

  • 想在同一台电脑上把 UI 和本地 mira-engine 一起装好，首启自动拉起本机引擎：选 MIRA-bundle
  • 想连接远程服务器上的 mira，或你已经自己装好了本机 mira / mira-engine：选 MIRA-standalone

0) 前置条件​

最少需要：

  • 一台 macOS / Windows / Linux 电脑。
  • 至少 一个 模型 Provider 的 API key（OpenAI / Anthropic / OpenRouter / DeepSeek / 阿里 DashScope / 智谱 / 火山 / Azure 等任一即可），也可以用本地的 Ollama（不要 key）。

按你后面选的安装方式不同，软件依赖不同：

安装方式PythonNode.jsGit
A. 单文件可执行（推荐普通用户）❌ 不需要仅在你想从源码跑 UI 时需要❌
B. PyPI 安装（推荐熟悉 Python 的研究者）3.11 或 3.12仅在你想从源码跑 UI 时需要❌
C. 源码安装（开发者 / 想 hack）3.11 或 3.1220+✅

不知道 Provider 选哪个？想要省事且效果稳：注册一个 OpenRouter key，能用一把钥匙调遍主流闭源/开源模型。

1) 安装 MIRA 引擎​

挑一个你最舒服的方式。装一种就够了，不要混装。

无需 Python，下载即用，最适合非开发者。

到 GitHub Releases 下载对应平台的可执行文件（每个文件都附带 .sha256 校验和）：

平台文件
Windows (x86_64)mira-engine-windows-x86_64.exe
macOS (Apple Silicon)mira-engine-macos-arm64
macOS (Intel)mira-engine-macos-x86_64
Linux (x86_64)mira-engine-linux-x86_64

放到 PATH 里即可（建议改名去掉平台后缀）。

macOS / Linux：

# 以 macOS arm64 为例
curl -L -o mira-engine \
  https://github.com/MIRA-Intelligence/mira/releases/latest/download/mira-engine-macos-arm64
chmod +x mira-engine
sudo mv mira-engine /usr/local/bin/

# macOS 首次运行可能需要解除 Gatekeeper 隔离
xattr -dr com.apple.quarantine /usr/local/bin/mira-engine

Windows（PowerShell，管理员）：

# 下载到固定目录并加入 PATH
$dst = "C:\Program Files\Mira"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
Invoke-WebRequest -Uri "https://github.com/MIRA-Intelligence/mira/releases/latest/download/mira-engine-windows-x86_64.exe" `
  -OutFile "$dst\mira-engine.exe"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$dst", "Machine")

单文件版直接提供 mira-engine 服务管理 CLI（含 gateway 子流程），可以覆盖大多数日常使用。如果你需要直接用 mira agent ... 在终端跟 Agent 对话，请改用 B 或 C 方式安装。

校验：

mira-engine --help
mira-engine doctor

2) mira onboard — 初始化本地​

mira onboard

它会：

  1. 在 ~/.mira/ 下创建：config.json、workspace/、logs/、runtime/。
  2. 写入一份带占位字段的 config.json 模板。
  3. （加 --wizard 可以走交互式向导，逐项填 provider/model/key。）

如果你之前用过 MedPilot，第一次运行 mira 任何子命令时都会自动把 ~/.medpilot/ → ~/.mira/，并把 MEDPILOT_* 环境变量映射到 MIRA_*，原文件保留 .migrated-from-medpilot 标记后不再触发。

3) 配置 Provider​

打开 ~/.mira/config.json，至少把以下几项填齐。下面给三种最常见组合：

选项 A：OpenRouter（最简单，一把钥匙调全家）
{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4-5",
      "maxTokens": 8192,
      "temperature": 0.1,
      "maxToolIterations": 60
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-..."
    }
  }
}
选项 B：直接 OpenAI + Anthropic 双账号
{
  "agents": {
    "defaults": {
      "provider": "auto",
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "providers": {
    "openai":    { "apiKey": "sk-..." },
    "anthropic": { "apiKey": "sk-ant-..." }
  }
}

provider: "auto" 会按 model 字段自动匹配 anthropic/... → anthropic，openai/... → openai。

选项 C：本地 Ollama（无需 API key，需先装 Ollama 并 ollama pull qwen2.5:14b）
{
  "agents": {
    "defaults": {
      "provider": "ollama",
      "model": "qwen2.5:14b"
    }
  },
  "providers": {
    "ollama": {
      "apiBase": "http://localhost:11434"
    }
  }
}

校验：

mira status

应当看到 provider 已识别、model 已确认、workspace 路径正确。

4) 启动后端​

mira gateway

默认会在前台监听：

  • WebSocket：ws://localhost:18790/ws
  • REST API： http://localhost:18790/api

如果你想改端口：mira gateway --port 28790。常驻后台请看 本地服务（mira-engine）。

想直接在终端里聊一下试试，不用 UI？另开一个终端：

mira agent -m "你好，介绍一下你能做什么"

5) 启动 MiraUI​

挑一种安装方式。普通用户走 A 即可，B 留给前端开发者和想 hack UI 的人。

先按你的使用场景选包：

你现在的需求应下载的桌面包
我只想在这台电脑上直接开始用，不想单独装 mira-engineMIRA-bundle
我已经手动装好了 mira / mira-engine，只想装 UIMIRA-standalone
我要连接远程服务器上的 mira gatewayMIRA-standalone
我需要 Linux 桌面包MIRA-standalone（当前 Linux 只提供 standalone）

一个简单判断法：想连远程，就优先下 standalone；想本机一键开箱即用，就下 bundle。

到 GitHub Releases 下载对应平台的安装包。同一个 release 页面里会同时出现 -standalone- 和 -bundle- 两类资产：

类型适合谁典型文件名
MIRA-bundle本机使用、想省掉单独安装引擎MIRA-bundle-<ver>-mac-arm64.dmg / MIRA-bundle-<ver>-win-x64-setup.exe
MIRA-standalone远程连接、或你自己管理 mira-engineMIRA-standalone-<ver>-mac-arm64.dmg / MIRA-standalone-<ver>-win-x64-setup.exe / Linux .AppImage

macOS 首次打开如果提示 “无法验证开发者”：右键 → 打开（或 xattr -dr com.apple.quarantine /Applications/MIRA.app）。

启动后：

  1. 如果你装的是 MIRA-bundle：
    • 首启会自动检查、注册并启动本机 mira-engine
    • 默认走本地模式，目标地址固定为 127.0.0.1:18790
    • 最适合“这台电脑自己跑研究任务”的场景
  2. 如果你装的是 MIRA-standalone：
    • 不会替你安装内置 engine
    • 如果你本机已经按前文装好并启动了 mira gateway，通常无需额外配置
    • 如果后端跑在远程机器上，打开 Settings → General，填写远程 API / WebSocket 地址（例如 https://mira.lab.example.com/api 与 wss://mira.lab.example.com/ws）
  3. 不确定自己该下哪个？又只想尽快开始：
    • 单机本地使用：下 bundle
    • 远程 server / 团队共享后端：下 standalone

首屏占位图

图：UI 首屏总览。

6) 你的第一个项目​

  1. 新建项目：点左侧 +，填写：
    • Research description：对本项目要研究的内容及目标进行详细的描述。
    • agent_profile：研究类项目选 research。
    • contract_version：默认 compat 即可，等熟悉后再尝试 strict。
    • run_mode：先选 manual（每一步都看一眼）。
  2. 进入 Research 阶段：补充背景、数据来源、参考文献。Agent 会用 pubmed-search / deep-research 自动找资料。
  3. 进入 Experiment 阶段：在“新建实验”里写明指标和方法。Agent 会调用对应 skill（如 medical-image-dl-pipeline）落到 experiments/exp-001/ 下，每跑完一轮会回写 task_plan.json 中的 experiments[].results。
  4. 进入 Result 阶段：选择导出类型（experiment_report / paper_article / presentation / metadata），点击导出。完成后 UI 会显示 output_path 与 output_type，文件落在 result/exports/。
新建项目

图：新建项目

7) 验收清单​

跑完上面流程后，至少应满足：

  • ~/.mira/workspace/PRJ-xxxx/task_plan.json 存在且 phase = result、status = completed。
  • result.output_path 对应文件存在并可下载。
  • UI 项目卡片上出现 completed 标识。
  • mira status 没有红色项。

任一条不满足，按 FAQ 与故障排查 对应小节定位。

下一步去哪​

用得更顺手​

调优​

扩展​

出问题了​