mobile-use：用自然语言自动化你的手机

Mobile-use 是一款功能强大的开源 AI 助手，能够通过自然语言控制你的 Android 或 iOS 设备。它能理解你的指令，并与用户界面交互来完成各种任务，从发送消息到导航复杂的应用程序。

Mobile-use 正在快速发展中。你的建议、想法和报告的 bug 都将影响这个项目的方向。请随时加入 Discord 的讨论或直接贡献代码，我们一定会回复每一位参与者！❤️

✨ 特性

• 🗣️ 自然语言控制：使用你的母语与手机互动。
• 📱 UI 感知自动化：智能地在应用界面中导航（注意：目前对游戏的支持有限，因为游戏通常不提供无障碍树数据）。
• 📊 数据抓取：通过自然语言描述，从任何应用中提取信息并将其结构化为你所需的格式（例如 JSON）。
• 🔧 可扩展与可定制：轻松配置不同的大模型来驱动 Mobile-use 的核心代理。

基准测试

我们在 AndroidWorld 基准测试中表现最佳，并且是首个完成 100% 测试项的团队。

更多关于我们如何达成这一里程碑的信息，请参阅：Minitap 基准测试。

官方排行榜在此：Google 表格。

我们的研究论文请见：arXiv。

🚀 快速开始

准备好自动化你的移动体验了吗？按照以下步骤即可快速上手 Mobile-use。

🌐 通过我们的平台

最简单的方式是使用我们的平台。 请参考我们的 平台快速入门指南 开始使用。

🛠️ 从源码安装

1. 设置环境变量： 将 .env.example 文件复制为 .env，并添加你的 API 密钥。

   cp .env.example .env
   

2. （可选）自定义 LLM 配置： 如果你想使用不同的模型或服务提供商，可以创建自己的 LLM 配置文件。

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

   然后编辑 llm-config.override.jsonc 以满足你的需求。

   你也可以使用本地 LLM 或其他兼容 OpenAI API 的服务提供商：

   1. 在 .env 中设置 OPENAI_BASE_URL 和 OPENAI_API_KEY。
   2. 在 llm-config.override.jsonc 中，将你希望使用的代理节点的提供商设置为 openai，并选择你的服务提供商支持的模型。

   [!注意] 如果你想使用 Google Vertex AI，你必须：

   • 为你的环境配置好凭据（gcloud、工作负载身份等）
   • 将服务账户 JSON 文件的路径存储为 GOOGLE_APPLICATION_CREDENTIALS 环境变量

   更多信息：- 凭据类型 - google.auth API 参考

快速启动（Docker）

[!注意] 目前此快速入门仅适用于 Android 设备或模拟器，并且你需要已安装 Docker。

首先：

• 将你的 Android 设备连接并启用开发者选项中的 USB 调试模式。
• 或者启动一个 Android 模拟器。

然后在终端中运行：

1. 对于 Linux/macOS：

chmod +x mobile-use.sh
bash ./mobile-use.sh \
  "打开 Gmail，找到前三封未读邮件，并列出发件人和主题" \
  --output-description "一个包含 'sender' 和 'subject' 键的对象列表"

2. 对于 Windows（在 PowerShell 终端中）：

powershell.exe -ExecutionPolicy Bypass -File mobile-use.ps1 `
  "打开 Gmail，找到前三封未读邮件，并列出发件人和主题" `
  --output-description "一个包含 'sender' 和 'subject' 键的对象列表"

[!注意] 如果使用你自己的设备，请确保接受设备上弹出的 ADB 连接请求。

🧰 故障排除

脚本会尝试通过 IP 地址连接到你的设备。 因此，你的设备 必须与电脑连接在同一 Wi‑Fi 网络下。

1. 未找到设备 IP

如果脚本报错如下：

无法获取设备 IP。是否已通过 USB 连接设备，并且与电脑处于同一 Wi‑Fi 网络？

这意味着脚本未能找到设备上的常见 Wi‑Fi 接口。 因此，你需要通过 adb shell ip addr show up 确定你的手机正在使用的 WLAN 接口名称。 然后在脚本中添加 --interface <YOUR_INTERFACE_NAME> 参数。

2. 无法连接到 :5555（Docker 内部）

这很可能是防火墙阻止了连接。目前尚无明确的解决方案。

3. 拉取 GHCR Docker 镜像失败（未经授权）

由于 UV Docker 镜像依赖于 ghcr.io 公开仓库，如果你之前曾使用过 ghcr.io 来访问私有仓库，可能会导致令牌过期。 请尝试运行 docker logout ghcr.io，然后再次运行脚本。

手动启动（开发模式）

适用于希望手动设置环境的开发者：

1. 设备支持

目前，mobile-use 支持以下设备：

• 实体 Android 手机：通过 USB 连接，并启用 USB 调试功能。
• Android 模拟器：可通过 Android Studio 设置。
• iOS 模拟器：仅支持 macOS 用户。

[!NOTE] 实体 iOS 设备暂不支持。

2. 先决条件

对于 Android：

• Android Debug Bridge (ADB)：用于连接设备的工具。

对于 iOS（仅限 macOS）：

• Xcode：苹果公司提供的 iOS 开发集成开发环境。

• fb-idb：Facebook 提供的 iOS 开发桥，用于设备自动化。

  # 通过 Homebrew 安装（macOS）
  brew tap facebook/fb
  brew install idb-companion
  

  [!NOTE] idb_companion 是与 iOS 模拟器通信所必需的工具。安装后请确保它已添加到您的 PATH 中。

