MobiAgent：基于视觉语言模型的移动端智能体框架实战指南

在人工智能与自动化领域，智能体（Agent）技术正成为连接数字世界与现实操作的关键桥梁。其核心原理在于，通过感知环境、理解任务、规划步骤并执行动作，实现自主完成目标。这项技术的核心价值在于将人类从重复、繁琐的交互中解放出来，提升效率与准确性。在众多应用场景中，移动设备自动化因其高频、刚需的特性，成为智能体技术落地的重要方向。传统基于坐标的脚本自动化方案脆弱且难以维护，而结合了视觉理解与任务规划的智

FasterThanMind

533人浏览 · 2026-04-25 11:57:16

FasterThanMind · 2026-04-25 11:57:16 发布

1. 项目概述：一个能“看懂”手机屏幕并帮你干活的智能体

如果你曾经幻想过，能有一个助手直接在你的手机屏幕上“看到”App界面，然后像真人一样点击、滑动、输入，帮你完成从“在小红书上找相机推荐”到“去淘宝比价并微信分享”这样一连串复杂的跨应用任务，那么MobiAgent就是你正在寻找的那个答案。这不是一个简单的自动化脚本，而是一个集成了视觉理解、任务规划、动作执行和记忆学习能力的 系统性移动智能体框架 。简单来说，它让AI学会了“使用手机”。

我最初接触这类项目，是因为厌倦了在测试和演示中反复进行那些固定、枯燥的手机操作。传统的自动化工具（如基于坐标的脚本）极其脆弱，屏幕分辨率一变、UI布局一改，脚本就全废了。而MobiAgent的核心突破在于，它让智能体真正“理解”屏幕内容：通过视觉模型（Vision Language Model）分析截图，识别出UI元素（如按钮、输入框、文本）及其语义，然后生成符合当前上下文的具体操作指令（如“点击‘登录’按钮”、“在搜索框输入‘单反相机’”）。这使其具备了强大的泛化能力和适应性。

这个框架不仅仅是一个模型，它是一套完整的生态系统，包含三个核心部分：

MobiMind智能体模型家族 ：负责“看”和“想”的视觉语言模型，是系统的大脑。
AgentRR智能体加速框架 ：负责“记”和“快”，通过记录和回放成功的操作序列来加速后续相似任务的执行。
MobiFlow智能体评测基准 ：一套基于里程碑有向无环图（Milestone DAG）的评估体系，用于科学、量化地衡量智能体的任务完成能力。

对于开发者、研究者，或者任何对移动端AI自动化感兴趣的人来说，MobiAgent提供了一个绝佳的研究和实践平台。你可以用它来构建个性化的手机助手，自动化日常繁琐操作，或者深入探索具身智能（Embodied AI）在移动设备上的前沿应用。接下来，我将带你深入拆解这个框架，从设计思路到实操部署，分享我踩过的坑和总结的经验。

2. 核心架构与设计思路拆解

MobiAgent的设计充分体现了“系统化”思维，它不是将一个大模型生硬地塞给手机，而是构建了一个分层、解耦、可扩展的智能体系统。理解这个架构，是有效使用和二次开发的关键。

2.1 分层决策与执行流程

MobiAgent的典型工作流遵循“规划-决策-落地”的范式，对应其架构中的三个核心服务，这种设计借鉴了机器人学中的经典分层控制思想，并将其适配到了GUI交互领域。

2.1.1 规划层（Planner） 这是任务的总指挥，通常由一个具备较强推理能力的纯文本大语言模型（如Qwen-4B-Instruct）担任。它的输入是用户的自然语言指令（例如：“帮我查一下明天北京的天气，并设定一个晚上8点的提醒”），输出是一个 高层次的任务分解计划 。这个计划不是具体的操作，而是步骤描述，比如： [1. 打开天气应用； 2. 查询北京天气； 3. 打开时钟应用； 4. 创建晚上8点的提醒] 。规划层的作用是理解用户意图的复杂性，并将其拆解为一系列可顺序执行的子目标。

2.1.2 决策层（Decider） 决策层是MobiMind模型的核心能力之一。它接收来自规划层的当前子任务（如“打开天气应用”）和当前手机屏幕的截图。它的职责是进行 屏幕语义理解 和 原子动作生成 。具体来说，它需要：

