Open-AutoGLM：基于视觉大模型的手机端智能体部署与开发实战

1. 项目概述：当你的手机学会“自己动”

想象一下，你正瘫在沙发上，突然想点个外卖，但手机在茶几那头充电。你懒得起身，于是对着空气说了一句：“帮我打开美团，搜一下附近的披萨店，选个评分4.5以上的下单。”几秒钟后，你的手机屏幕自己亮起，应用图标被精准点击，搜索框里自动输入了“披萨”，页面开始滚动筛选，最后停在了一家你常去的店，购物车页面已经打开，就等你确认支付了。

这听起来像是科幻电影里的场景，但今天，它已经是一个可以运行在你电脑和手机上的开源项目。这就是Open-AutoGLM，一个由智谱AI开源的手机端智能体框架。它的核心目标很简单：让AI能“看懂”你的手机屏幕，并“动手”帮你完成操作。你不再需要一步步手动点击，只需用最自然的语言下达指令，剩下的交给这个“手机管家”去思考、规划和执行。

这个项目的出现，标志着一个新趋势的开始：AI正在从“对话”走向“实操”。过去几年，我们见证了AI在文本生成、图像创作上的飞跃，但它们大多停留在“说”和“画”的层面。Open-AutoGLM则试图解决一个更接地气的问题：如何让AI真正融入我们的数字生活，成为能操作具体应用、完成实际任务的“数字手脚”。无论是帮你比价购物、整理相册、回复消息，还是完成一系列复杂的多应用工作流，它都提供了一个可编程、可扩展的自动化大脑。

对于开发者、自动化爱好者和任何对AI应用前沿感兴趣的人来说，理解并上手这个项目，就像是拿到了通往下一代人机交互的钥匙。它不仅仅是一个工具，更是一个探索“具身智能”在移动设备上如何落地的绝佳实验场。接下来，我将带你从零开始，深入拆解这个框架的每一个齿轮，分享我在部署和调试过程中踩过的坑、总结的技巧，让你不仅能复现，更能理解其背后的设计哲学。

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

要理解Open-AutoGLM，我们不能只把它看作一个“自动化脚本”。它是一个完整的感知-决策-执行闭环系统。其核心工作流可以概括为以下四个步骤，这构成了整个系统的骨架：

1. 视觉感知：通过ADB（Android调试桥）或HDC（鸿蒙调试桥）实时捕获手机屏幕截图。
2. 意图理解：将截图和你的自然语言指令（如“把这张照片发微信给妈妈”）一起，送入一个名为AutoGLM-Phone的多模态大模型。这个模型经过特殊训练，能“看懂”屏幕上的UI元素（按钮、输入框、图标）及其含义。
3. 动作规划：模型基于对当前屏幕的理解和你的最终目标，进行“思考”（思维链推理），规划出下一步最应该执行的具体操作，比如Tap(坐标)、Type(文本)、Swipe等。
4. 指令执行：系统将模型输出的结构化操作指令，通过ADB/HDC发送给手机执行，然后回到第一步，进入下一个循环，直到任务完成或达到最大步数限制。

这个循环的精妙之处在于，它模拟了人类操作手机的过程：看一眼屏幕，想一想该点哪里，然后动手。下面，我们来深入剖析这个流程中的几个关键设计选择及其背后的考量。

2.1 为什么选择“视觉模型+坐标”的方案？

你可能会有疑问：为什么不直接使用更“底层”的UI层级信息（比如Android的uiautomator提供的控件树）？那样不是更精确吗？这个选择恰恰体现了项目团队对泛化能力和开发效率的权衡。

• 泛化能力是王道：UI层级信息虽然精确，但它严重依赖于应用的具体实现。不同应用、甚至同一应用的不同版本，其控件ID、层级结构都可能发生变化。一个为微信定制的脚本，很可能在抖音上完全失效。而视觉模型的方案则具有极强的泛化性。模型学习的是“一个看起来像搜索框的区域应该输入文字”、“一个红色的播放按钮应该被点击”这类视觉模式。只要应用界面在视觉上符合人类认知，模型就能理解并操作。这意味着，同一个模型无需修改就能适配成千上万款应用。
• 开发与维护成本：基于UI层级的自动化需要为每个应用、每个主要页面编写和维护定位逻辑，工作量巨大。视觉方案将这份“理解”工作交给了预训练好的大模型，开发者只需关注任务逻辑和系统集成，大大降低了开发门槛和长期维护成本。
• 对“黑盒”应用的兼容性：许多应用，特别是游戏或一些使用自定义渲染引擎的应用，其UI控件树对自动化工具是不可见的。视觉是穿透这些“黑盒”的唯一通用方式。

