Open-AutoGLM 远程使用完整指南

关于UCloud(优刻得)旗下的compshare算力共享平台
UCloud(优刻得)是中国知名的中立云计算服务商，科创板上市，中国云计算第一股。
Compshare GPU算力平台隶属于UCloud，专注于提供高性价4090算力资源，配备独立IP，支持按时、按天、按月灵活计费，支持github、huggingface访问加速。
使用下方链接注册可获得20元算力金，免费体验10小时4090云算力，此外还有5090, 3090和P40，价格每小时只需要8毛，赠送的算礼金够用一整天。
https://www.compshare.cn/?ytag=GPU_lovelyyoshino_Lcsdn_csdn_display

1. 项目介绍

1.1 Open-AutoGLM 的定位与意义

Open-AutoGLM是由智谱AI在2024年10月推出的开源手机操作智能体框架。该项目基于AutoGLM模型构建，代表了在移动设备自动化领域的重要突破。与传统的移动自动化框架不同，Open-AutoGLM能够通过视觉理解和自然语言指令来完成复杂的手机操作任务，使用户仅需描述高层意图即可实现端到端的自动化流程。官方项目地址为GitHub仓库。

该框架的核心创新在于整合了多模态视觉理解、智能规划和设备控制能力。用户可以通过自然语言描述需求，例如"打开电商应用并搜索特定商品"，系统会自动解析用户意图、分析当前屏幕内容、规划执行步骤，并通过ADB（Android Debug Bridge）实现对物理设备的精确控制。这种端到端的自动化能力在移动应用测试、流程自动化和辅助功能等领域具有重大应用价值。

Open-AutoGLM目前支持超过50款主流应用，涵盖社交通讯、电商购物、生产力工具、媒体娱乐和旅游导航等多个领域。这些应用包括WhatsApp、Telegram、Amazon、eBay、Gmail、Google Calendar、Google Drive、Chrome、Google Maps和Booking.com等国际应用，以及微信、QQ、淘宝、美团等中文应用。这广泛的应用支持使得框架能够适应不同用户的实际需求。

目前相关镜像已经存入vLLM-Omni自动生成项目中了。

2. 核心概念与架构

2.1 ADB 与 Android 远程调试的原理

Android Debug Bridge（ADB）是Android官方提供的用于与Android设备进行通信的命令行工具。根据Android官方文档的定义，ADB采用客户端-服务器架构设计，包含以下三个核心组件：

客户端端：运行在开发计算机上，通过命令行与服务器通信，用户可以从终端调用ADB命令来执行各种操作。

服务器端：在启动时绑定到本地TCP端口5037，监听来自ADB客户端的命令请求。所有ADB客户端均通过端口5037与服务器建立通信通道。

守护进程（adbd）：运行在Android设备上的后台服务，负责接收来自ADB服务器的命令并在设备上执行相应操作，包括文件传输、屏幕截图、输入模拟等功能。

ADB支持多种传输方式。最初的实现方式是通过USB连接，这要求设备连接到计算机的USB端口。但从Android 11版本开始，Google在操作系统层面引入了原生无线调试支持，允许设备通过TCP/IP协议与计算机建立连接。此外，ADB还支持通过adb tcpip命令将现有的USB连接转换为TCP/IP模式，实现无线调试功能。这种灵活的架构使得Open-AutoGLM能够支持本地USB连接、WiFi远程连接等多种使用场景。

2.2 视觉模型服务的角色

Open-AutoGLM框架的决策逻辑依赖于一个支持OpenAI兼容API的视觉语言模型服务。该模型在获取设备屏幕截图后，能够：

视觉理解：分析屏幕中的UI元素、文本内容和空间布局，识别可交互的组件位置和当前应用状态。

意图规划：根据用户的自然语言指令和当前的屏幕状态，规划合理的操作序列，决定下一步应该执行的具体动作。

动作生成：输出结构化的操作命令，包括点击坐标、文本输入内容、滑动方向等，这些命令由ADB转发给设备执行。