理解屏幕 ：识别截图中的所有UI元素（图标、文本、按钮等）及其功能。
判断状态 ：结合任务，判断当前屏幕是否处于完成任务所需的状态。例如，对于“打开天气应用”，如果当前屏幕是桌面，Decider需要识别出天气应用的图标。
生成动作 ：输出一个原子操作指令，如 tap(icon_weather) （点击天气图标）。这个动作必须是当前屏幕环境下可执行且最可能推进任务的一步。

2.1.3 落地层（Grounder） 在早期版本中，Grounder是一个独立的模块，负责将Decider生成的抽象动作（如 tap(icon_weather) ） 具体化为设备可执行的坐标或ADB命令 （如 adb shell input tap 540 1200 ）。它需要精确的元素定位能力。在最新的MobiMind-1.5-4B等模型中，Decider和Grounder的功能被整合进一个端到端（End-to-End）模型，即模型直接输出可执行的坐标，这简化了流程并减少了延迟。

实操心得：为什么需要分层？ 直接让一个模型“看完指令和截图就输出点击坐标”是一种端到端思路，看似简单，但在复杂任务上容易失败，且调试困难。分层设计的好处在于：

模块化与可维护性 ：每一层职责清晰，可以独立优化和替换。例如，你可以升级Planner模型来获得更好的任务分解能力，而不影响Decider。

错误隔离与调试 ：任务失败了，可以很容易定位是规划不合理、决策错误还是坐标定位不准。

引入记忆与加速 ：AgentRR框架主要在决策-落地层面进行加速，记录成功的 (屏幕状态，动作，结果状态) 三元组，方便后续检索复用。

2.2 记忆系统的设计哲学

记忆是智能体体现“智能”和“个性化”的关键。MobiAgent集成了三种记忆，分别服务于不同目的：

2.2.1 用户画像记忆（User Profile Memory） 这是 长期、静态的个性化记忆 。想象一下，你的手机助手如果知道你喜欢性价比高的电子产品、习惯用微信沟通工作、经常浏览小红书，那么当你下达一个模糊指令如“找一款相机”时，它就能主动倾向于搜索“性价比单反”并在小红书查找，最后通过微信分享。技术上，这通常通过一个向量数据库（如Milvus）存储用户偏好特征，在规划阶段作为上下文提供给Planner模型。

2.2.2 经验记忆（Experience Memory） 这是 中期、任务相关的动态记忆 。当智能体成功完成一个任务（如“在小红书搜索相机并分享”）后，整个任务轨迹（包括规划步骤、每一步的屏幕和动作）可以被抽象和存储。未来遇到类似任务时，Planner可以直接检索并参考这个“经验包”，快速生成规划，甚至跳过一些试错步骤。这显著提升了复杂任务的执行效率。

2.2.3 动作记忆（Action Memory - AgentRR） 这是 短期、操作层面的缓存记忆 ，也是AgentRR框架的核心。它记录的是最细粒度的成功操作对。例如，在某个特定的小红书首页界面， tap(搜索框) 这个动作总是能成功。AgentRR会把这个 (屏幕特征，动作) 对缓存起来。下次再遇到高度相似的屏幕时，直接调用缓存的动作执行，无需再调用耗时的Decider模型进行推理。这对于加速应用内固定流程（如登录、导航）效果极佳。

注意事项：记忆系统的权衡 开启记忆系统（尤其是向量数据库和图数据库）会引入额外的部署复杂性和运行时开销。对于简单的、一次性的自动化任务，可能不需要开启。但对于构建长期服务的个性化助手，记忆系统是提升体验的必选项。建议先从基础模式跑通，再逐步按需引入记忆模块。

3. 环境搭建与核心配置实战

纸上得来终觉浅，绝知此事要躬行。下面我将以在Ubuntu 22.04系统上，控制一台安卓手机为例，详细演示如何从零搭建MobiAgent的运行环境。这个过程会涉及Python环境、模型服务、手机调试和记忆组件等多个环节。

3.1 基础软件环境准备

首先，我们需要一个干净的Python环境。使用Conda可以很好地隔离依赖。

