Open-AutoGLM开发者必看：远程调试与本地联调实操手册

Open-AutoGLM开发者必看：远程调试与本地联调实操手册

Open-AutoGLM 是智谱开源的手机端 AI Agent 框架，它把大模型能力真正带到了移动场景里。不是简单地把网页版模型塞进手机 App，而是让 AI 能“看见”屏幕、“理解”界面、“动手”操作——就像一个随时待命的数字同事，站在你手机背后帮你点、滑、输、搜、确认。

AutoGLM-Phone 是这个框架的核心实现，一个基于视觉语言模型的 AI 手机智能助理。它不依赖预设脚本，也不靠固定控件 ID，而是用多模态方式实时理解当前屏幕画面，再结合自然语言指令，自动规划出一连串精准的 ADB 操作。你说“打开小红书搜美食”，它就真能识别出首页的搜索框图标、点击、输入文字、点搜索按钮、滚动浏览结果——整个过程无需你碰一下屏幕。

Phone Agent 则是面向开发者的完整落地形态。它把屏幕感知、意图解析、动作规划、设备执行、安全确认这五个关键环节都封装成了可调试、可替换、可扩展的模块。更关键的是，它原生支持远程 ADB 控制：你可以用家里的电脑，连上公司服务器上的 vLLM 模型，再操控放在办公室抽屉里的测试机。WiFi 连接、IP 地址配置、ADB 端口转发……这些过去只在运维文档里出现的词，现在成了日常开发的一部分。它还内置了敏感操作拦截机制——遇到登录页、支付页、验证码弹窗时会自动暂停，等你人工接管，既保证自动化效率，又守住安全底线。

这套流程听起来复杂？其实只要三步：配好 ADB、连上真机、跑起 main.py。下面我们就从零开始，手把手带你完成一次完整的远程调试与本地联调实战。不讲原理，不堆参数，只说你马上能用上的操作。

1. 本地控制端环境搭建：让电脑“认得”你的手机

要让本地电脑成为 AI 的“手”，第一步就是让它能和安卓设备稳定通信。这不是装个软件就行的事，而是一套需要软硬协同的连接体系。我们不追求一步到位，而是分三块来理清：系统准备、ADB 配置、手机设置。每一步都有明确验证方式，错在哪一眼就能看出来。

1.1 系统与工具清单：检查你的开发台是否齐备

你不需要高端工作站，一台日常办公的笔记本就足够。重点是确保以下四项都已就位：

• 操作系统：Windows 10/11 或 macOS Monterey（12）及以上。Linux 用户同样适用，但本文以 Win/macOS 为主。
• Python 环境：建议使用 Python 3.10 或 3.11。太新（如 3.12）可能有兼容性问题，太旧（如 3.8）则缺少部分异步特性支持。运行python --version确认。
• 安卓设备：一部 Android 7.0（Nougat）或更高版本的真机。模拟器（如 Android Studio 自带的 Pixel 设备）也能跑通，但真实触控反馈、摄像头权限、后台保活等行为，真机才最接近用户实际体验。
• ADB 工具包：这是整套流程的“神经中枢”。它不是某个 App，而是一组命令行程序（adb、fastboot 等）。官方下载地址是 developer.android.com/platform-tools，选择对应系统的 ZIP 包。

为什么必须用官方 ADB？
第三方精简版常删减adb connect、adb tcpip等远程调试关键命令，或者签名不一致导致 Windows SmartScreen 拦截。官方包虽大一点，但省去所有兼容性雷区。

1.2 ADB 环境变量配置：让命令行“随时待命”

安装完 ADB，它只是静静躺在某个文件夹里。要让它在任意位置都能被调用，必须把它加入系统环境变量。这是新手最容易卡住的一步，我们拆解成傻瓜式操作。

Windows 用户（图形化操作，零命令行）

1. 解压下载好的platform-tools-latest-windows.zip，得到一个名为platform-tools的文件夹。记下它的完整路径，比如C:\Users\YourName\Downloads\platform-tools。
2. 按Win + R，输入sysdm.cpl，回车打开“系统属性”。
3. 切换到“高级”选项卡，点击右下角“环境变量”按钮。
4. 在“系统变量”区域，找到并双击Path。
5. 点击“新建”，把刚才记下的platform-tools文件夹路径粘贴进去。
6. 点击“确定”逐级保存。重启你的终端（CMD/PowerShell/Terminal），然后输入：

   adb version

   如果看到类似Android Debug Bridge version 1.0.41的输出，说明配置成功。