当然，这个方案也有挑战，主要是精度和稳定性。点击坐标的微小偏差可能导致误操作。项目通过模型训练（让模型更精准地输出坐标）和执行层的一些容错机制（如对可点击区域进行模糊匹配）来缓解这个问题。在实际测试中，对于主流应用的标准化UI组件，其操作准确率已经相当可观。

2.2 模型选型：AutoGLM-Phone的核心能力

项目的“大脑”是AutoGLM-Phone-9B模型。它不是通用的图文模型，而是针对手机界面理解和操作指令生成进行了专项微调的模型。这带来了几个关键特性：

• 多模态理解：能同时处理图像（屏幕截图）和文本（用户指令），理解两者间的关联。
• 结构化输出：模型被训练为输出固定的JSON格式动作指令，如{"action": "Tap", "element": [x, y]}，而不是一段描述性文字。这保证了下游执行模块能可靠地解析。
• 思维链（Chain-of-Thought）：在输出最终动作前，模型会在内部进行推理，例如：“用户想发微信。当前屏幕是桌面。所以我需要先找到微信图标并点击。”项目提供的检查脚本可以输出这段“思考过程”，这对于调试和理解模型决策逻辑至关重要。
• 中文场景优化：基础版（AutoGLM-Phone-9B）针对中文应用进行了深度优化，对淘宝、微信、小红书等国内App的界面元素识别和操作逻辑更贴合。同时还提供了多语言版（AutoGLM-Phone-9B-Multilingual）以支持更广泛的场景。

一个重要的实践心得：模型的质量直接决定了Agent的天花板。如果模型无法正确理解某个小众应用的界面，那么后续的所有执行都无从谈起。因此，在项目初期，花时间验证模型对你目标应用的理解能力，比盲目调试代码更重要。

2.3 执行层：ADB与HDC的双重支持

执行层是连接“数字大脑”和“物理手机”的桥梁。项目同时支持Android的ADB和鸿蒙的HDC，这是一个具有前瞻性的设计。

• ADB：安卓生态的标准调试工具，历史悠久，命令丰富且稳定。它是目前最主流的测试和自动化接口。
• HDC：鸿蒙系统自带的调试工具，随着HarmonyOS NEXT的推进，支持HDC意味着项目能覆盖未来的纯血鸿蒙应用生态。

这里有一个容易踩的坑：很多教程只提ADB。如果你用的是较新的鸿蒙设备（特别是HarmonyOS NEXT），必须使用--device-type hdc参数，并确保HDC工具已正确安装和配置，否则设备根本无法识别。我在第一次接触华为Mate 60 Pro时就在这里卡了半小时，最后才发现需要切换调试桥。

框架抽象了ADBConnection和HDCConnection类，上层Agent无需关心底层是哪种协议，只需调用统一的tap,swipe,screenshot等方法，这大大提升了代码的复用性和可维护性。

3. 从零开始的完整部署与实操指南

理论讲得再多，不如亲手跑通一遍。我将以最常见的场景——在Windows/macOS电脑上，控制一台安卓手机，使用云端模型服务——为例，带你走完整个部署流程。请严格按照步骤操作，我会在每个环节注明我踩过的坑和注意事项。

3.1 第一阶段：手机端“铺路”——基础配置

这是所有步骤中最关键的一环，手机配置不正确，后面一切免谈。

步骤1：开启开发者选项与USB调试