# 创建并激活一个名为MobiAgent的Python 3.10环境
conda create -n MobiAgent python=3.10 -y
conda activate MobiAgent

接下来安装基础依赖。MobiAgent提供了两个依赖文件：

requirements_simple.txt : 仅包含运行智能体执行器（Runner）的最小依赖，适合快速体验。
requirements.txt : 包含数据收集、处理等全流程工具链的完整依赖。

对于大多数只想体验核心功能的用户，安装简单版即可：

pip install -r requirements_simple.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你计划进行二次开发或使用全部功能，则安装完整版：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

踩坑记录：依赖冲突 这类项目依赖较多，容易发生版本冲突。如果遇到 opencv-python 、 torch 等库的安装问题，可以尝试先安装PyTorch（根据你的CUDA版本），再安装其他依赖。例如，对于CUDA 11.8： pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 然后再安装 requirements.txt 。

3.2 手机端配置与ADB连接

智能体需要通过ADB（Android Debug Bridge）控制手机。这是整个流程中硬件相关且容易出错的一步。

3.2.1 在电脑上安装ADB工具

Ubuntu/Debian : sudo apt install android-tools-adb
macOS : brew install android-platform-tools
Windows : 下载 Android SDK Platform-Tools 并解压，将其路径加入系统环境变量。

3.2.2 在手机上开启开发者模式

进入手机“设置” -> “关于手机”，连续点击“版本号”7次，直到出现“您已处于开发者模式”的提示。
返回设置，找到新出现的“开发者选项”。
在开发者选项中，开启“USB调试”。部分手机还需要开启“USB调试（安全设置）”以允许通过ADB输入文本。

3.2.3 安装ADBKeyboard输入法 由于ADB默认的输入法在某些场景下无法输入中文或效率低下，我们需要安装一个专门的ADB输入法。

# 下载APK文件
wget https://github.com/senzhk/ADBKeyBoard/raw/master/ADBKeyboard.apk
# 通过ADB安装到手机
adb install ADBKeyboard.apk

安装后，在手机的“设置”->“系统”->“语言与输入法”->“虚拟键盘”中，找到“ADBKeyboard”并启用它。在需要输入时，通常需要手动切换到该输入法。

3.2.4 连接手机并测试 用USB数据线连接手机和电脑。在电脑终端执行：

adb devices

如果看到设备列表中出现你的设备序列号，且状态为 device ，则表示连接成功。如果显示 unauthorized ，请在手机弹出的“允许USB调试吗？”对话框中点击“确定”。

常见问题排查：ADB连接失败

设备未列出 ：检查USB线是否完好，尝试更换线缆或USB接口。重启 adb server : adb kill-server && adb start-server 。

一直处于offline状态 ：重新插拔USB线，并在手机上重新授权USB调试。

无反应 ：部分手机需要在连接模式中选择“传输文件（MTP）”而非“仅充电”。

3.3 模型服务部署与启动

MobiAgent依赖多个模型服务。官方推荐使用 vLLM 进行高性能推理部署，它支持连续批处理和PagedAttention，能极大提高吞吐量。

3.3.1 下载模型权重 你需要下载两个核心模型：

MobiMind模型 ：负责决策（Decider）和落地（Grounder）。例如最新的 MobiMind-1.5-4B 。

# 使用 huggingface-cli 下载 (需先 pip install huggingface-hub)
huggingface-cli download IPADS-SAI/MobiMind-1.5-4B-0313 --local-dir ./models/MobiMind-1.5-4B

规划模型（Planner） ：通常使用一个纯文本LLM，如 Qwen2.5-4B-Instruct 。

huggingface-cli download Qwen/Qwen2.5-4B-Instruct --local-dir ./models/Qwen2.5-4B-Instruct

3.3.2 使用vLLM启动模型服务 打开两个独立的终端窗口，分别启动Planner和MobiMind服务。

终端1 - 启动Planner服务 (端口 8002) :

conda activate MobiAgent
vllm serve ./models/Qwen2.5-4B-Instruct --port 8002 --api-key token-abc123 --served-model-name planner

终端2 - 启动MobiMind服务 (端口 8000) :

