AutoGLM 保姆级部署教程：智谱开源手机端 GUI Agent，自然语言驱动安卓/鸿蒙自动操作

一、项目介绍

AutoGLM（开源版仓库名 Open-AutoGLM）是智谱 AI（Zhipu AI / Z.ai）开源的一款手机端智能助理框架（Phone Agent）。官方 README 对其定位是：基于 AutoGLM 视觉语言模型构建，能以多模态方式理解手机屏幕内容，并通过 ADB（Android Debug Bridge）或 HDC（鸿蒙调试命令）自动控制设备完成任务。用户只需用自然语言描述需求（例如「打开美团搜索附近的火锅店」），系统即可自动解析意图、理解当前界面、规划下一步动作并执行整个流程。

项目架构分为两部分：Agent 代码（运行在用户电脑上，负责调用模型、解析动作、控制手机）与视觉模型服务（可使用第三方 API，也可本地用 vLLM / SGLang 自部署）。AutoGLM-Phone-9B 是针对中文手机应用优化的视觉语言模型，AutoGLM-Phone-9B-Multilingual 支持英文等多语言场景。项目在 GitHub（zai-org/Open-AutoGLM）持续活跃维护（核验日期 2026-11-01），并已适配 Midscene.js 等第三方 UI 自动化框架。

二、功能拆解

按官方 README「项目介绍」「可用操作」「支持的应用」「远程调试」章节，核心能力如下：

功能	说明（官方原文要点）
自然语言驱动	用户输入「打开小红书搜索美食」即自动完成意图解析、界面理解、动作规划与执行
多模态屏幕感知	视觉语言模型截图理解当前界面，输出点击坐标
10 种内置操作	`Launch`（启动应用）、`Tap`（点击）、`Type`（输入文本）、`Swipe`（滑动）、`Back`（返回）、`Home`（桌面）、`Long Press`（长按）、`Double Tap`（双击）、`Wait`（等待）、`Take_over`（请求人工接管）
敏感操作人工接管	登录、验证码、支付等敏感场景自动暂停，请求人工接管后继续
双平台支持	Android（7.0+，通过 ADB）与 HarmonyOS NEXT（通过 HDC）
远程 WiFi 调试	手机与电脑同一 WiFi 下，可通过 `adb connect` / `hdc tconn` 无线控制
50+ 中文应用 / 60+ 鸿蒙应用	微信、淘宝、京东、美团、抖音、小红书、bilibili、高德地图等主流应用一键启动
Python API	`from phone_agent import PhoneAgent` 可在自己的代码中嵌入 Agent
中英双语 Prompt	`--lang cn`（默认中文）/ `--lang en`（英文）

三、官方/GitHub 链接

GitHub 仓库：https://github.com/zai-org/Open-AutoGLM
模型权重（Hugging Face）：https://huggingface.co/zai-org/AutoGLM-Phone-9B
模型权重（ModelScope 魔搭）：https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B
智谱 BigModel API 文档：https://docs.bigmodel.cn/cn/api/introduction
ADB 官方下载（Android platform-tools）：https://developer.android.com/tools/releases/platform-tools
HarmonyOS SDK 下载：https://developer.huawei.com/consumer/cn/download/
ADB Keyboard（文本输入）：https://github.com/senzhk/ADBKeyBoard/blob/master/ADBKeyboard.apk
iOS 环境配置指南（仓库内）：docs/ios_setup/ios_setup.md
论文引用：arXiv:2411.00820（AutoGLM）、arXiv:2509.18119（MobileRL）

四、环境要求

按官方 README「Android 环境准备」与「部署准备工作」章节：

Python： 3.10 及以上版本（官方原文「建议使用 Python 3.10 及以上版本」）。
Android 设备： Android 7.0 以上，启用「开发者模式」与「USB 调试」；部分机型还需启用「USB 调试（安全设置）」。
鸿蒙设备： HarmonyOS NEXT 以上版本，启用「开发者选项」中的「USB 调试」与「无线调试」。
ADB 工具： 从 Android 官方 platform-tools 下载并加入 PATH；或 macOS 上 brew install android-platform-tools。
HDC 工具： 从 HarmonyOS SDK 下载，路径 harmonyos-sdk/toolchains 加入 PATH。
ADB Keyboard（仅 Android）： 用于中文文本输入，安装后需在系统输入法设置中启用。
模型服务（二选一）：
选项 A：使用第三方已部署模型 API（智谱 BigModel 或 ModelScope），无需 GPU；
选项 B：本地自部署模型，需 NVIDIA GPU（官方自动化章节注明「建议 24GB+ 显存」），使用 vLLM 或 SGLang，模型文件约 20GB。
操作系统： 官方 README 给出 macOS、Linux、Windows 三种环境变量配置方式；Agent 代码跨平台运行。