这个模型服务可以通过多种方式获取：用户可以选择使用第三方云服务如z.ai、Novita AI或ModelScope，这些服务已经部署了AutoGLM模型；或者用户也可以在本地配有适当GPU的计算机上自行部署模型。两种方式各有优缺点，需要根据实际条件选择。

3. 本地部署指南

3.1 系统需求与硬件配置

3.1.1 计算机端系统需求

Open-AutoGLM的主程序可运行在macOS、Linux和Windows等多个操作系统上，但实际适配程度存在差异。macOS用户推荐使用10.15以上版本，特别是配备M1或M2芯片的Apple Silicon机型具有优异的性能表现。Linux用户推荐使用Ubuntu 20.04 LTS或更新版本、CentOS 7以上等主流发行版。Windows用户由于环境配置的复杂性，推荐使用Windows 10或11配合WSL2（Windows Subsystem for Linux 2）来获得更稳定的Linux环境。

Python环境方面，项目要求Python版本不低于3.9，但推荐使用3.10或3.11版本以获得更好的性能和库的兼容性。包管理工具pip的版本应为21.0或更高。

计算机的硬件配置中，CPU不必过于强劲，4核处理器基本可满足需求。内存方面建议至少8GB以上，因为vLLM等推理框架在运行时需要加载完整的模型权重和维护计算缓存。如果仅运行框架本身而使用第三方模型服务，4GB内存亦可接受。本地存储空间建议预留至少20GB，用于存放Python环境、依赖库和模型权重文件。

3.1.2 Android设备要求

Android设备需要运行Android 7.0（API级别24）或更高版本。这个版本要求相对较低，覆盖了绝大多数在用的Android设备，包括2016年及之后发布的主流机型。设备与计算机的连接需要使用支持数据传输的USB线，这是一个常见的误区——许多低价USB线仅提供充电功能，无法进行数据通信。用户可以通过在计算机上执行adb devices命令来验证USB线是否支持数据传输。

3.1.3 云端模型部署的特殊要求

若用户选择在云端部署AutoGLM模型，则对硬件配置有明显更高的要求。首先需要配备NVIDIA GPU显卡，根据社区的实践经验，使用A100-40GB或RTX 5880 Ada 48G等40GB显存级别的显卡最为稳定。一般而言，在保证推理质量的前提下，24GB显存是基本门槛，但这可能导致推理速度较慢。显卡对应的CUDA计算能力也有要求，需要CUDA 11.8及更高版本。此外，模型权重文件本身约占20GB存储空间，考虑到模型加载、缓存和日志等开销，建议预留至少30GB的SSD空间。完整的部署和测试流程通常需要2-3小时，总费用在10-15元左右。这种方式对于测试和学习开发非常经济。

3.2 前置环境配置

3.2.1 安装 ADB 工具

ADB工具是操作Android设备的基础，需要首先安装。

在macOS系统上，最便捷的安装方式是通过Homebrew包管理器。用户需要首先安装Homebrew（若未安装），然后执行以下命令：

brewinstallandroid-platform-tools adb version

执行adb version后应输出版本信息如"Android Debug Bridge version 1.0.41"等，说明安装成功。若用户倾向于手动安装，可以从Google官方平台工具下载页面下载macOS版本的工具包，解压后添加到系统PATH环境变量。

对于Linux用户（以Ubuntu/Debian为例），安装过程如下：

sudoapt-getupdatesudoapt-getinstallandroid-tools-adb android-tools-fastboot adb version

在Windows系统上，可以使用包管理器Chocolatey进行安装（前提是已安装Chocolatey）：

choco install android-platform-tools adb version

或者用户可以手动从Google官方下载Windows版本的platform-tools包，解压到指定目录如C:\platform-tools，然后将该目录路径添加到系统环境变量PATH中。具体操作为：右键点击"此电脑"→属性→高级系统设置→环境变量，在用户变量或系统变量中找到Path变量，新增一条为C:\platform-tools的路径。重启PowerShell或命令提示符后，执行adb version验证配置。