conda activate MobiAgent
vllm serve ./models/MobiMind-1.5-4B --port 8000 --api-key token-abc123 --served-model-name mobimind

参数解释 ：

--port : 指定服务监听的端口。
--api-key : 设置一个简单的API密钥，客户端连接时需要提供。
--served-model-name : 指定模型名称，在API请求中会用到。
如果你的GPU内存不足，可以添加 --gpu-memory-utilization 0.9 来更激进地利用内存，或使用 --quantization awq 加载AWQ量化版本的模型（需模型本身支持）。

3.3.3 验证服务 服务启动后，你可以通过curl命令测试：

curl http://localhost:8002/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token-abc123" \
  -d '{
    "model": "planner",
    "prompt": "Hello, what is your name?",
    "max_tokens": 10
  }'

如果返回包含生成的文本，说明服务运行正常。

3.4 可选组件：记忆系统部署

如果你需要用户画像或经验记忆功能，需要部署额外的后台服务。

3.4.1 用户画像记忆（基于Milvus） Milvus是一个向量数据库，用于存储和检索用户偏好特征。

# 使用Docker快速启动一个Milvus单机实例
docker run -d \
  --name milvus-standalone \
  -p 19530:19530 \
  -p 9091:9091 \
  -v /path/to/milvus/data:/var/lib/milvus \
  -v /path/to/milvus/conf:/etc/milvus \
  milvusdb/milvus:v2.4.0-rc.1

启动后，需要在项目根目录创建或修改 .env 文件，配置连接信息：

MILVUS_URL=http://localhost:19530
EMBEDDING_MODEL=BAAI/bge-small-zh # 用于生成特征向量的模型
EMBEDDING_MODEL_DIMS=384 # 向量维度
OPENAI_API_KEY=sk-... # 如果你使用OpenAI的LLM作为Planner
OPENAI_BASE_URL=https://api.openai.com/v1

3.4.2 图检索增强（GraphRAG，基于Neo4j） 对于更复杂的、关系型用户偏好，可以使用Neo4j图数据库。

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  -v /path/to/neo4j/data:/data \
  -v /path/to/neo4j/logs:/logs \
  neo4j:5.23.0

同样，在 .env 文件中补充配置：

NEO4J_URL=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password

注意事项：生产环境部署 以上Docker命令仅适用于开发和测试。生产环境需要考虑数据持久化卷、网络安全、资源限制和高可用性。务必为Milvus和Neo4j设置强密码，并将服务端口（19530, 7474, 7687）限制在内部网络访问。

4. 运行你的第一个智能体任务

环境就绪后，我们就可以让智能体开始工作了。MobiAgent通过一个“Runner”程序来协调所有组件。

4.1 准备任务清单

首先，我们需要定义想要智能体执行的任务。在 runner/mobiagent/ 目录下，找到或创建 task.json 文件。这是一个JSON列表，每个元素是一个任务描述。

[
  "打开微信，找到名为‘技术交流群’的群聊，查看最近一条消息",
  "在手机桌面上找到并打开浏览器应用",
  "在哔哩哔哩应用中搜索‘科技美学’并进入其主页"
]

任务描述应尽可能清晰、具体。避免使用模糊代词（如“它”、“那个”），因为Planner模型可能无法正确解析指代关系。

4.2 启动智能体执行器（Runner）

在配置好任务文件后，我们启动核心的Runner程序。这里我们演示最基础的启动方式（不使用记忆）。

# 在项目根目录下执行
python -m runner.mobiagent.mobiagent \
  --service_ip localhost \
  --decider_port 8000 \
  --planner_port 8002 \
  --device Android \
  --task_file runner/mobiagent/task.json \
  --data_dir ./run_results

关键参数详解 ：

--service_ip : 模型服务所在的IP地址，本地运行就是 localhost 。
--decider_port : MobiMind模型服务端口（我们之前启动在8000）。
--planner_port : Planner模型服务端口（我们之前启动在8002）。
--grounder_port : 在MobiMind-1.5-4B等端到端模型中已弃用，因为坐标预测功能已整合。
--device : 设备类型，支持 Android 和 Harmony （鸿蒙）。
--task_file : 任务列表文件的路径。
--data_dir : 运行结果（包括截图、动作日志、轨迹数据）的保存目录。
--e2e : 如果使用端到端模型（如MobiMind-1.5-4B），可以设置为 true 以跳过独立的Grounder调用，加速执行。

