Skip to main content

排查常见问题

本文按「问题 → 排查 → 解决」的方式，汇总 AutoGLM-GUI 使用中最常见的故障，覆盖设备连接、模型 API、实时画面、端口冲突和任务执行五类。先按现象找到对应条目，再依次执行排查步骤。

如果按本文仍无法定位，请直接跳到末尾的排障工具一节，用日志和追踪文件复现问题。

ADB 与设备连接​

设备连不上 / 设备列表里没有​

排查：

  1. 在终端执行 adb devices，确认设备本身能被系统识别。
  2. 如果列表为空或显示 unauthorized，在手机上重新确认「允许 USB 调试」的授权弹窗。
  3. WiFi 连接时确认手机和电脑在同一网段，能互相 ping 通。

解决：

  • USB 连接：换一根数据线（部分线只能充电不能传数据），开启「开发者选项 → USB 调试」。
  • 设备授权弹窗没出现时，执行 adb kill-server && adb start-server 后重新插拔。
  • WiFi 连接：在界面左下角「添加无线设备 → 远程设备」里手动输入 IP:端口 重连，参见 连接设备。

提示找不到 adb / adb 命令不存在​

桌面版已内置 ADB，一般不会遇到此问题。从 Python 包或源码运行时，如果系统 PATH 里没有 adb，启动日志会出现 WARNING 并降级。

排查：在终端执行 adb version，看是否能正常输出版本号。

解决：

  • 安装 Android Platform Tools，并把 adb 所在目录加入 PATH。

  • 如果 adb 装在非标准路径，用环境变量显式指定：

    AUTOGLM_ADB_PATH=/path/to/adb autoglm-gui --base-url http://localhost:8080/v1

    该变量会被传递给设备管理器，--reload 模式下的子进程也会继承。完整环境变量见 环境变量参考。

WiFi 调试一段时间后断开​

WiFi 调试端口在手机重启、切换网络或休眠后通常会变化，旧的 IP:端口 会失效。

排查：在手机「无线调试」页面查看当前端口，与界面里记录的是否一致。

解决：重新读取手机上的最新端口，删除失效的远程设备后重新添加。需要长期稳定连接时优先用 USB，或保持手机充电并关闭省电策略。

二维码配对失败​

排查：

  1. 确认手机系统为 Android 11 及以上（低版本不支持二维码配对）。
  2. 确认手机和电脑在同一 WiFi，且未开启 AP 隔离。
  3. 注意界面提示「超时：未检测到扫码」，说明配对请求一直没到达。

解决：

  • 二维码配对依赖 mDNS 多播来发现设备。在 Docker 里运行时，bridge 网络会阻断 mDNS，必须使用 --network host 模式，详见 Docker 部署参考。
  • 多次失败时点击「重新生成」刷新二维码再扫。
  • 仍不行就退回 USB 一次性配对，配对成功后即可拔线无线使用。

模拟器没有被发现​

排查：先用 adb devices 确认模拟器是否出现（通常显示为 emulator-5554）。

解决：

  • 确保模拟器先于 AutoGLM-GUI 启动，或启动后在界面点击「发现设备」刷新。
  • 部分模拟器（如夜神、MuMu）需要先执行 adb connect 127.0.0.1:<端口> 才能被识别，端口见各模拟器的 ADB 设置。

模型 API​

模型相关配置遵循四层优先级：CLI 参数 > 环境变量 > 配置文件（~/.config/autoglm/config.json）> 默认值。启动横幅会打印当前生效的 Source、Base URL 和 Model，排查时先看这里确认实际用的是哪一份配置。配置方法见 配置模型。

「测试连接」失败 / 连接失败​

排查：在设置页点击「测试连接」，根据返回的报错判断是网络、鉴权还是模型名问题。

解决：按下面几条逐项核对 Base URL、API Key 和模型名。

401 / 鉴权失败​

排查：确认 API Key 已填写且未过期；自建服务通常不校验 Key，可留空（内部默认 EMPTY）。

解决：

  • 用智谱 BigModel、ModelScope 等托管服务时，把正确的 sk-xxxxx 填进 API Key。
  • 注意不要把 Key 前后的空格一起粘贴进去。

请求超时​

排查：确认 Base URL 指向的服务确实在运行，且本机能访问（自建服务可用 curl 直接测试该地址）。

解决：

  • 本地推理服务（vLLM/SGLang）首次加载模型较慢，等服务完全就绪后再测试。
  • 服务器部署时确认防火墙/安全组放行了对应端口。
  • 网络不稳定导致的偶发超时，重试即可。

Base URL 写错（必须带 /v1）​