1. 进入手机【设置】>【关于手机】，连续点击【版本号】7次，直到出现“您已处于开发者模式”的提示。
2. 返回【设置】，找到新出现的【开发者选项】（通常在【系统与更新】或【更多设置】里）。
3. 在【开发者选项】中，找到并开启【USB调试】。
4. （极其重要）寻找并开启【USB调试（安全设置）】。这个选项允许ADB在锁屏状态下进行模拟输入，很多自动化操作失败都是因为它没开。不同厂商命名可能略有不同，如“允许通过USB调试修改权限”等。

步骤2：安装并启用ADB Keyboard

1. 在手机浏览器中打开https://github.com/senzhk/ADBKeyBoard/blob/master/ADBKeyboard.apk，下载并安装此输入法。
2. 进入手机【设置】>【系统与更新】>【语言和输入法】>【虚拟键盘】。
3. 找到【ADB Keyboard】，点击进入并【启用】。
4. （可选但建议）在同一界面，将【ADB Keyboard】设为当前输入法之一。Agent会在需要输入时自动切换，但提前设好可避免权限问题。

踩坑实录：我曾遇到在输入框长按无法弹出输入法选择菜单的情况，导致Agent无法切换至ADB Keyboard。解决方案是，在电脑上通过命令adb shell ime set com.android.adbkeyboard/.AdbIME直接设置其为默认输入法。完成后，记得用adb shell ime set com.sohu.inputmethod.sogou/.SogouIME（换成你的常用输入法）改回来，否则日常使用会不方便。

步骤3：连接电脑并授权

1. 使用一条确认支持数据传输的USB线连接手机和电脑。很多廉价的充电线只有电源线，没有数据线，会导致连接失败。
2. 连接后，手机屏幕会弹出“允许USB调试吗？”的对话框，勾选“始终允许”，并点击【确定】。

3.2 第二阶段：电脑端“搭桥”——环境准备

步骤1：安装ADB工具

• macOS：最简单的方式是通过Homebrew安装：brew install android-platform-tools。
• Windows：
  1. 前往 Android开发者平台工具页面 下载platform-tools压缩包。
  2. 解压到一个你喜欢的路径，例如C:\android-platform-tools。
  3. 将此路径添加到系统的PATH环境变量中。具体步骤：右键“此电脑”->“属性”->“高级系统设置”->“环境变量”，在“系统变量”中找到Path，编辑并添加新路径。

步骤2：验证连接打开命令行终端（Windows用CMD或PowerShell，macOS用Terminal），输入：

adb devices

如果一切正常，你会看到类似以下的输出：

List of devices attached abcdefg123456 device

这表示你的设备已被识别。如果显示unauthorized，请检查手机端的授权弹窗；如果什么都没显示，请检查USB线、接口和开发者选项。

步骤3：获取项目代码并创建Python环境

# 克隆项目仓库 git clone https://github.com/zai-org/Open-AutoGLM.git cd Open-AutoGLM # 创建并激活虚拟环境（强烈推荐，避免包冲突） python -m venv venv # macOS/Linux: source venv/bin/activate # Windows: venv\Scripts\activate # 安装项目依赖 pip install -r requirements.txt pip install -e .

-e参数代表“可编辑模式”安装，这样你修改项目中的任何Python代码，都能立即生效，非常适合后续的二次开发。

3.3 第三阶段：连接“大脑”——模型服务配置

这是项目的核心依赖。对于大多数个人开发者和体验者，我强烈推荐使用第三方云服务，省去本地部署模型对GPU显存（约需20GB以上）和复杂配置的依赖。

方案A：使用智谱AI官方API（最便捷）

1. 访问 智谱AI开放平台 ，注册并登录。
2. 在控制台申请API Key。通常会有一定额度的免费试用。
3. 记下你的API Key。模型名称固定为autoglm-phone，API基础地址为https://open.bigmodel.cn/api/paas/v4。

方案B：使用ModelScope（魔搭社区）API

1. 访问 ModelScope ，注册登录。
2. 在模型页面 AutoGLM-Phone-9B 页面，点击“在线体验”或查看文档获取API调用方式。通常也需要创建API Key。
3. 其基础地址为https://api-inference.modelscope.cn/v1，模型名为ZhipuAI/AutoGLM-Phone-9B。

方案C：本地部署模型（仅限拥有高性能GPU的用户）如果你有一张显存充足的NVIDIA显卡（如RTX 3090/4090或A100），可以尝试本地部署，获得更低的延迟和完全的控制权。