启动后，Runner会依次读取 task.json 中的每个任务，并执行以下循环：

获取屏幕 ：通过ADB截取当前手机屏幕。
调用Planner ：将用户任务和当前屏幕（可选）发送给Planner，获取任务分解计划。
循环执行子任务 ：对于计划中的每个步骤： a. 截屏。 b. 调用Decider（MobiMind），传入当前子任务和截图，获得动作指令。 c. 执行动作（通过ADB发送点击、滑动等命令）。 d. 等待界面稳定，进入下一步。
记录与保存 ：将整个执行过程的截图、动作、模型输入输出保存到 data_dir 中，用于后续分析和调试。

4.3 运行多任务协作示例

MobiAgent支持复杂的跨应用多任务。这需要启动另一个专门的Runner。例如，执行官方Demo中的任务：

python -m runner.mobiagent.multi_task.mobiagent_refactored \
  --service_ip localhost \
  --decider_port 8000 \
  --planner_port 8002 \
  --task "在小红书查找2025年性价比最高的单反相机推荐，然后在淘宝搜索该相机，并将淘宝中的相机品牌、名称和价格通过微信发送给小赵。"

这个任务会动态规划，涉及三个应用：小红书（信息获取）、淘宝（比价）、微信（通信）。Runner需要处理应用间切换、信息提取（从小红书结果中提取相机型号）和传递（将型号填入淘宝搜索框，再将结果摘要发送微信）。

实操心得：任务描述的技巧

原子化 ：对于简单任务，直接描述最终目标（如“打开微信”）。对于复杂任务，可以适度拆解（如“给张三发消息说晚上开会”），但不要过度拆解成“打开微信->点击通讯录->搜索张三...”，这反而可能限制Planner的灵活性。

提供上下文 ：如果任务涉及特定联系人、群聊或文件，确保它们在手机中存在且名称唯一。例如，“发消息给小赵”可能失败，因为可能有多个“小赵”；而“发消息给‘张三（同事）’”则更明确。

预期管理 ：当前模型能力仍在发展中，对于需要高度逻辑推理或创意性操作的任务（如“P一张图然后发朋友圈”），失败率可能较高。从简单的导航、搜索、信息传递任务开始体验。

5. 高级功能解析与性能调优

当基础功能跑通后，我们可以深入探索MobiAgent的高级特性，并对系统进行调优，以提升其可靠性、速度和智能化程度。

5.1 AgentRR：智能体加速框架实战

AgentRR（Agent Record & Replay）是MobiAgent中用于提升执行效率的核心组件。其原理是“记录成功，回放加速”。

5.1.1 工作原理

记录阶段 ：在智能体正常执行任务过程中，AgentRR会默默记录每一对成功的 (屏幕特征，动作) 。屏幕特征通常是对截图进行编码后的向量或哈希值。
检索阶段 ：当智能体再次遇到一个新屏幕时，会先在AgentRR的缓存中搜索是否有 视觉上相似 的历史屏幕。
回放阶段 ：如果找到高度相似的屏幕（相似度超过阈值），则直接取出对应的历史动作执行， 绕过Decider模型的推理过程 。由于特征匹配和动作回放的速度远快于模型前向传播，从而实现了加速。

5.1.2 启用与配置 AgentRR的集成方式在演进。一种典型的方式是在启动Runner时启用相关参数。你需要查阅 agent_rr/README.md 获取最新的集成指南。通常，它可能涉及以下步骤：

确保 agent_rr 模块已安装。
在启动Runner时添加 --enable_agentrr 或类似参数。
指定AgentRR缓存数据库的路径。

5.1.3 效果与局限

效果：对于重复性高的操作（如应用登录流程、固定界面的按钮点击），加速效果非常明显，能减少50%以上的模型调用，大幅降低任务耗时和云端计算成本。
局限：如果UI发生较大变化（如应用更新），缓存的动作可能失效甚至导致错误。因此，系统需要设计缓存失效和更新机制。通常，可以设置相似度阈值，并定期清理旧缓存。