3.2.2 配置 Android 设备开发者选项

Android设备的开发者选项默认处于隐藏状态，需要手动启用。操作流程为：打开设备的设置应用，导航到"关于手机"或"About Phone"菜单，找到"Build Number"或"版本号"字段，用手指快速连续点击7-10次，直到屏幕出现提示"You are now a developer"或"您已进入开发者模式"。

启用开发者模式后，返回设置主菜单，新的"开发者选项"或"Developer Options"菜单项会出现在设置菜单中（通常在系统设置的高级选项下）。进入该菜单，启用"USB调试"或"USB Debugging"选项。这一步至关重要，因为没有启用USB调试，计算机将无法与设备建立通信。在某些设备上还需要启用"USB调试（安全设置）"或"USB Debugging (Security Settings)"这个额外的选项，才能完整支持所有远程操作。

3.2.3 验证 ADB 连接

使用支持数据传输的USB线将Android设备连接到计算机。连接时，设备屏幕可能会弹出一个对话框，询问是否允许USB调试，用户需要点击"允许"或"Always Allow"。如果没有弹出对话框，可以尝试断开重新连接。

连接后，在计算机的命令行中执行：

adb devices

成功的输出应为：

List of attached devices XXXXXXXX device

其中XXXXXXXX是设备的序列号。如果输出显示"unauthorized"，说明设备上的授权需要重新确认。解决方案为：断开USB线，在设备上进入开发者选项重置USB调试授权，重新插入USB线，重新点击"允许"。如果仍然无法识别，应检查：USB线是否支持数据传输（某些低价线仅支持充电），是否使用了正确的USB端口，ADB服务是否已启动（可执行adb kill-server && adb start-server重启）。

3.2.4 安装 ADB Keyboard 输入法

Open-AutoGLM需要通过ADB Keyboard来模拟用户的文本输入操作。这是因为标准的ADB工具无法直接向输入框发送中文等复杂文字，需要借助Android系统的输入法机制。

首先，用户需要获取ADB Keyboard的APK文件。可以从GitHub项目直接下载，或使用curl命令下载：

curl-O https://github.com/senzhk/ADBKeyBoard/raw/master/ADBKeyboard.apk

然后使用ADB命令将APK文件安装到设备：

adbinstallADBKeyboard.apk

安装完成后，需要在设备上启用ADB Keyboard作为可用的输入法。操作方式为：打开设备的设置，导航到"系统"→"语言和输入法"（不同Android版本的菜单名称可能略有差异），在"虚拟键盘"或"输入法"部分找到"ADB Keyboard"，启用它。也可以通过命令行方式启用：

adb shell imeenablecom.android.adbkeyboard/.AdbIME

为了确保输入能正常工作，建议进一步设置ADB Keyboard为默认输入法：

adb shell imesetcom.android.adbkeyboard/.AdbIME

验证设置是否成功的方式为执行：

adb shell settings get secure default_input_method

正确的输出应为com.android.adbkeyboard/.AdbIME。如果输出不符，说明ADB Keyboard设置尚未生效，需要重新按上述步骤操作。

3.3 本地部署详细步骤

本地部署需要经过多个步骤，首先需要克隆项目仓库并完成基本环境配置。

创建一个独立的Python虚拟环境是最佳实践，这样可以避免对系统环境和其他项目的影响：

gitclone https://github.com/zai-org/Open-AutoGLM.gitcdOpen-AutoGLM python3 -m venv venvsourcevenv/bin/activate# 在Windows上为: venv\Scripts\activate

激活虚拟环境后，升级pip和相关工具，然后安装项目依赖：

pipinstall--upgrade pip setuptools wheel pipinstall-r requirements.txt pipinstallvllm pipinstall-e.

安装完成后，验证基本的Python包是否可用：

python -c"from phone_agent import PhoneAgent; print('Phone Agent installed successfully')"