# 安装vLLM推理框架 pip install vllm # 启动模型服务（这会自动从Hugging Face下载约20GB的模型文件） python -m vllm.entrypoints.openai.api_server \ --served-model-name autoglm-phone-9b \ --model zai-org/AutoGLM-Phone-9B \ --max-model-len 25480 \ --port 8000

启动成功后，模型服务地址为http://localhost:8000/v1。请注意，官方文档中提到的--mm-encoder-tp-mode等参数是针对多GPU张量并行的，单卡运行可以省略，否则可能报错。

3.4 第四阶段：“点火”测试——运行你的第一个Agent

现在，让我们用最简单的命令来验证整个链路是否打通。假设你使用智谱AI的API。

# 将 YOUR_API_KEY 替换为你的真实Key python main.py --base-url https://open.bigmodel.cn/api/paas/v4 --model autoglm-phone --apikey YOUR_API_KEY "打开设置，进入关于手机页面"

执行这条命令后，你应该会看到：

1. 终端开始打印日志，模型服务被调用。
2. 你的手机屏幕自动亮起，解锁（如果设置了锁屏密码，这里会卡住，需要先手动解锁）。
3. 手机自动打开“设置”应用，并滚动或点击进入“关于手机”页面。

恭喜！如果你的手机完成了这一系列操作，那么最基本的部署就成功了。你可以尝试更复杂的任务，比如“打开微信，找到文件传输助手，发送消息‘Hello AutoGLM’”。

4. 核心功能深度解析与高级用法

在成功运行基础任务后，我们可以深入探索框架提供的更多能力，让它真正成为你的得力助手。

4.1 远程控制：摆脱USB线的束缚

一直连着USB线太不方便了。Open-AutoGLM支持通过Wi-Fi进行远程ADB调试，让你能在同一个局域网内无线控制手机。

配置步骤：

1. 确保手机和电脑连接同一Wi-Fi网络。
2. 用USB线将手机与电脑连接一次，进行初始设置。
3. 在电脑终端执行：adb tcpip 5555。这个命令将ADB守护进程切换到监听TCP/IP的5555端口。
4. 拔掉USB线。
5. 在手机上进入【设置】>【关于手机】>【状态信息】，查看手机的IP地址（或直接在Wi-Fi设置中查看）。
6. 在电脑终端执行：adb connect 手机IP地址:5555，例如adb connect 192.168.1.100:5555。
7. 再次运行adb devices，你应该能看到一个通过IP地址连接的设备。

现在，运行Agent时，你可以通过--device-id参数指定这个远程设备：

python main.py --base-url YOUR_MODEL_URL --device-id 192.168.1.100:5555 "打开抖音"

注意事项：手机重启后，可能需要重新用USB线执行一次adb tcpip 5555来重新开启网络调试端口。

4.2 Verbose模式：窥探AI的思考过程

在调试或单纯好奇AI如何决策时，--verbose参数（或在代码中设置verbose=True）是你的最佳伙伴。它会打印出模型完整的“思维链”和每一步执行的动作。

python main.py --base-url YOUR_MODEL_URL --verbose "打开美团，搜索咖啡厅"

输出会类似这样：

