mobile-use

环境要求

• Python 环境，并使用 uv 管理虚拟环境与依赖（README 使用 uv venv / uv sync）
• 一台已开启 USB 调试的 Android 真机，或已启动的 Android 模拟器（Docker 快速启动仅支持 Android）
• 至少一个受支持的 LLM 提供商 API Key（如 Anthropic、MiniMax，或任意 OpenAI 兼容服务）
• 若使用 Docker 快速启动，本机需已安装 Docker

安装与启动步骤

1. 1克隆仓库

   把 mobile-use 仓库克隆到本地并进入项目目录，后续命令都在该目录下执行。

   git clone https://github.com/minitap-ai/mobile-use.git && cd mobile-use

   复制

2. 2配置环境变量

   复制示例环境变量文件，然后在 .env 中填入所选提供商的 API Key。

   cp .env.example .env

   复制

3. 3自定义模型配置

   可选步骤：需要换模型或提供商时，复制 LLM 配置模板并编辑 override 文件。

   cp llm-config.override.template.jsonc llm-config.override.jsonc

   复制

4. 4创建虚拟环境

   用 uv 按 .python-version 指定的 Python 版本创建 .venv 目录。

   uv venv

   复制

5. 5激活虚拟环境

   macOS/Linux 用 source 激活；Windows 执行 .venv\Scripts\activate。

   source .venv/bin/activate

   复制

6. 6安装依赖

   按锁定文件同步依赖，保证环境一致。

   uv sync

   复制

7. 7运行任务

   用自然语言描述任务并直接传给 main.py；首次未配置模型会提示你选择模型。

   python ./minitap/mobile_use/main.py "Go to settings and tell me my current battery level"

   复制

8. 8Docker 快速启动

   可选方式，仅支持 Android，需先插好真机或启动模拟器；macOS/Linux 用移动端脚本一键运行。

   chmod +x mobile-use.sh && bash ./mobile-use.sh "Open Gmail, find first 3 unread emails, and list their sender and subject line" --output-description "A JSON list of objects, each with 'sender' and 'subject' keys"

   复制

关键配置

如何确认成功

执行 python ./minitap/mobile_use/main.py "Go to settings and tell me my current battery level"，能返回当前电量即表示运行成功。

常见问题

注意事项

• Docker 快速启动需本机已安装 Docker，且仅支持 Android 设备或模拟器。
• Windows 用户需在 PowerShell 中执行 mobile-use.ps1 脚本（powershell.exe -ExecutionPolicy Bypass -File mobile-use.ps1），并接受设备上的 ADB 授权弹窗。
• 使用 Google Vertex AI 时需先配置好环境凭据，或把服务账号 JSON 路径写入 GOOGLE_APPLICATION_CREDENTIALS。
• 移动端模型提供商的可用模型以 llm-config.defaults.jsonc 中的预设为准，如 claude-sonnet-4-6、MiniMax-M2.7。