若出现导入错误，说明安装过程中存在问题，需要检查上述步骤是否完全执行。

本地部署的核心是启动vLLM推理服务器。这一步需要较长的执行时间（可能需要10-30分钟，取决于网络和硬件），因为系统需要自动从HuggingFace等源下载约20GB的模型文件。执行以下命令：

python3 -m vllm.entrypoints.openai.api_server\--served-model-name autoglm-phone-9b-multilingual\--allowed-local-media-path /\--mm-encoder-tp-mode data\--mm_processor_cache_type shm\--mm_processor_kwargs"{\"max_pixels\":5000000}"\--max-model-len25480\--chat-template-content-format string\--limit-mm-per-prompt"{\"image\":10}"\--model zai-org/AutoGLM-Phone-9B-Multilingual\--port8000

该命令中各参数的含义为：

--served-model-name: vLLM服务暴露给客户端的模型名称，可以任意指定但应与后续调用时一致。

--allowed-local-media-path: 允许加载的本地媒体文件的根路径，设置为/表示允许访问所有本地文件。

--mm-encoder-tp-mode: 多模态编码器的张量并行模式，data表示按数据维度进行并行。

--mm_processor_cache_type: 多模态处理器缓存类型，shm表示使用共享内存以优化性能。

--mm_processor_kwargs: 多模态处理器的配置参数，其中max_pixels设置为5000000限制单张图像的最大像素数。

--max-model-len: 模型能处理的最大序列长度，设置为25480对应模型的最大上下文长度。

--chat-template-content-format: 聊天模板的内容格式，string表示使用字符串格式。

--limit-mm-per-prompt: 单条提示词中多媒体内容的限制，{"image":10}表示每条提示最多包含10张图像。

--model: 要加载的模型在HuggingFace的完整标识。

--port: 服务器监听的本地TCP端口，默认为8000。

启动成功后，终端会输出类似"Uvicorn running on http://0.0.0.0:8000"的信息。此时可以在另一个终端标签页或窗口验证服务是否正常运行：

curl-X GET http://localhost:8000/v1/models\-H"Content-Type: application/json"

正确的返回应包含模型列表信息。若返回连接错误或超时，说明服务未成功启动，需要查看vLLM终端中的错误日志进行诊断。

常见的启动错误包括：CUDA显存不足（vLLM会输出具体的显存需求信息）、网络连接问题导致模型下载失败、Python版本或依赖库版本不匹配等。用户应根据具体的错误信息进行相应的调整。

3.4 部署验证

部署完成后，项目提供了验证脚本来检查模型服务是否可用：

python scripts/check_deployment_en.py\--base-url http://localhost:8000/v1\--model autoglm-phone-9b-multilingual

若使用第三方服务，则相应修改--base-url和--model参数，并添加--apikey参数。成功的输出应包含模型的实际推理结果、生成的token数量等统计信息，这说明模型服务可以正常工作。

4. 手机远程使用

4.1 USB连接的本地使用

在完成了环境配置和模型服务准备后，用户可以开始使用Open-AutoGLM框架。最直接的使用方式是保持USB连接，在本地计算机上执行任务。

最简单的用法是单次任务执行模式。用户通过命令行指定要执行的任务，框架执行完成后自动退出：

python main.py\--base-url http://localhost:8000/v1\--model autoglm-phone-9b-multilingual\"打开Chrome浏览器并搜索Python教程"

若使用第三方服务，则修改--base-url和--model参数，并添加--apikey参数。

对于需要执行多个连续任务的场景，可以使用交互模式。启动时不指定任务，框架会进入交互式命令提示符，等待用户输入任务描述：

python main.py\--base-url http://localhost:8000/v1\--model autoglm-phone-9b-multilingual

进入后可以逐个输入任务：

> 打开Gmail应用 > 撰写邮件给support@example.com > 输入邮件主题和内容 > 发送邮件

交互模式下，每个任务执行完毕后框架会返回提示符，允许用户输入下一个任务。这对于需要观察和验证每一步执行结果的场景特别有用。