macOS 用户（终端命令，一气呵成）

1. 假设你把 ADB 解压到了~/Downloads/platform-tools（这是最常见路径）。
2. 打开 Terminal，执行以下命令：

   echo 'export PATH=$PATH:~/Downloads/platform-tools' >> ~/.zshrc source ~/.zshrc

   这两行的意思是：把 ADB 路径永久写入你的 shell 配置，并立即生效。
3. 验证：

   adb version

   同样看到版本号，即为成功。

小技巧：快速定位 ADB
如果你不确定 ADB 放在哪，可以在 Finder 中用 Spotlight（Cmd+Space）搜索adb，找到adb文件，右键“显示简介”，复制“位置”字段，就是你要添加的路径。

1.3 手机端深度设置：打开通往安卓系统的“后门”

电脑认得 ADB 了，手机还得“同意”被控制。这需要开启三个关键开关，缺一不可。

1. 开启开发者模式：
   进入手机“设置” → “关于手机” → 连续点击“版本号”7次。屏幕上会出现“您现在处于开发者模式”的提示。别担心，这只是解锁隐藏菜单，不会影响日常使用。

2. 开启 USB 调试：
   返回“设置”，现在你能看到多了一个“开发者选项”。点进去，找到“USB 调试”，把它打开。系统会弹出确认框，点“确定”。

3. 安装并启用 ADB Keyboard（关键！）：
   这是 Open-AutoGLM 实现“自动输入”的核心组件。它让 AI 能绕过系统键盘，直接向任意输入框发送文字。

   • 去 GitHub 搜索adb-keyboard，下载最新版 APK（如adb-keyboard-v1.0.0.apk）。
   • 用数据线传到手机，或通过浏览器直接下载安装（需在“设置→安全”中允许“未知来源应用”）。
   • 安装完成后，进入“设置” → “语言与输入法” → “当前键盘”，把默认输入法切换为ADB Keyboard。
   • 验证方法：在微信聊天框长按，如果弹出“输入法”选项且ADB Keyboard在列表中并被选中，就成功了。

为什么不用系统键盘？
系统键盘会触发隐私弹窗、需要手动授权、且无法保证在所有 App 内稳定工作。ADB Keyboard 是一个轻量级服务，它监听 ADB 的input text命令，收到后直接注入字符，全程无感、无弹窗、无权限请求。

2. 控制端代码部署：把 Open-AutoGLM “搬”到你电脑上

环境搭好了，现在要把控制大脑——Open-AutoGLM 的客户端代码，拉到本地运行起来。这一步的目标很明确：让main.py能顺利启动，并准备好接收你的第一条自然语言指令。

2.1 克隆仓库与安装依赖：三行命令搞定

打开你的终端（Windows 用户用 PowerShell，macOS 用 Terminal），依次执行：

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

pip install -e .这条命令是关键。它不是把代码打包安装，而是以“开发模式”链接到当前目录。这意味着你后续修改phone_agent/下的任何 Python 文件，都不需要重新安装，改完就能立刻生效，对调试极其友好。

2.2 验证连接：用最原始的方式确认“手”和“身体”已连通

在执行任何 AI 指令前，先做一次最底层的握手测试。这能排除 90% 的硬件连接问题。

• USB 连接测试：
  用数据线将手机连接电脑。确保手机屏幕亮起，并在通知栏看到“USB 用于传输文件”或类似提示（不需要选“仅充电”）。然后在终端运行：

  adb devices

  正常输出应为：

  List of devices attached 1234567890abcdef device

  如果显示unauthorized，请在手机上查看是否有“允许 USB 调试”的弹窗，勾选“始终允许”，再点确定。如果显示为空，检查数据线是否支持数据传输（有些线只能充电）、USB 接口是否松动、驱动是否安装（Windows 用户可尝试安装 Universal ADB Drivers）。

