Roky Wang 的技术知识库

Mobilerun：用 LLM Agent 控制 Android 与 iOS 的移动自动化框架

12分钟阅读

Mobilerun：用 LLM Agent 控制 Android 与 iOS 的移动自动化框架

先给结论

Mobilerun 是 Droidrun 开源的移动端 Agent 框架：用户给出自然语言目标，LLM 根据设备的 UI 状态、无障碍树和可选的屏幕截图，循环选择点击、滑动、输入、启动应用或读取状态等动作，直到完成任务或达到步数上限。它面向 Android 和 iOS；本地 Framework 提供 CLI、Docker 与 Python API，另有托管设备和 API 工作流取向的 Mobilerun Cloud。^[来源：Mobilerun 项目 README]

它最适合需要把真实手机纳入 AI 自动化闭环的开发与测试场景，例如探索式 QA、回归辅助、重复操作、原生 App 数据提取或事件触发的任务。它不等价于传统的确定性 UI 测试框架：模型输出、界面变化、网络状态和设备权限都会影响结果，因此关键业务动作仍应保留明确断言、可审计日志与人工确认。

本文依据 2026-07-27 查阅的项目 README、官方快速开始与架构文档。模型列表、Portal 的系统权限和 Cloud 的产品边界可能随版本变动，落地前请以当前官方文档为准。

它如何工作

Mobilerun 将“看见设备”和“决定下一步”拆成两层。Android 本地运行时通过安装在设备上的 Mobilerun Portal 获取无障碍服务提供的 UI 树，并执行文本输入、手势、应用启动和设备状态读取；Agent 将这些观察结果连同任务目标交给所选 LLM，再发出下一轮动作。需要理解图像时，--vision 会把截图加入模型上下文；对于没有可用无障碍树的 App，可以使用仅依赖截图的 --vision-only 模式。^[来源：Mobilerun Quickstart]

自然语言目标
      │
      ▼
MobileAgent / CLI ── 任务规划、模型调用、状态管理 ── LLM 提供商
      │                                                   ▲
      │ 动作                                      UI 树 / 截图 / 状态
      ▼                                                   │
Android Portal 或 iOS Portal ──────── 设备上的应用与系统界面 ────────┘

这与 scrcpy 的职责不同：scrcpy 借助 ADB 将手机画面和人工输入映射到 Mac；Mobilerun 在 ADB 连接之外还引入设备侧 Portal、模型推理和多步决策。若目标是可靠重放已知步骤，优先考虑显式脚本或测试框架；若目标是从“打开设置并找出版本号”这类语义任务中适配具体界面，Mobilerun 才提供额外价值。

本地 Framework 的最小路径

官方快速开始要求 Python 3.11、3.12 或 3.13（目前不支持 Python 3.14）、uv、ADB，以及已开启开发者选项和 USB 调试的 Android 设备。CLI 使用可按下面顺序验证：^[来源：Mobilerun Quickstart]

# 仅使用命令行
uv tool install mobilerun
 
# 为已连接 Android 安装 Portal，并启用无障碍服务
mobilerun setup
 
# 验证本机能够与 Portal 通信
mobilerun ping
 
# 选择模型提供商、鉴权方式和模型
mobilerun configure
 
# 执行一个低风险的只读任务
mobilerun run "Open Settings and tell me the Android version"

configure 可以写入提供商配置，也可使用如 GOOGLE_API_KEY、OPENAI_API_KEY 或 ANTHROPIC_API_KEY 的环境变量。常见提供商中，Gemini、OpenAI、Ollama、OpenRouter 等默认可用；部分提供商需要额外安装包。实际支持范围以安装时的当前版本为准。^[来源：Mobilerun 项目 README]

在交付给长任务前，应先把 ping、单步读取和单个无害手势作为 smoke test。不要把“安装成功”理解为“Agent 已可靠理解所有应用”：无障碍树的质量、应用自定义控件、动态页面和模型本身都会改变成功率。

视觉、推理与 Python 集成

能力用途代价与边界
默认模式以 UI 树和设备状态执行直接任务受无障碍信息完整度影响；自定义绘制界面可能信息不足。
--vision将截图交给模型，辅助识别当前界面会增加模型成本、延迟和屏幕数据外发范围。
--vision-only不依赖无障碍树地从截图控制泛化能力可能更好，但定位与验证通常更不稳定。
--reasoning用 manager-executor 模式规划较长、多步骤任务调用次数、时延与错误累积会增加；应限制最大步数。
Python API用 MobileAgent、MobileConfig 组合业务流程与自定义工具应把结果状态、超时、重试和关键确认写进应用代码。