4.2 WiFi远程调试配置

ADB提供了两种WiFi调试方式。较早的Android版本需要使用TCP/IP模式进行设置，这需要经过USB中介步骤。较新的Android设备（11及以后）支持原生的无线调试功能，使用更为便捷。

对于支持原生无线调试的设备（Android 11+）：

首先，确保计算机和Android设备连接到同一个无线网络。在设备上进入开发者选项，找到"无线调试"或"Wireless Debugging"选项，启用它。启用后，设备屏幕会显示一个IP地址和端口号的配对码。

在计算机端，打开命令行并执行：

adb connect192.168.1.100:5555

其中IP地址和端口需要替换为设备屏幕上显示的实际值。连接成功后，可以验证：

adb devices

输出应该包含该设备的连接信息，形式为192.168.1.100:5555 device。

对于较早的Android版本或特定设备：

这种方案需要先通过USB建立初始连接，然后通过ADB命令启用TCP/IP监听模式。首先用USB线连接设备，确认adb devices能识别设备，然后执行：

adb tcpip5555

这条命令会使设备启动TCP/IP监听模式，监听端口5555。此后可以断开USB线，计算机可以通过网络连接到设备。获取设备的IP地址可以通过在设备上查看WiFi设置获得，或在系统设置的关于手机页面找到IP地址字段。然后执行：

adb connect192.168.1.100:5555

成功连接后，可以像使用本地USB连接一样使用Open-AutoGLM框架：

python main.py\--device-id192.168.1.100:5555\--base-url http://localhost:8000/v1\--model autoglm-phone-9b-multilingual\"打开设备应用"

参数--device-id用于指定特定的设备，这在需要同时连接多个设备时特别有用。

4.3 多设备并发控制

Open-AutoGLM支持同时连接和控制多个Android设备，这对于批量自动化测试或多设备场景特别有价值。查看当前连接的所有设备的命令为：

adb devices -l

该命令会输出更详细的设备信息，包括设备序列号、连接模式和硬件型号。

通过Python API实现多设备的并发控制，可以充分利用计算机的多核处理能力。以下是一个实际的代码示例：

fromconcurrent.futuresimportThreadPoolExecutorfromphone_agentimportPhoneAgentfromphone_agent.modelimportModelConfigfromphone_agent.adbimportlist_devices# 获取所有已连接设备的列表devices=list_devices()# 创建模型配置model_config=ModelConfig(base_url="http://localhost:8000/v1",model_name="autoglm-phone-9b-multilingual",)defexecute_task_on_device(device_id,task_description):"""在指定设备上执行任务的函数"""try:agent=PhoneAgent(model_config=model_config,device_id=device_id)result=agent.run(task_description)return{'device_id':device_id,'status':'success','result':result}exceptExceptionase:return{'device_id':device_id,'status':'failed','error':str(e)}# 定义要在各设备上执行的任务列表tasks={devices[0].device_id:"打开设置应用",devices[1].device_id:"打开Chrome浏览器",devices[2].device_id:"打开Gmail应用",}# 使用线程池实现并发执行withThreadPoolExecutor(max_workers=min(3,len(devices)))asexecutor:# 提交所有任务futures={device_id:executor.submit(execute_task_on_device,device_id,task)fordevice_id,taskintasks.items()}# 收集执行结果results={}fordevice_id,futureinfutures.items():try:results[device_id]=future.result(timeout=300)# 5分钟超时exceptExceptionase:results[device_id]={'device_id':device_id,'status':'timeout','error':str(e)}# 输出执行结果fordevice_id,resultinresults.items():ifresult['status']=='success':print(f"设备{device_id}: 任务成功完成")else:print(f"设备{device_id}: 任务失败 -{result.get('error','未知原因')}")

在这个示例中，ThreadPoolExecutor的max_workers参数限制了同时执行的线程数，这很重要，因为模型服务的并发处理能力有限。通常max_workers设置为3-5是合理的平衡。

4.4 详细模式与调试