5.2 记忆系统的集成与使用

5.2.1 启用用户画像记忆 要启用用户画像，你需要确保Milvus或Neo4j服务已运行，且 .env 配置正确。然后在启动Runner时添加参数：

python -m runner.mobiagent.mobiagent \
  ... (其他参数) \
  --user_profile on \
  --use_graphrag off  # 使用Milvus向量检索。若用Neo4j，则设为 on

启用后，Planner在规划任务时，会先查询记忆库，将用户偏好信息（如“偏好性价比产品”、“常用微信沟通”）作为系统提示词的一部分，从而生成更个性化的计划。

5.2.2 启用经验记忆 经验记忆关注的是任务层面的复用。启用方式通常是通过 --use_experience 参数：

python -m runner.mobiagent.mobiagent \
  ... (其他参数) \
  --use_experience

当执行一个新任务时，Runner会从经验库中检索语义相似的历史任务及其成功执行轨迹，并将此轨迹作为示例（few-shot）插入到给Planner的提示词中，引导其生成更可靠、更高效的规划。

性能调优建议：记忆检索的权衡 记忆检索虽然能提升规划质量，但也会增加延迟（向量检索/图查询时间）。在实时性要求高的场景，可以考虑：

异步预加载 ：在用户输入任务前，预先加载其相关的用户画像。

缓存热点记忆 ：对频繁使用的记忆条目在内存中做一层缓存。

设置超时 ：为记忆检索操作设置一个超时时间，超时后则降级为无记忆规划，保证系统响应。

5.3 模型与参数调优

5.3.1 模型选型

Planner模型 ：对长文本理解和逻辑分解能力要求高。 Qwen2.5-4B-Instruct 是一个平衡的选择。如果追求更高性能，可以尝试 Qwen2.5-7B-Instruct 或 Qwen2.5-14B-Instruct ，但需要更多GPU资源。
MobiMind模型 ：这是专门为GUI理解微调的视觉语言模型。优先选择最新版本，如 MobiMind-1.5-4B ，它通常整合了更多数据和改进的架构。注意区分“Mixed”（决策+落地）版本和“Reasoning”（可能强化推理）版本，根据需求选择。

5.3.2 vLLM服务参数

--max-model-len : 设置模型的最大上下文长度。对于GUI任务，截图经过编码后token较长，可能需要调高此值（如4096或8192）。
--tensor-parallel-size : 如果有多张GPU，可以设置张量并行以加速推理。
--gpu-memory-utilization : 控制GPU内存使用率，如果遇到内存不足（OOM）错误，可以适当调低（如0.8）。

5.3.3 Runner执行参数

--action_interval : 动作执行后的等待间隔（秒）。给界面足够的响应时间。太短可能导致操作在界面加载完成前触发，太长则降低效率。通常设置在1.0到2.0秒之间，可根据手机性能调整。
--max_steps_per_task : 单个任务允许的最大执行步数。防止智能体陷入死循环。默认值可能为50，对于复杂任务可以适当调高。
--confidence_threshold : Decider模型输出动作的置信度阈值。低于此阈值的动作可能被拒绝执行，要求模型重新思考。这可以提高动作的准确性，但可能增加重试次数。

6. 故障排查与常见问题实录

在实际部署和运行MobiAgent的过程中，你一定会遇到各种问题。下面我整理了一份常见问题速查表，涵盖了从环境、连接到执行各个阶段的典型坑点。