五、部署步骤

步骤 1：克隆仓库（官方自动化章节原命令）

git clone https://github.com/zai-org/Open-AutoGLM.git
cd Open-AutoGLM

逐段解释：git clone 从 GitHub 拉取仓库；cd Open-AutoGLM 进入项目根目录。

预期输出参考： 输出 Cloning into 'Open-AutoGLM'... 与远程对象计数进度，最终回到命令行提示符。

步骤 2：创建 Python 虚拟环境并激活（官方自动化章节推荐方式）

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

逐段解释：python -m venv venv 在项目目录下创建名为 venv 的虚拟环境；source venv/bin/activate 激活该环境（Windows 用 venv\Scripts\activate）。

预期输出参考： 命令成功、无输出；命令行提示符前出现 (venv) 表示已激活。

步骤 3：安装项目依赖（官方「部署准备工作」原命令）

pip install -r requirements.txt 
pip install -e .

逐段解释：pip install -r requirements.txt 按 requirements.txt 安装运行依赖；pip install -e . 以可编辑模式（editable）安装当前项目本身，使 phone_agent 包可被 Python 直接导入。

预期输出参考： pip 输出下载与安装进度，结束时输出 Successfully installed ... 之类的汇总行。

步骤 4：配置 ADB 并连接 Android 设备（官方原命令）

# 检查已连接的设备
adb devices

逐段解释：adb devices 列出当前 ADB 可见的设备。

预期输出参考（官方原文示例）：

text List of devices attached emulator-5554 device

若输出 List of devices attached 后为空，或显示 unauthorized，说明 USB 调试未授权或数据线仅能充电，需按后文「故障排查」处理。

鸿蒙用户等价命令（官方原命令）：

hdc list targets

逐段解释：hdc list targets 列出已连接的鸿蒙设备。

预期输出参考（官方原文示例）：

text 7001005458323933328a01bce01c2500

步骤 5：启动模型服务（二选一）

方式 A：使用第三方 API（无需本地 GPU）。直接跳到步骤 6。

方式 B：本地用 vLLM 启动 OpenAI 兼容模型服务（官方原命令）：

python3 -m vllm.entrypoints.openai.api_server \
 --served-model-name autoglm-phone-9b \
 --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}" \
 --model zai-org/AutoGLM-Phone-9B \
 --port 8000

逐段解释：python3 -m vllm.entrypoints.openai.api_server 启动 vLLM 的 OpenAI 兼容 API 服务；--served-model-name autoglm-phone-9b 对外暴露的模型名；--allowed-local-media-path / 允许读取本地图片路径；--mm-encoder-tp-mode data、--mm_processor_cache_type shm、--mm_processor_kwargs 是官方要求的多模态编码器参数；--max-model-len 25480 上下文长度；--limit-mm-per-prompt 每 prompt 最多 10 张图；--model zai-org/AutoGLM-Phone-9B 自动从 Hugging Face 拉取模型权重；--port 8000 监听端口。

SGLang 等价启动命令（官方原文）：

shell python3 -m sglang.launch_server --model-path zai-org/AutoGLM-Phone-9B \ --served-model-name autoglm-phone-9b \ --context-length 25480 \ --mm-enable-dp-encoder \ --mm-process-config '{"image":{"max_pixels":5000000}}' \ --port 8000

预期输出参考： 模型服务启动后，可通过 http://localhost:8000/v1 访问（官方原文：「运行成功后，将可以通过 http://localhost:8000/v1 访问模型服务」）。

步骤 6：验证模型部署（官方原命令）

python scripts/check_deployment_cn.py --base-url http://你的IP:你的端口/v1 --model 模型名称