对于复杂的任务或需要理解框架决策过程的情况，用户可以启用详细日志输出。在命令行中添加--verbose参数：

python main.py\--verbose\--base-url http://localhost:8000/v1\--model autoglm-phone-9b-multilingual\"任务描述"

详细模式会输出每一步的决策过程和执行动作，例如：

================================================== 思考过程: -------------------------------------------------- 当前屏幕在应用首页，需要打开搜索功能 -------------------------------------------------- 执行的动作: { "_metadata": "do", "action": "Tap", "element": [500, 100] } ==================================================

这对于理解框架的行为、调试失败案例和优化提示词都非常有帮助。

5. 故障诊断

5.1 ADB连接诊断

ADB连接问题是部署中最常见的问题。若执行adb devices返回空列表或未识别设备，需要系统地进行诊断。

首先验证ADB服务是否正常运行。重启ADB服务可能解决瞬时问题：

adb kill-server adb start-server adb devices

如果重启后仍无设备显示，需要在Android设备上检查开发者选项中USB调试是否启用。某些设备需要同时启用"USB调试"和"USB调试（安全设置）"两个选项才能正常工作。检查完毕后重新连接USB线。

若设备显示为"unauthorized"状态，这意味着设备上的RSA密钥验证失败。解决方案为断开USB线，在设备的开发者选项中撤销所有已授予的USB调试权限，重新插入USB线。此时设备屏幕会再次弹出授权对话框，点击"Always Allow"将计算机的公钥写入设备信任列表。

若USB线本身存在问题（仅支持充电不支持数据传输），需要更换USB线。此外，某些USB集线器或扩展坞可能导致连接不稳定，建议直接连接到计算机的USB端口。

5.2 模型服务诊断

若应用无法连接到模型服务，首先验证服务是否真正启动。对于本地部署，查看vLLM启动时的输出信息，确认没有出现CUDA显存不足、模型下载失败等错误。

使用curl命令测试API连接：

curl-X GET http://localhost:8000/v1/models

对于第三方服务，则测试对应的API端点，例如：

curl-X GET https://api.z.ai/api/paas/v4/models\-H"Authorization: Bearer your-api-key"

若返回"Connection refused"，说明服务未启动或端口配置错误。若返回超时，通常表示网络连接问题。若返回认证错误，需要检查API密钥是否正确复制。

5.3 文本输入故障

文本输入失败或显示乱码通常是由ADB Keyboard问题引起的。首先检查ADB Keyboard是否安装成功：

adb shell pm list packages|grepadbkeyboard

若没有输出或输出不包含com.android.adbkeyboard，说明安装失败，需要重新安装APK文件。若输出正确但仍无法输入文本，则检查输入法是否启用和设置为默认：

adb shell settings get secure default_input_method

输出应为com.android.adbkeyboard/.AdbIME。若不符，重新设置：

adb shell imesetcom.android.adbkeyboard/.AdbIME

在Windows系统上，中文输入可能因系统编码问题而出现乱码。解决方案为设置Python编码环境变量：

$env:PYTHONIOENCODING ="utf-8"python main.py...

5.4 性能优化建议

若模型推理速度过慢，可以尝试以下优化策略。首先，减少模型的输出token数量：

model_config=ModelConfig(base_url="http://localhost:8000/v1",model_name="autoglm-phone-9b-multilingual",max_tokens=2000,# 从默认3000降低到2000temperature=0.05,# 降低采样温度以加快生成)

其次，对于本地部署，增加并行GPU数量。如果配置了多块GPU，vLLM可以自动利用它们进行并行推理。

最后，对于WiFi连接的远程设备，确保网络延迟在合理范围内（通常<100ms）。若网络延迟过高，可能需要部署到更靠近的服务器位置。

6. 参考资源

• GitHub项目仓库
• Android Debug Bridge官方文档
• z.ai模型服务平台
• Novita AI推理平台
• ModelScope社区
• vLLM项目
• 智谱AI官方文档