问题现象	可能原因	排查步骤与解决方案
ADB连接成功，但Runner报错无法截图	1. 手机屏幕锁屏。 2. ADB权限不足（部分手机需额外授权）。 3. 屏幕截图服务异常。	1. 解锁手机屏幕，并设置永不息屏（开发者选项内）。 2. 在手机开发者选项中，检查并开启“USB调试（安全设置）”。 3. 手动执行 `adb shell screencap -p /sdcard/test.png` 测试截图功能。
模型服务启动失败，提示CUDA Out of Memory	GPU内存不足。	1. 检查是否有其他进程占用GPU。 2. 使用更小的模型（如从7B换到4B）。 3. 为vLLM添加 `--gpu-memory-utilization 0.8` 参数。 4. 使用量化模型（如AWQ, GPTQ）。 5. 考虑使用CPU推理（极慢，仅用于测试）。
Planner/Decider服务返回HTTP 404或连接拒绝	1. 服务未成功启动。 2. 端口被占用。 3. Runner中配置的IP或端口错误。	1. 检查运行模型服务的终端是否有错误日志。 2. 使用 `netstat -tulnp \| grep <端口号>` 检查端口占用情况。 3. 确认Runner启动命令中的 `--service_ip` , `--decider_port` , `--planner_port` 与服务实际地址一致。
智能体执行动作错误（如点错位置）	1. Decider/Grounder模型识别不准。 2. 屏幕分辨率适配问题。 3. 动作间隔太短，界面未加载完。	1. 检查 `data_dir` 中保存的截图和对应的模型预测结果，看是识别错误还是坐标转换错误。 2. 确保Runner使用的屏幕分辨率与模型训练时适配的分辨率相近。部分模型针对1080P优化。 3. 增加 `--action_interval` 参数值。
任务卡在某个步骤无限循环	1. Planner分解出的子任务无法完成。 2. Decider无法在当前屏幕找到执行路径。 3. 遇到了模型未见过的新UI组件。	1. 查看日志，确定卡在哪一步。分析当前屏幕和子任务是否匹配。 2. 尝试调低 `--confidence_threshold` ，让模型尝试更多可能。 3. 手动干预一次，让智能体记录下成功路径（如果开启了AgentRR）。 4. 这是当前技术的局限性，需要更强大的模型或人工定义规则处理边界情况。
多任务执行时，信息在应用间传递失败	1. 信息提取（从屏幕OCR文本）不准确。 2. 规划逻辑断层，未设计信息传递步骤。	1. 检查OCR模块是否正常工作。可以尝试更换或优化OCR引擎（如从Tesseract换为PaddleOCR）。 2. 分析Planner生成的计划，看是否包含了“提取品牌和价格”、“切换到微信”、“输入提取的信息”等关键步骤。可能需要优化给Planner的提示词（Prompt）。
启用记忆系统后，Runner启动报错	1. 记忆服务（Milvus/Neo4j）未启动或连接失败。 2. `.env` 配置文件错误或路径不对。 3. 依赖库未安装。	1. 使用 `docker ps` 确认记忆服务容器正在运行。 2. 检查 `.env` 文件中的连接字符串、用户名、密码是否正确。确保文件在Runner的工作目录下。 3. 确认已安装 `pymilvus` , `neo4j` 等客户端库。

独家避坑技巧：

“先跑通，再优化” ：第一次运行时，尽量使用最简单的配置（单模型、无记忆、简单任务）。确保整个数据流（ADB截图 -> 模型推理 -> ADB执行）是通的。之后再逐步增加复杂度。
善用数据记录 ：Runner的 --data_dir 参数是你的最佳调试工具。里面保存了每一步的截图、模型接收的Prompt和返回的结果。当任务失败时，第一件事就是去这里“复盘”，直观地看到智能体“看”到了什么，“想”了什么。
模拟器是好朋友 ：在真机上反复测试耗电且可能误操作。可以考虑使用Android模拟器（如Android Studio自带的AVD）。确保模拟器开启GPU加速，并使用 adb connect <模拟器IP> 连接。模拟器的屏幕状态更稳定，便于调试。
Prompt工程微调 ：如果发现Planner总是分解错误，或Decider总是点错按钮，可以尝试修改它们对应的系统提示词（System Prompt）。这些提示词通常定义在Runner的代码中（如 runner/mobiagent/prompts.py ）。微妙的提示词调整可能带来显著的性能提升。

MobiAgent作为一个前沿的开源项目，展示了移动端智能体技术的巨大潜力。从环境搭建、模型部署到任务执行和高级功能调优，整个过程就像在组装并训练一个数字世界的“实习生”。它目前可能还不够完美，执行复杂任务时可能会“犯傻”，但它的框架设计是清晰且强大的，为后续的改进和定制提供了坚实的基础。无论是用于学术研究，还是作为构建个性化自动化工具的起点，深入理解和实践这个项目，都能让你站在移动AI自动化领域的前沿。