这是最常见的配置错误。Base URL 必须是 OpenAI 兼容端点的完整路径，通常以 /v1 结尾。

排查：检查地址是否漏写了 /v1，以及是否以 http:// 或 https:// 开头（配置校验会拒绝不合法的前缀，界面提示「URL 必须以 http:// 或 https:// 开头」）。

解决：

  • 自建服务：http://localhost:8080/v1
  • ModelScope：https://api-inference.modelscope.cn/v1
  • 智谱 BigModel 例外，使用 https://open.bigmodel.cn/api/paas/v4

末尾多余的斜杠会被自动去除，无需手动处理。

模型名不对​

排查：模型名要和服务端实际部署/订阅的名称完全一致，大小写敏感。默认值为 autoglm-phone-9b。

解决：

  • 自建 zai-org/AutoGLM-Phone-9B：填启动时指定的名字，默认 autoglm-phone-9b。
  • 智谱 BigModel：autoglm-phone。
  • ModelScope：ZhipuAI/AutoGLM-Phone-9B。

使用分层代理模式时还需单独配置决策模型的 Base URL / API Key / Model Name，三者缺一会导致规划层无法启动。

实时画面​

视频流黑屏 / 不显示​

实时画面基于 scrcpy 视频流，通过浏览器的 WebCodecs API 解码，对运行环境有要求。

排查：看画面上的提示文字判断原因。

解决：

  • 提示「视频流需要 HTTPS 或 localhost 环境」：浏览器的 WebCodecs 只在 localhost 或 HTTPS 下可用。通过 IP:端口 远程访问时不是安全上下文，需要为服务配置 HTTPS（启动时加 --ssl-keyfile 和 --ssl-certfile），或直接用桌面版（已内置完整能力）。
  • 提示「当前浏览器不支持 WebCodecs API」：换用最新版 Chrome 或 Edge。
  • 视频实在无法工作时，可在设备面板右上角把显示模式从「视频」切换到「图像」，回退到截图轮询模式（约 0.5 秒刷新一次），功能不受影响只是不够流畅。

相关操作见 实时控制。

端口冲突​

8000 端口被占用​

默认不指定 --port 时，服务会从 8000 开始自动向后探测可用端口，并在启动横幅里打印 Auto-detected available port: <端口>。所以多数情况下端口冲突会被自动绕过。

排查：看启动横幅打印的实际端口号，浏览器按这个端口访问。

解决：

  • 想固定端口，用 --port 显式指定，例如 autoglm-gui --base-url ... --port 9000。
  • Docker bridge 模式下用 -p 9000:8000 做端口映射；host 模式则在 command 里加 --port。详见 Docker 部署参考 和 CLI 参考。

任务执行​

任务卡住不动 / 一直在转​

排查：观察实时画面，确认是模型还在思考、还是停在某个界面反复操作。任务有最大步数限制（默认 100 步），超过会自动停止。

解决：

  • 点击「立即打断」中断当前执行，响应在 1 秒内。打断后可在同一对话里换一种说法重新下达任务，详见 中断任务。
  • 怀疑上下文已经乱了，点「重置对话」清空历史重新开始。
  • 任务确实需要更多步数时，可在高级设置里调高单次任务最大步数（留空表示不限制，任务会持续运行到手动停止）。

报错 ELEMENT_NOT_FOUND（找不到元素）​

这是有意设计的 Fail-Fast 行为，常见于 MCP 的 chat 工具：找不到目标元素时立即报错，而不是猜测坐标乱点。

排查：看当时的截图，确认目标元素是否真的在当前屏幕上可见。

解决：

  • 把复杂任务拆成更小、更明确的原子步骤（MCP chat 工具有 5 步限制，超出会报 STEP_LIMIT_EXCEEDED）。
  • 元素需要滚动才能出现时，先让 Agent 滚动到可见区域，再执行点击。
  • 任务描述里给出更具体的目标特征（按钮文字、所在位置等），减少歧义。

排障工具：日志与追踪​

按上面条目仍无法定位时，用日志和追踪文件还原完整执行过程：

  • 日志文件：默认写到 logs/autoglm_{日期}.log。需要更详细信息时，启动时加 --log-level DEBUG。
  • 追踪文件：每次任务的 span 以 JSONL 写入 logs/trace_{日期}.jsonl。先从任务或历史记录里拿到 trace_id，再用它过滤追踪文件，即可看到每一步的截图、模型调用、动作执行和耗时。
  • 聚合指标：任务完成后可通过 /api/metrics 查看 Prometheus 直方图。

追踪机制、span 覆盖范围和完整的调试流程见 可观测性。

提交 Issue 时附上对应时间段的日志和 trace_id，能帮助快速定位问题。