逐段解释：scripts/check_deployment_cn.py 是官方提供的部署自检脚本；--base-url 填模型服务地址；--model 填模型名（本地部署为 autoglm-phone-9b；智谱 BigModel 为 autoglm-phone；ModelScope 为 ZhipuAI/AutoGLM-Phone-9B）。

预期输出参考（官方原文示例）：

```text
用户想要比较这个洗发水在京东和淘宝上的价格，然后选择最便宜的平台下单。当前在小红书app上，显示的是一个关于LUMMI MOOD洗发水的帖子。

我需要：
1. 先启动京东app，搜索这个洗发水
2. 查看京东的价格
...

do(action="Launch", app="京东")
```

官方原文警告：「如果思维链长度很短，或者出现了乱码，很可能是模型部署失败，请仔细检查文档要求的配置和依赖。」

步骤 7：运行 Agent（官方「使用 AutoGLM」原命令）

# Android 设备 - 交互模式
python main.py --base-url http://localhost:8000/v1 --model "autoglm-phone-9b"

# Android 设备 - 指定任务
python main.py --base-url http://localhost:8000/v1 "打开美团搜索附近的火锅店"

# 鸿蒙设备 - 交互模式
python main.py --device-type hdc --base-url http://localhost:8000/v1 --model "autoglm-phone-9b"

# 使用第三方 API Key 认证（智谱 BigModel 示例）
python main.py --base-url https://open.bigmodel.cn/api/paas/v4 --model "autoglm-phone" --apikey "your-bigmodel-api-key" "打开美团搜索附近的火锅店"

# 列出支持的应用（Android）
python main.py --list-apps

逐段解释：python main.py 是 Agent 主入口；--base-url 模型服务地址；--model 模型名；--device-type hdc 指定鸿蒙设备（默认 adb 即 Android）；位置参数（不带 flag 的字符串）即用户任务描述；--apikey 在使用第三方 API 时传密钥；--list-apps 仅列出支持的应用清单后退出。

六、配置参数详解

1. 环境变量（官方 README「环境变量」节原文表格）：

变量	描述	默认值
`PHONE_AGENT_BASE_URL`	模型 API 地址	`http://localhost:8000/v1`
`PHONE_AGENT_MODEL`	模型名称	`autoglm-phone-9b`
`PHONE_AGENT_API_KEY`	模型认证 API Key	`EMPTY`
`PHONE_AGENT_MAX_STEPS`	每个任务最大步数	`100`
`PHONE_AGENT_DEVICE_ID`	ADB/HDC 设备 ID	（自动检测）
`PHONE_AGENT_DEVICE_TYPE`	设备类型（`adb` 或 `hdc`）	`adb`
`PHONE_AGENT_LANG`	语言（`cn` 或 `en`）	`cn`

2. 模型配置（官方 Python API 示例）：

from phone_agent.model import ModelConfig

config = ModelConfig(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",  # API 密钥(如需要)
    model_name="autoglm-phone-9b",  # 模型名称
    max_tokens=3000,  # 最大输出 token 数
    temperature=0.1,  # 采样温度
    frequency_penalty=0.2,  # 频率惩罚
)

3. Agent 配置（官方 Python API 示例）：

from phone_agent.agent import AgentConfig

config = AgentConfig(
    max_steps=100,  # 每个任务最大步数
    device_id=None,  # ADB 设备 ID(None 为自动检测)
    lang="cn",  # 语言选择：cn(中文)或 en(英文)
    verbose=True,  # 打印调试信息(包括思考过程和执行动作)
)

4. 自定义系统 Prompt： 中文 prompt 配置文件为 phone_agent/config/prompts_zh.py，英文为 phone_agent/config/prompts_en.py（官方原文），可直接修改以增强特定领域能力。

5. 自定义回调（敏感操作确认 / 人工接管）：

def my_confirmation(message: str) -> bool:
    """敏感操作确认回调"""
    return input(f"确认执行 {message}？(y/n): ").lower() == "y"


def my_takeover(message: str) -> None:
    """人工接管回调"""
    print(f"请手动完成: {message}")
    input("完成后按回车继续...")


agent = PhoneAgent(
    confirmation_callback=my_confirmation,
    takeover_callback=my_takeover,
)

七、启动与运维