================================================== 💭 思考过程: -------------------------------------------------- 用户想要打开美团并搜索咖啡厅。当前屏幕是系统桌面。我需要先找到美团应用的图标。 美团图标通常是一个袋鼠形象，颜色是黄色。让我在桌面上寻找这个图标。 -------------------------------------------------- 🎯 执行动作: { "action": "Launch", "app": "美团" } ================================================== ...（执行后，新的截图和思考）... 💭 思考过程: -------------------------------------------------- 美团应用已成功打开。现在位于首页。顶部应该有一个搜索框。我需要点击搜索框以激活输入。 搜索框通常位于页面顶部中央，有一个放大镜图标和“搜索商家/商品”的提示文字。 -------------------------------------------------- 🎯 执行动作: { "action": "Tap", "element": [360, 180] # 点击搜索框的坐标 }

通过这个输出，你可以清晰地看到AI是如何分解任务、识别界面元素并做出决策的。这对于排查“为什么它点错了地方”这类问题非常有帮助。

4.3 安全护栏：敏感操作确认与人工接管

让AI完全自主操作手机存在风险，比如误触支付、发送隐私信息等。框架内置了两道安全护栏：

1. 敏感操作确认回调：当Agent即将执行某些预定义的敏感操作（如涉及“支付”、“转账”、“删除”等关键词）时，会暂停并调用一个回调函数向你确认。你可以自定义这个函数，例如弹出一个命令行确认框。
2. 人工接管回调：当遇到模型无法处理的场景，如复杂的图形验证码、人脸识别登录、非标准弹窗时，Agent会主动调用Take_over动作，并触发人工接管回调。这时，你需要手动在手机上完成操作，然后在终端按回车，Agent会继续执行后续任务。

在Python API中，你可以这样使用它们：

from phone_agent import PhoneAgent def my_confirmation(message): """自定义确认函数""" user_input = input(f"⚠️ 即将执行敏感操作: {message}\n确认执行？(y/n): ") return user_input.lower() == 'y' def my_takeover(message): """自定义接管函数""" print(f"🤖 请求人工接管: {message}") input("请手动在手机上完成操作，完成后按回车键继续...") agent = PhoneAgent( base_url=your_model_url, confirmation_callback=my_confirmation, # 传入确认回调 takeover_callback=my_takeover # 传入接管回调 ) agent.run("给我的好友张三微信转账100元")

这样，当任务进行到“点击转账按钮”或“输入金额”时，程序会暂停并等待你的确认，极大地增强了可控性和安全性。

5. 二次开发指南：定制你的专属手机助手

Open-AutoGLM作为一个开源框架，其真正的威力在于可扩展性。你可以基于它构建更复杂、更专用的自动化流程。

5.1 项目结构导读

理解项目结构是二次开发的第一步：

phone_agent/ ├── agent.py # 核心Agent类，协调感知、决策、执行循环 ├── model/ │ └── client.py # 封装与AI模型API的通信 ├── adb/ # Android设备控制层 │ ├── connection.py # 设备连接管理（USB/Wi-Fi） │ ├── screenshot.py # 屏幕截图捕获 │ ├── input.py # 模拟键盘输入（依赖ADB Keyboard） │ └── device.py # 基础动作执行（点击、滑动等） ├── hdc/ # 鸿蒙设备控制层（结构与adb/类似） ├── actions/ │ └── handler.py # 动作执行器，解析模型输出并调用adb/hdc ├── config/ │ ├── apps.py # 应用包名映射（如“微信” -> com.tencent.mm） │ ├── prompts_zh.py # 中文系统提示词，定义AI的“角色”和能力 │ └── prompts_en.py # 英文系统提示词 └── examples/ # 示例代码

5.2 扩展现有应用支持列表

框架内置了50多款常见应用的支持。但如果你常用的App不在列表中（例如某个小众笔记软件），可以轻松添加。

1. 找到phone_agent/config/apps.py文件。
2. 在APP_PACKAGES字典中添加新的映射。键是应用在中文指令中的名称，值是应用的包名（Package Name）。

APP_PACKAGES = { "微信": "com.tencent.mm", "淘宝": "com.taobao.taobao", "我的笔记": "com.example.mynotes", # 新增 # ... 其他应用 }

如何获取包名？最简单的方法是，在手机上打开该应用，然后在电脑终端执行adb shell dumpsys window | grep mCurrentFocus（Android）或查看应用信息。

5.3 编写自定义自动化流程脚本

main.py适合单次任务。对于复杂的、多步骤的定制化流程，最好编写独立的Python脚本。

from phone_agent import PhoneAgent import time def daily_morning_routine(agent): """一个自定义的晨间自动化流程""" print("开始执行晨间流程...") # 1. 关闭闹钟（假设闹钟应用已支持） agent.run("关闭闹钟") time.sleep(2) # 2. 查看天气 agent.run("打开天气应用") # 这里可以添加逻辑：截图，然后用OCR或模型解析天气信息并播报 time.sleep(3) # 3. 播放新闻简报 agent.run("打开网易云音乐，播放我的‘晨间新闻’歌单") time.sleep(60) # 听一分钟 # 4. 发送早安消息 agent.run("打开微信，给‘家人群’发送消息：早安，我起床了。") print("晨间流程执行完毕。") if __name__ == "__main__": agent = PhoneAgent(base_url="你的模型地址") daily_morning_routine(agent)

你可以将这个脚本设置为电脑开机自启动，配合远程ADB，实现真正的自动化。

5.4 集成到其他系统

PhoneAgent的Python API设计得很清晰，可以很容易地集成到Web服务、机器人框架或其他系统中。

from flask import Flask, request, jsonify from phone_agent import PhoneAgent app = Flask(__name__) agent = PhoneAgent(base_url="你的模型地址") # 全局初始化一个Agent @app.route('/execute', methods=['POST']) def execute_task(): data = request.json task = data.get('task') if not task: return jsonify({'error': 'No task provided'}), 400 try: result = agent.run(task) return jsonify({'status': 'success', 'result': result}) except Exception as e: return jsonify({'status': 'error', 'message': str(e)}), 500 if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

这样，你就创建了一个简单的HTTP服务，可以通过发送POST请求（如{"task": "打开支付宝查余额"}）来远程触发手机自动化任务。

6. 实战避坑与疑难杂症排查

在实际使用中，你一定会遇到各种各样的问题。下面是我在深度使用过程中总结的“血泪经验”，希望能帮你快速排雷。

6.1 连接与设备问题排查表

6.2 模型与执行逻辑问题

6.3 性能优化小贴士

1. 使用云端API：对于绝大多数用户，云端API（智谱、ModelScope）是最佳选择，省去了本地部署的硬件成本和运维烦恼。
2. 精简截图分辨率：默认截图是全分辨率，传输和处理耗时。如果手机屏幕是2K或4K，可以考虑在screenshot.py中修改代码，将截图缩放至1080p以下，能显著提升速度，且对模型识别精度影响很小。
3. 缓存模型响应：对于重复性任务，如果界面变化不大，可以考虑缓存模型的“思考”结果，避免重复调用API产生不必要的开销。
4. 任务拆解：过于复杂的指令（如“帮我规划周末旅行，订机票酒店并生成攻略”）容易导致模型困惑。将其拆解成“打开携程”、“搜索北京到上海的机票”等原子任务序列执行，成功率更高。

7. 展望与进阶思考：不止于“自动化”

Open-AutoGLM为我们打开了一扇门，但门后的世界远不止简单的“自动化”。结合我自己的实验，这里有几个值得探索的进阶方向：

方向一：多设备协同与工作流当前Agent控制单台设备。想象一下，一个中心AI协调多个手机Agent：一个负责监控电商价格，一个负责爬取社交媒体信息，另一个负责自动回复消息。它们之间通过消息队列通信，共同完成一个复杂的商业或研究任务。

方向二：与RPA（机器人流程自动化）结合将手机Agent作为RPA流程中的一个环节。例如，一个企业级的RPA流程可以从电脑ERP系统获取数据，然后通过手机Agent自动登录微信小程序完成审批、或在移动端App上提交报表，打通PC与移动端的自动化壁垒。

方向三：强化学习（RL）微调项目引用的论文《MobileRL》提到了在线强化学习。这意味着Agent可以从自己的成功和失败中学习。你可以搭建一个环境，让Agent尝试完成某个任务，根据成功与否给予奖励或惩罚，让它自我进化，针对特定应用（如公司内部复杂的OA系统）训练出专家级的操作能力。

方向四：无障碍辅助对于视障或行动不便的用户，一个能准确理解屏幕内容并代为操作的Agent，可能比现有的读屏软件更加高效和自然。这不仅是技术探索，更具有深刻的社会价值。

部署和使用Open-AutoGLM的过程，就像在教一个刚学会看和动的小孩如何使用智能手机。开始时它笨手笨脚，但每一次成功的任务，都让我们离“智能体普遍应用”的未来更近一步。这个项目最大的价值不在于它现在能做什么，而在于它提供了一个坚实、可扩展的基座，让每个开发者都能在此基础上，构建自己想象中的那个“智能数字助理”。