• WiFi 远程连接测试（进阶）：
  如果你想摆脱数据线束缚，可以走 WiFi。但首次必须用 USB 连接一次来“授权”：

  # 1. 用 USB 连上后，开启 TCP/IP 模式 adb tcpip 5555 # 2. 拔掉 USB 线，确保手机和电脑在同一 WiFi 下 # 3. 查看手机 IP（设置→关于手机→状态信息→IP 地址） # 4. 用电脑连接该 IP adb connect 192.168.1.100:5555

  成功后，adb devices会显示192.168.1.100:5555 device。此后，只要不重启手机或网络，这个连接就一直有效。

WiFi 连接稳定性提示：
办公室 WiFi 通常比家用更稳定。如果频繁断连，优先排查路由器 QoS 设置、手机 WiFi 省电模式（关闭“WLAN 休眠策略”）、或直接换回 USB。远程调试的价值在于“位置自由”，而非“连接永不掉线”。

3. 启动 AI 代理：下达你的第一条自然语言指令

万事俱备，现在轮到主角登场。AI 代理的启动方式有两种：命令行快速验证，和 Python API 深度集成。我们先用命令行跑通全流程，再展示如何把它嵌入你自己的项目。

3.1 命令行一键启动：三秒见证魔法

确保你已完成：

• 云服务器上的 vLLM 已启动，并映射了端口（如8800）；
• 本地电脑已通过adb devices确认设备在线；
• Open-AutoGLM目录下，虚拟环境已激活。

现在，在Open-AutoGLM根目录下，执行：

python main.py \ --device-id 1234567890abcdef \ --base-url http://192.168.1.200:8800/v1 \ --model "autoglm-phone-9b" \ "打开抖音搜索抖音号为：dycwo11nt61d 的博主并关注他！"

参数详解：

• --device-id：就是adb devices输出的第一列 ID。如果是 WiFi 连接，就写192.168.1.100:5555。
• --base-url：指向你云服务器上 vLLM 的 API 地址。注意格式必须是http://IP:PORT/v1，末尾/v1不可省略。
• --model：指定模型名称，必须与 vLLM 启动时--model参数完全一致。
• 最后的字符串：这就是你的“自然语言指令”，用中文、带标点、有具体目标，越像人话越好。

你会看到终端开始滚动日志：

• [INFO] Capturing screenshot...→ AI 截取当前屏幕
• [INFO] Sending to VLM for perception...→ 把截图和指令发给云端模型
• [INFO] Got plan: [CLICK, (x=520, y=120), TAP_SEARCH_BOX]→ 模型返回结构化动作
• [INFO] Executing: adb shell input tap 520 120→ 本地 ADB 执行点击

几秒钟后，你的手机屏幕就会自动亮起、打开抖音、点击搜索框、输入账号、点击搜索、找到博主、点击关注按钮——一气呵成。

3.2 Python API 深度集成：把 AI 变成你项目的“一个函数”

命令行适合快速验证，但工程化项目需要更灵活的控制。Open-AutoGLM 提供了干净的 Python API，让你能精确管理连接、获取设备状态、甚至自定义动作链。

from phone_agent.adb import ADBConnection, list_devices from phone_agent.agent import PhoneAgent # 1. 创建 ADB 连接管理器 conn = ADBConnection() # 2. 连接设备（支持 USB 和 WiFi） success, message = conn.connect("192.168.1.100:5555") # WiFi # success, message = conn.connect("1234567890abcdef") # USB print(f"连接状态: {message}") # 3. 列出所有已连接设备（可用于多机管理） devices = list_devices() for device in devices: print(f"{device.device_id} - {device.connection_type.value}") # 4. 初始化 AI 代理（指向你的云服务） agent = PhoneAgent( base_url="http://192.168.1.200:8800/v1", model_name="autoglm-phone-9b" ) # 5. 下达指令（同步阻塞，等待任务完成） result = agent.run("给我看看今天天气预报") print(f"任务完成，最终状态: {result.status}") # 6. 断开连接（可选） conn.disconnect("192.168.1.100:5555")

这段代码展示了真正的工程价值：你可以把它放进 Flask Web 服务，做成一个 HTTP 接口；可以集成进 CI/CD 流程，每次发版自动跑一遍 UI 回归测试；也可以作为内部工具，让产品经理用自然语言描述需求，AI 自动生成操作视频。

4. 常见问题排查：那些让你抓耳挠腮的“小意外”

再完美的手册也绕不开现实世界的毛刺。以下是我们在真实联调中高频遇到的 5 个问题，以及直击要害的解决思路。