前台运行： python main.py ... 即前台启动，Ctrl+C 终止。
后台常驻 / 开机自启： 官方 README 未提供后台常驻、开机自启或 systemd 配置。本项目是交互式 CLI Agent，每次运行对应一次任务或一个会话，本身设计为前台运行；如需后台执行单次任务，可由用户自行用 nohup / tmux 等通用手段包裹（属通用 Linux 用法，非官方文档内容）。
停止任务： 终端按 Ctrl+C；Agent 执行过程中遇到敏感操作会自动暂停并请求人工接管。
查看日志： 终端实时输出 verbose 思考过程（verbose=True 时每步打印「💭 思考过程」「🎯 执行动作」）。
远程 WiFi 调试（官方原命令）：

# Android 设备 - 通过 WiFi 连接, 改成手机显示的 IP 地址和端口
adb connect 192.168.1.100:5555

# 验证连接
adb devices
# 应显示：192.168.1.100:5555    device

# 鸿蒙设备 - 通过 WiFi 连接
hdc tconn 192.168.1.100:5555

# 验证连接
hdc list targets
# 应显示：192.168.1.100:5555

指定设备执行任务（官方原命令）：

python main.py --device-id 192.168.1.100:5555 --base-url http://localhost:8000/v1 --model "autoglm-phone-9b" "打开抖音刷视频"

升级依赖： 二次开发模式安装：pip install -e ".[dev]"；运行测试：pytest tests/（官方「二次开发」节）。

八、实操验证

连接 Android 设备，执行 adb devices 应看到一台 device 状态的设备。
（若用本地模型）vLLM 服务启动后，执行 python scripts/check_deployment_cn.py --base-url http://localhost:8000/v1 --model autoglm-phone-9b，应输出带 <think>...</think> 与 <answer>do(action="Launch", app="京东")</answer> 的推理结果（官方原文示例）。
执行最小验收任务（官方自动化章节推荐）：

python main.py --base-url {MODEL_URL} --model "autoglm-phone-9b" "打开微信，对文件传输助手发送消息：部署成功"

预期结果（官方原文）： 手机自动打开微信 → 自动搜索「文件传输助手」→ 自动发送消息「部署成功」。

部署完成的标志（官方原文）：手机能自动执行用户的自然语言指令。

登录与安全（重要）

AutoGLM 本身没有 Web 后台、没有账号密码登录。 它是运行在用户电脑上的 Python CLI，直接通过 ADB/HDC 控制手机，不存在「默认账号/默认密码」这一概念。
唯一需要妥善保管的密钥是模型服务的 API Key： 使用智谱 BigModel / ModelScope 等第三方 API 时，通过 --apikey 或环境变量 PHONE_AGENT_API_KEY 传入；官方 README 示例值为 your-bigmodel-api-key / your-modelscope-api-key，正式使用时必须替换为你在平台申请的真实 Key，切勿硬编码进公开仓库。
本地自部署模型时 API Key 为 EMPTY（官方 ModelConfig 示例），因 vLLM/SGLang 默认不鉴权。
安全提醒：
1. 手机端 USB 调试授权框只在第一次连接时弹出，不要在公共电脑上随意点「允许」；
2. 远程 WiFi 调试（adb connect IP:5555）一旦开启，同一网络下任何人知道 IP 端口即可控制手机，使用完毕后执行 adb disconnect / hdc tdisconn 断开；
3. Agent 执行支付、银行、短信等敏感页面时会因截图黑屏而自动请求人工接管，不要绕过该机制；
4. 官方 README 顶部警告：「本项目仅供研究和学习使用。严禁用于非法获取信息、干扰系统或任何违法活动。」

九、故障排查

案例 1：adb devices 无输出或显示 unauthorized（官方「常见问题」「自动化部署」节）

报错原文（官方原文）：

List of devices attached
（空）

或

xxxxxxxx    unauthorized

报错原因：USB 调试未开启，或手机上未点击「允许 USB 调试」授权框，或数据线仅能充电不能传数据。
分步解决（官方原文）：① 检查开发者选项中「USB 调试」是否开启；② 检查数据线是否支持数据传输；③ 手机上弹出的授权框是否已点击「允许」；④ 尝试更换 USB 接口或数据线；⑤ 重启 ADB 服务（官方原命令）：

adb kill-server
adb start-server
adb devices

