Open-AutoGLM教程：list_devices API返回值解析说明-深圳市維司達科技有限公司

Open-AutoGLM教程：list_devices API返回值解析说明

Open-AutoGLM – 智谱开源的手机端AI Agent框架

AutoGLM-Phone 是一个基于视觉语言模型的 AI 手机智能助理框架。它能以多模态方式理解屏幕内容，并通过 ADB 自动操控设备。用户只需用自然语言下指令，如“打开小红书搜美食”，模型即可解析意图、理解界面并自动规划、执行操作流程，无需手动点击。

1. 背景与使用场景

你有没有想过，让AI帮你操作手机？不是简单的语音助手，而是真正“看得懂”屏幕、“想得清楚”下一步、“点得准”每一个按钮的智能体。这就是Open-AutoGLM的目标——由智谱AI开源的手机端AI Agent框架，结合视觉语言模型与自动化控制能力，实现真正的“手机代驾”。

而在这个系统中，list_devices是一个关键的API接口，用于获取当前通过ADB连接的所有安卓设备信息。无论是本地调试还是远程控制，正确理解这个API的返回值，是确保后续操作顺利进行的第一步。

本文将带你深入解析list_devices的返回结构、字段含义以及在实际开发中的典型用法，帮助你快速上手 Open-AutoGLM 的设备管理模块。

2. 环境准备与项目部署

2.1 硬件与软件要求

在开始之前，请确认你的开发环境满足以下条件：

操作系统：Windows 或 macOS（Linux也可支持）
Python版本：建议使用 Python 3.10 或更高版本
安卓设备：Android 7.0 及以上系统的真机或模拟器
ADB工具：Android Debug Bridge，用于与设备通信

ADB 安装与配置

如果你还没有安装 ADB，可以从 Android SDK Platform Tools 下载对应平台的压缩包。

Windows 配置步骤：

解压下载的platform-tools文件夹。
按Win + R输入sysdm.cpl，进入“系统属性” → “高级” → “环境变量”。
在“系统变量”中找到Path，点击编辑，添加解压后的platform-tools目录路径。
打开命令行输入adb version，若显示版本号则表示配置成功。

macOS 快速配置方法：

# 假设 platform-tools 解压在 Downloads 目录下 export PATH=${PATH}:~/Downloads/platform-tools

你可以将这行命令写入.zshrc或.bash_profile实现永久生效。

2.2 手机端设置

为了让电脑能够控制手机，需要开启以下权限：

开启开发者模式
进入“设置” → “关于手机” → 连续点击“版本号”5~7次，直到提示已开启开发者选项。
启用USB调试
返回设置主界面 → “开发者选项” → 开启“USB调试”。
安装 ADB Keyboard（可选但推荐）
- 下载并安装 ADB Keyboard 的 APK。
- 在“语言与输入法”中，将默认输入法切换为 ADB Keyboard。
- 这样可以在无物理键盘的情况下实现文本输入自动化。

3. 部署 Open-AutoGLM 控制端

3.1 克隆项目并安装依赖

在本地电脑上执行以下命令，拉取 Open-AutoGLM 的源码并安装所需依赖：

git clone https://github.com/zai-org/Open-AutoGLM cd Open-AutoGLM # 安装依赖 pip install -r requirements.txt pip install -e .

注意：-e .表示以可编辑模式安装，便于后续修改代码和调试。

3.2 连接设备方式

Open-AutoGLM 支持两种设备连接方式：USB 和 WiFi（远程ADB），适用于不同场景。

USB 连接

最稳定的方式，适合本地调试。

adb devices

正常输出应类似：

List of devices attached ABCDEF1234567890 device

其中ABCDEF1234567890就是你的设备ID。

WiFi 远程连接

适合远程调试或无线操作场景，需先通过USB激活TCP/IP模式。

# 第一步：使用USB连接后，开启5555端口监听 adb tcpip 5555 # 第二步：断开USB，通过IP连接（确保在同一局域网） adb connect 192.168.1.100:5555

连接成功后，再次运行adb devices应能看到该设备出现在列表中。

4. list_devices API 使用详解

4.1 API 功能简介

list_devices()是 Open-AutoGLM 提供的一个核心函数，位于phone_agent.adb模块中，用于动态获取当前所有已连接的安卓设备及其连接状态。

它不依赖外部命令，而是封装了对 ADB 的调用逻辑，返回结构化的设备对象列表，便于程序化处理。

4.2 导入与调用方式

from phone_agent.adb import list_devices devices = list_devices() for device in devices: print(f"设备ID: {device.device_id}") print(f"连接类型: {device.connection_type.value}") print(f"状态: {device.status}") print("---")