例如 CLI 中 --steps 30 --debug 能限制尝试次数并输出调试信息，--reasoning 适用于联系人搜索、跨页面填写等较复杂任务。Python API 则适合把 Agent 作为一个受控环节嵌入现有服务：官方示例中 await agent.run() 返回包含 success、reason 和 steps 的结果，可据此决定后续动作。^[来源：Mobilerun Quickstart]

从工程视角看，结构化输出、应用指令卡（app cards）、自定义工具、保存的轨迹与 Arize Phoenix 或 Langfuse 追踪，比单纯增加 prompt 更能提升可排查性。它们让团队能回答“模型看到了什么、为何点击此处、何时失败”，而不是只看到最终是否成功。^[来源：Mobilerun 项目 README]

Framework 与 Cloud：不要混淆运行边界

维度Mobilerun FrameworkMobilerun Cloud
运行位置自己的机器与已连接设备Mobilerun 管理的基础设施
接入方式CLI、Docker、Python APIDashboard、REST API、SDK 与托管设备
更适合本地开发、代码级编排、自有真机调试托管真机/云手机、设备群和无需本地执行的 API 工作流
主要责任用户负责设备连接、密钥、运行环境与操作边界仍需评估数据、设备、账号及云端工作流的权限边界

若团队需要完全控制模型密钥、设备与执行环境，应从 Framework 开始；若需要按规模调度托管手机或通过云 API 操作设备，再评估 Cloud。二者是部署与运营模式的选择，不是“本地版功能较少、云版必然更可靠”的简单关系。^[来源：Mobilerun 项目 README]

适用场景与不适用场景

场景建议原因
探索式移动 App QA、回归辅助适合，但保留关键断言Agent 能覆盖自然语言任务；发布门禁仍需确定性测试。
重复的个人设备操作适合从低风险任务开始可利用自然语言与应用状态，减少手动步骤。
原生 App 的信息查找与提取适合先在非敏感数据上验证UI 树和视觉可补充传统 API 不足，但数据质量须复核。
支付、转账、删库、发布或账号授权不应全自动执行误操作和提示注入的影响不可逆，应要求人工最终确认。
有稳定 API、CLI 或测试 ID 的业务流程通常优先 API/脚本/测试框架成本更低、确定性更强、审计更完整。

它与 open-computer-use 共享“Agent 观察—行动—验证”的总体模式，但执行面不同：前者专注 Android/iOS 的 Portal 与移动工作流，后者把桌面 GUI 动作作为 MCP 工具提供给上层 Agent。跨端流程应先划清手机、桌面、服务端 API 各自负责的环节，避免把本可审计的接口调用退化成脆弱的屏幕点击。

安全、隐私与可靠性

Portal 的无障碍服务有能力读取屏幕上可访问的 UI 内容并代表用户操作；视觉模式还可能把截图发给所选模型提供商。加上 USB/无线 ADB 调试授权与 LLM API key，Mobilerun 实际连接了设备控制、敏感屏幕数据和外部模型三个高风险面。因此至少应做到：

  1. 使用测试设备、测试账号和最小权限 API key；生产设备不要作为首次试验环境。
  2. 将读取、草拟和执行区分开；涉及发送、支付、删除、授权、发布时必须由人确认最终动作。
  3. 限制任务的目标 App、最大步数、网络访问和模型提供商；不要接受来自不可信通知、网页或聊天内容的可执行指令。
  4. 开启 debug、保存轨迹或接入 tracing 时，按敏感日志处理截图、UI 文本、凭据与联系人信息，并设置保留期。
  5. 任务结束后，按需关闭 USB/无线调试并审查或撤销不再需要的 Portal 无障碍权限。

这与桌面 GUI Agent 的权限原则相通；macOS Computer Use 方案对比中讨论的“观察与执行分离、关键节点人工确认”同样适用于手机。移动端的额外难点是个人账号、验证码、通知和生物识别往往更集中在同一台设备上。

结论

Mobilerun 的价值在于把 LLM Agent 的推理能力接到真实移动设备的原生交互面：UI 树提供结构化观察，截图弥补视觉信息，CLI 和 Python API 则把一次性任务扩展为可编排工作流。它适合真实机上的探索与半自动化，不应替代安全关键、合规关键或需要强确定性的接口与测试。先从只读、低风险、可复盘的任务开始，验证设备、模型和目标 App 的组合后再逐步扩大范围。

关系图谱

反向链接