案例 2：能打开应用，但无法点击（官方「常见问题」）

报错原文：Agent 输出 Launch 动作成功，但后续 Tap 不生效或抛异常。
报错原因（官方原文）：「部分机型需要同时开启两个调试选项才能正常使用：USB 调试 和 USB 调试（安全设置）」。
分步解决：① 在 设置 → 开发者选项 中检查这两个选项是否都已启用；② 重启手机后再次 adb devices 确认连接。

案例 3：中文文本输入失败或变成乱码（官方「常见问题」）

报错原文：Agent 执行 Type 动作后，目标输入框无文字或出现乱码。
报错原因（官方原文）：ADB Keyboard 未安装或未启用。
分步解决：① 从 https://github.com/senzhk/ADBKeyBoard/blob/master/ADBKeyboard.apk 下载安装包并在安卓设备安装；② 在 设置 > 系统 > 语言和输入法 > 虚拟键盘 中启用 ADB Keyboard（或执行官方命令 adb shell ime enable com.android.adbkeyboard/.AdbIME）；③ Agent 会在需要输入时自动切换到 ADB Keyboard。

案例 4：Windows 下中文输出报 UnicodeEncodeError: gbk code（官方「常见问题」）

报错原文（官方原文）：

UnicodeEncodeError: 'gbk' codec can't encode character ...

报错原因：Windows 终端默认 GBK 编码，无法输出 Agent 的中文日志。
分步解决（官方原文）：在运行命令前加环境变量：

set PYTHONIOENCODING=utf-8
python main.py --base-url ... "打开微信"

案例 5：交互模式报 EOF when reading a line（官方「常见问题」）

报错原文（官方原文）：

EOF when reading a line

报错原因：交互模式需要 TTY，但当前环境（如某些 IDE 输出窗口、后台任务）不是 TTY。
分步解决（官方原文）：「使用非交互模式直接指定任务，或者切换到 TTY 模式的终端应用」——即把位置参数（任务字符串）直接传给 python main.py，而不是进入交互循环。

案例 6：截图返回黑屏（官方「常见问题」）

报错现象：Agent 截图后界面全黑。
报错原因（官方原文）：「这通常意味着应用正在显示敏感页面（支付、密码、银行类应用）。Agent 会自动检测并请求人工接管。」
解决：等待 Agent 自动暂停并弹出人工接管请求，手动完成敏感步骤后按回车继续；非 Bug，属正常保护机制。

十、升级、回滚与卸载

升级（官方「Upgrading」风格）： 拉取最新代码并重新安装依赖：

git pull
pip install -r requirements.txt
pip install -e .

逐段解释：git pull 同步上游最新代码；重装依赖以同步 requirements.txt 变化。

回滚： 官方未提供一键回滚命令；可用 Git 通用机制切换到旧 tag / 旧 commit 后重新 pip install -e .：

git checkout <旧版本 tag 或 commit>
pip install -e .

卸载：
- 项目本身：删除克隆的 Open-AutoGLM/ 目录即可；
- Python 依赖：虚拟环境直接 deactivate && rm -rf venv；
- 模型权重（本地部署时）：默认缓存在 Hugging Face 缓存目录（~/.cache/huggingface/），可手动删除以释放约 20GB 磁盘空间；
- ADB / HDC 工具：从 PATH 环境变量中移除对应路径并删除下载目录；
- ADB Keyboard：在 Android 手机 设置 > 输入法 中卸载该 APK。

十一、商用许可合规说明

许可证：Apache License 2.0（仓库根目录 LICENSE 文件原文首行：Apache License Version 2.0, January 2004）。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更。
模型权重的许可需单独确认： AutoGLM-Phone-9B 模型权重托管在 Hugging Face（zai-org/AutoGLM-Phone-9B）与 ModelScope（ZhipuAI/AutoGLM-Phone-9B），商用前请到对应模型卡页面阅读其独立许可条款。
使用限制（官方 README 原文）： 「本项目仅供研究和学习使用。严禁用于非法获取信息、干扰系统或任何违法活动。请仔细审阅使用条款（resources/privacy_policy.txt）。」
官方同时提供商业产品「智谱 AI 输入法 / Autotyper Agent」与 BigModel 商用 API，企业级生产部署建议走官方 API 渠道。