4.3 返回值结构解析

list_devices()返回的是一个包含Device对象的列表，每个对象具有以下属性：

属性名	类型	说明
`device_id`	str	设备唯一标识符，如`ABCDEF1234567890`或`192.168.1.100:5555`
`connection_type`	ConnectionType 枚举	连接方式：`USB`或`TCP`
`status`	str	当前状态，通常为`"device"`（已连接）、`"offline"`或`"unauthorized"`

ConnectionType 枚举值说明

from enum import Enum class ConnectionType(Enum): USB = "usb" TCP = "tcp"

USB：表示通过数据线连接
TCP：表示通过网络（WiFi）连接

这意味着你可以根据connection_type判断设备是否为远程连接，从而决定是否需要特殊处理延迟或稳定性问题。

4.4 实际应用场景示例

场景一：自动选择可用设备

当多个设备同时连接时，可以编写逻辑自动筛选出状态正常的设备：

from phone_agent.adb import list_devices def get_first_healthy_device(): devices = list_devices() for dev in devices: if dev.status == "device": # 状态正常 return dev return None device = get_first_healthy_device() if device: print(f"选中设备: {device.device_id} ({device.connection_type.value})") else: print("没有可用设备")

场景二：区分本地与远程设备

有些操作（如频繁截图）对网络延迟敏感，可通过判断连接类型优化策略：

for dev in list_devices(): if dev.connection_type == ConnectionType.TCP: print(f"[警告] {dev.device_id} 为远程连接，可能影响响应速度") else: print(f"[提示] {dev.device_id} 为本地USB连接，推荐用于高频率任务")

场景三：结合 ADBConnection 类进行高级控制

除了list_devices()，还可以配合ADBConnection类实现更复杂的设备管理：

from phone_agent.adb import ADBConnection, list_devices conn = ADBConnection() # 查看当前连接设备 devices = list_devices() if not devices: print("未检测到任何设备") else: target = devices[0].device_id print(f"尝试连接: {target}") success, msg = conn.connect(target) if success: ip = conn.get_device_ip() print(f"设备内网IP: {ip}") # 启用TCP/IP模式以便后续无线连接 conn.enable_tcpip(5555) else: print(f"连接失败: {msg}") conn.disconnect(target)

这段代码展示了如何从设备发现 → 建立连接 → 获取信息 → 断开连接的完整流程。

5. 常见问题与排查建议

5.1 设备未出现在 list_devices 结果中

可能原因及解决方案：

未授权调试：首次连接时手机会弹出“允许USB调试？”对话框，请点击“允许”。若误点了“拒绝”，可在“开发者选项”中清除授权记录重新连接。
驱动问题（Windows）：部分国产手机需安装官方USB驱动才能被识别。建议使用小米、华为、OPPO等品牌的官方助手工具辅助安装。
ADB服务异常：尝试重启ADB服务：
```
adb kill-server adb start-server
```

5.2 list_devices 返回空列表但 adb devices 有输出

这种情况通常是由于 Python 环境中的adb调用路径与命令行不一致导致。

解决方法：

确保你在 Python 中使用的 ADB 与命令行是同一个。

显式指定 ADB 路径（如果项目支持）：

import os os.environ["ANDROID_HOME"] = "/Users/yourname/Library/Android/sdk" os.environ["PATH"] += ":$ANDROID_HOME/platform-tools"

5.3 远程连接频繁掉线

WiFi连接不稳定是常见问题，尤其在网络信号差或跨路由器环境下。

建议：

使用5GHz频段WiFi提升稳定性
减少并发操作频率，避免大量截图请求堆积
关键任务优先使用USB连接

5.4 敏感操作的安全提醒

Open-AutoGLM 内置了敏感操作拦截机制，例如涉及支付、删除应用等行为不会自动执行，而是等待人工确认。这是为了防止误操作带来的风险。

你也可以在配置文件中自定义哪些动作需要人工介入，提升安全性。

6. 总结

list_devices虽然只是一个简单的API，但它在整个 Open-AutoGLM 框架中扮演着“设备探针”的角色。只有准确识别和管理连接的设备，后续的屏幕感知、意图理解、动作执行才有可能顺利进行。

通过本文，你应该已经掌握了：

如何配置 ADB 环境并连接安卓设备
Open-AutoGLM 的基本部署流程
list_devices()的返回结构与字段含义
如何在实际项目中使用该API进行设备筛选与状态判断
常见连接问题的排查思路

下一步，你可以尝试结合自然语言指令，让AI代理真正“接管”你的手机，完成搜索、关注、点赞等一系列复杂操作。

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

Open-AutoGLM教程：list_devices API返回值解析说明