4.1 “Connection refused”：云服务器的大门没打开

现象：main.py报错ConnectionRefusedError: [Errno 111] Connection refused。
原因：不是你的代码错了，而是--base-url指向的服务器根本没在监听那个端口。
三步定位：

1. 登录云服务器，运行netstat -tuln | grep :8800，确认端口是否被 vLLM 占用。
2. 检查 vLLM 启动命令是否包含--host 0.0.0.0（必须，否则只监听 localhost）。
3. 检查云服务器防火墙：sudo ufw status（Ubuntu）或sudo firewall-cmd --list-ports（CentOS），确保8800/tcp已放行。

4.2 ADB 设备“时隐时现”：WiFi 连接的脆弱性

现象：adb devices有时显示设备，有时变空；或者adb connect成功，但adb shell就报错。
原因：WiFi 网络抖动、手机休眠、ADB daemon 服务崩溃。
稳住连接的两个动作：

• 在手机上，进入“开发者选项”，关闭“USB 调试（安全设置）”（此选项会周期性断开 WiFi ADB）。
• 在电脑上，定期执行adb kill-server && adb start-server重置 ADB 服务。

4.3 模型“装聋作哑”：指令发出去，没返回，也没报错

现象：终端卡在[INFO] Sending to VLM for perception...，十几秒后超时。
原因：vLLM 显存不足，或max-model-len设置过小，导致长上下文被截断。
急救方案：

• 登录服务器，用nvidia-smi查看显存占用。如果 >95%，说明 OOM。
• 重启 vLLM，启动参数加上--max-model-len 4096（根据你的 GPU 调整，A10G 推荐 2048~4096）。

4.4 屏幕“一片漆黑”：截图失败，AI 瞎了

现象：日志显示Capturing screenshot...，但后续没有Sending to VLM...，或截图文件为空。
原因：手机未授予adb shell screencap权限，常见于 Android 12+ 的隐私限制。
解决方案：

• 在手机“设置→隐私→权限管理→ADB 调试”，确保“读取屏幕内容”已开启。
• 或换用adb exec-out screencap -p > screen.png命令（v33+ ADB 支持）。

4.5 输入框“拒绝合作”：文字输不进去

现象：AI 识别出搜索框，也执行了input tap，但后续input text没反应。
原因：ADB Keyboard 未被设为默认，或当前 App 拦截了非系统键盘。
终极验证法：

• 在终端手动执行：adb shell input text "hello"。
• 如果手机没反应，说明 ADB Keyboard 未生效；如果弹出系统键盘，说明它被禁用了。回到“语言与输入法”设置，强制切换。

5. 总结：从“能跑”到“敢用”，你已经跨过了最关键的门槛

这篇手册没有讲 AutoGLM 的 Transformer 结构，也没分析视觉编码器的注意力热图。它只聚焦一件事：让你的 AI 代理，在真实手机上，第一次，稳稳当当地，完成一个你指定的任务。

你现在已经掌握了：

• 如何让 Windows/macOS 电脑和安卓手机建立一条可靠的 ADB 数据通道；
• 如何用一行adb connect实现免线缆的远程调试；
• 如何把 Open-AutoGLM 的控制端代码，变成你项目里一个可调用的PhoneAgent.run()函数；
• 当连接失败、模型沉默、截图空白时，不再盲目重启，而是有章法地逐层排查。

这看似只是“连上、跑通、看效果”的三步，但它背后是移动 AI 工程化的完整闭环：设备控制（ADB）、视觉感知（VLM）、意图理解（LLM）、动作规划（Agent）、安全兜底（人工接管）。Open-AutoGLM 把这些模块都做成了开箱即用的积木，而你，已经拿到了第一块。

下一步，你可以尝试：

• 用--debug参数启动main.py，查看每一帧截图和模型返回的 JSON 计划；
• 修改phone_agent/planner/下的规划逻辑，让 AI 在遇到验证码时，自动截图发到你的企业微信；
• 把PhoneAgent封装成 FastAPI 接口，让测试同学用 Postman 发送指令，彻底解放双手。

技术的价值，从来不在炫技，而在解决一个真实、微小、却反复出现的麻烦。当你第一次看着手机自己打开 App、输入文字、点击关注，那一刻的“哇”，就是所有调试的意义。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。