通用要求：

在开始之前，请确保已安装以下内容：

• uv：一款超快速的 Python 包管理器。

3. 安装

1. 克隆仓库：

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

2. 设置环境变量

3. 创建并激活虚拟环境：

   # 将使用 .python-version 文件中指定的 Python 版本创建 .venv 目录
   uv venv
   
   # 激活环境
   # 在 macOS/Linux 上：
   source .venv/bin/activate
   # 在 Windows 上：
   .venv\Scripts\activate
   

4. 安装依赖项：

   # 使用锁定的依赖项进行同步，以确保一致的配置
   uv sync
   

👨‍💻 使用方法

要运行 mobile-use，只需将您的命令作为参数传递即可。

示例 1：基本命令

python ./src/mobile_use/main.py "前往设置，告诉我当前的电池电量"

示例 2：数据抓取

提取特定信息并以结构化格式返回。例如，获取未读邮件列表：

python ./src/mobile_use/main.py \
  "打开 Gmail，找到所有未读邮件，并列出其发件人和主题" \
  --output-description "一个 JSON 列表，每个对象包含 'sender' 和 'subject' 键"

[!NOTE] 如果您尚未配置特定模型，mobile-use 会提示您从可用选项中选择一个。

🔎 智能体系统概述

❤️ 贡献

我们非常欢迎贡献！无论您是修复 bug、添加新功能，还是改进文档，您的帮助都将受到我们的欢迎。请阅读我们的 贡献指南 以开始。

⭐ 星标历史

🏆 归属与许可

mobile-use 是首个在 AndroidWorld 基准测试中达到 100% 准确率 的智能体框架。

本项目采用 Apache License 2.0 许可证。

如果您使用了此代码，或受到实现基准测试结果的架构启发，请务必注明 Minitap, Inc. 的贡献。

如何引用

如果您在研究或商业产品中使用本工作，请使用以下引用：

Pierre-Louis Favreau, Jean-Pierre Lo, Clement Guiguet, Charles Simon-Meunier,
Nicolas Dehandschoewercker, Allen G. Roush, Judah Goldfeder, Ravid Shwartz-Ziv.
多智能体会梦见电子屏幕吗？通过任务分解在 AndroidWorld 上实现完美准确率。
arXiv 预印本 arXiv:2602.07787 (2026)。
https://arxiv.org/abs/2602.07787

Bibtex

@misc{favreau2026multiagentsdreamelectricscreens,
  title        = {多智能体会梦见电子屏幕吗？通过任务分解在 AndroidWorld 上实现完美准确率},
  author       = {Pierre-Louis Favreau 和 Jean-Pierre Lo 和 Clement Guiguet 和 Charles Simon-Meunier 和 Nicolas Dehandschoewercker 和 Allen G. Roush 和 Judah Goldfeder 和 Ravid Shwartz-Ziv},
  year         = {2026},
  eprint       = {2602.07787},
  archivePrefix= {arXiv},
  primaryClass = {cs.AI},
  url          = {https://arxiv.org/abs/2602.07787}
}

mobile-use 快速上手指南

mobile-use 是一个强大的开源 AI 智能体，能够使用自然语言控制您的 Android 或 iOS 设备。它能理解您的指令并与 UI 交互，执行从发送消息到导航复杂应用等各种任务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

系统要求

• 操作系统: Linux, macOS, 或 Windows
• Python 版本: 3.12 或更高
• 设备支持:
  • Android: 物理手机（需开启 USB 调试）或 Android 模拟器。
  • iOS: 仅支持 macOS 上的 iOS 模拟器（暂不支持物理 iOS 设备）。

前置依赖

根据目标设备安装相应工具：

通用依赖:

• uv: 极速 Python 包管理器。

  # 安装 uv (推荐方式)
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

Android 设备:

• Android Debug Bridge (ADB): 用于连接设备。请确保 adb 已加入系统 PATH。

iOS 设备 (仅限 macOS):

• Xcode: Apple 官方 IDE。
• fb-idb: Facebook iOS 开发桥接工具。

  brew tap facebook/fb
  brew install idb-companion
  

  注意：安装后请确保 idb_companion 在您的 PATH 中。

安装步骤

1. 克隆项目

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

2. 配置环境变量

复制示例配置文件并填入您的 API Key（如 OpenAI Key 等）。

cp .env.example .env
# 编辑 .env 文件，填入 OPENAI_API_KEY 等必要信息

(可选) 自定义 LLM 配置: 如需使用其他模型提供商或本地模型，可复制并编辑配置文件：

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

3. 创建虚拟环境并安装依赖

使用 uv 快速设置环境：

# 创建虚拟环境
uv venv

# 激活环境
# macOS/Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 同步安装依赖
uv sync

基本使用

确保您的设备已通过 USB 连接（开启 USB 调试）或模拟器正在运行，然后执行以下命令。

示例 1：基础控制

查询手机电池电量：

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

示例 2：数据抓取

提取 Gmail 中未读邮件的发件人和主题，并以 JSON 格式输出：

python ./src/mobile_use/main.py \
  "Open Gmail, find all unread emails, and list their sender and subject line" \
  --output-description "A JSON list of objects, each with 'sender' and 'subject' keys"

提示: 如果未在配置文件中指定模型，运行时程序会提示您选择可用的模型。

---

更多高级用法（如 Docker 快速启动、多代理架构详解）请参考官方文档。