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

mobile-use 是一个强大的开源 AI Agent，可以通过自然语言控制 Android 或 iOS 设备。它能够理解用户命令并与 UI 交互执行任务，从发送消息到操作复杂应用都能胜任。该项目在 GitHub 上已获得 2.2k stars，是首个在 AndroidWorld 基准测试中达到 100% 完成度的智能体框架。

核心特性

• 自然语言控制：使用母语与手机交互，无需编写复杂脚本
• UI 感知自动化：智能导航应用界面（注意：游戏类应用由于不提供无障碍树数据，效果有限）
• 数据抓取：从任意应用提取信息并按需格式化（如 JSON）
• 可扩展定制：轻松配置不同 LLM 驱动 Agent

技术栈

• Python 3.12+ - 主要开发语言
• uv - 极速 Python 包管理器
• Docker - 容器化部署支持
• ADB (Android Debug Bridge) - Android 设备连接
• fb-idb - iOS 设备自动化（macOS only）

安装指南

快速启动（Docker）

目前仅支持 Android 设备/模拟器，需先安装 Docker。

前置条件：

• 连接 Android 设备并启用 USB 调试，或启动 Android 模拟器

运行命令：

Linux/macOS:

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"

Windows (PowerShell):

powershell.exe -ExecutionPolicy Bypass -File mobile-use.ps1 `
  "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"

手动安装（开发模式）

1. 设备支持

• 物理 Android 手机（USB 连接，启用 USB 调试）
• Android 模拟器（通过 Android Studio 设置）
• iOS 模拟器（仅 macOS）
• 物理 iOS 设备（暂不支持）

2. 前置要求

Android:

• Android Debug Bridge (ADB)

iOS (仅 macOS):

• Xcode - Apple 官方 IDE
• fb-idb - Facebook iOS 开发桥

brew tap facebook/fb
brew install idb-companion

通用要求:

• uv - 极速 Python 包管理器

3. 安装步骤

# 克隆仓库
git clone https://github.com/minitap-ai/mobile-use.git && cd mobile-use

# 设置环境变量
cp .env.example .env
# 编辑 .env 添加 API 密钥

# （可选）自定义 LLM 配置
cp llm-config.override.template.jsonc llm-config.override.jsonc

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # macOS/Linux
# 或 .venv\Scripts\activate  # Windows

# 安装依赖
uv sync

使用示例

基础命令

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

数据抓取

提取特定信息并以结构化格式返回：

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"

使用本地 LLM

1. 在 .env 中设置 OPENAI_BASE_URL 和 OPENAI_API_KEY
2. 在 llm-config.override.jsonc 中将 provider 设为 openai，选择支持的模型

Google Vertex AI 配置

需满足以下条件之一：

• 环境已配置凭证（gcloud、workload identity 等）
• 将服务账号 JSON 文件路径设为 GOOGLE_APPLICATION_CREDENTIALS 环境变量

Agent 系统架构

mobile-use 采用模块化 Agent 架构，通过可视化流程图管理任务执行：

该架构图自动从代码库生成，展示当前 Agent 系统设计。

基准测试成绩

mobile-use 是 AndroidWorld 基准测试的顶尖表现者，也是首个完成 100% 测试任务的开源框架。

• Minitap 基准测试详情
• 官方排行榜

故障排查

设备 IP 未找到

如果脚本报错 Could not get device IP，说明无法识别常见 Wi-Fi 接口。通过 adb shell ip addr show up 确定手机使用的 WLAN 接口，然后添加 --interface <YOUR_INTERFACE_NAME> 选项。

Docker 内连接失败

可能是防火墙阻止连接，请检查防火墙设置。

GHCR 镜像拉取失败 (unauthorized)

如果之前使用过 ghcr.io 私有仓库，可能有过期 token。运行 docker logout ghcr.io 后重试。

项目链接

• GitHub 仓库: https://github.com/minitap-ai/mobile-use
• 官方文档: https://docs.minitap.ai/v2/mcp-server/introduction
• 云平台: https://platform.mobile-use.ai
• PyPI 包: https://pypi.org/project/minitap-mobile-use/
• Discord 社区: https://discord.gg/6nSqmQ9pQs
• Twitter/X: https://x.com/minitap_ai

许可证

本项目采用 Apache License 2.0 开源协议。

如在研究或商业产品中使用本项目，请引用：

Minitap, Inc. (2026). Mobile-Use: Achieving 100% on AndroidWorld. GitHub: https://github.com/minitap-ai/mobile-use