📱 手机操控技能 (phone-agent)#

功能概览#

• 通过 USB ADB 连接安卓手机
• 捕获手机屏幕（UI Dump，无需 AI 看图）
• 分析界面元素位置（XML 结构解析）
• 执行 UI 操作：点击、滑动、输入文字、按键
• 打开 App、搜索联系人、发送简单消息

限制#

• ⚠️ 无法直接输入中文（ADB input text 绕过输入法，只能输入英文/数字/拼音）
• ⚠️ 需要 USB 调试权限
• ⚠️ 部分国产手机（如小米）需要额外开启"USB 调试安全设置"

---

第一部分：手机端配置（新手机一次性操作）#

1. 开启开发者选项#

1. 设置 → 关于手机 → 连续点击"MIUI 版本号"7次
2. 返回设置 → 更多设置 → 开发者选项

2. 开启 USB 调试#

1. 开发者选项 → 开启"USB 调试"

2. 小米额外设置：开发者选项 → 开启"USB 调试(安全设置)"

   • 这个需要 SIM 卡关联的小米账号登录后才能开启
   • 或者插 SIM 卡重启后自动解锁

3. 连接手机#

1. 用 USB 线连接手机和 Mac（电脑）
2. 手机上弹出"允许 USB 调试"→ 点"允许"
3. 建议同时开启"充电模式下允许 ADB"

4. 调整手机设置（避免息屏断开）#

1. 设置 → 显示 → 息屏时间 → 改为"最长"
2. 或保持手机在充电状态

5. 检查连接#

bash

adb devices

应显示设备 ID，如 803203a device

---

第二部分：Skill 安装检查清单#

依赖工具（已预装）#

• ✅ adb（Android SDK Platform Tools）
• ✅ python3（内置）
• ✅ 截图工具（系统自带）

验证安装#

bash

# 检查 adb
adb version

# 检查 skill 脚本
ls -la ~/.openclaw/skills/phone-agent/agent.py

---

第三部分：Skill 使用方法#

基本命令#

bash

# 查看连接状态
python3 ~/.openclaw/skills/phone-agent/agent.py connected

# 截图并保存到临时文件
python3 ~/.openclaw/skills/phone-agent/agent.py screenshot

# 获取屏幕尺寸
python3 ~/.openclaw/skills/phone-agent/agent.py size

# 点击坐标 (x, y)
python3 ~/.openclaw/skills/phone-agent/agent.py tap 500 1000

# 滑动 (x1, y1, x2, y2, duration)
python3 ~/.openclaw/skills/phone-agent/agent.py swipe 600 2400 600 800

# 输入文字（仅英文/数字）
python3 ~/.openclaw/skills/phone-agent/agent.py text "hello"

# 按键
python3 ~/.openclaw/skills/phone-agent/agent.py home      # HOME 键
python3 ~/.openclaw/skills/phone-agent/agent.py back      # 返回键
python3 ~/.openclaw/skills/phone-agent/agent.py power     # 电源键

# 启动 App（包名）
python3 ~/.openclaw/skills/phone-agent/agent.py start com.tencent.mm

# 强制停止 App
python3 ~/.openclaw/skills/phone-agent/agent.py stop com.tencent.mm

---

第四部分：典型工作流程#

流程一：打开微信并搜索联系人#

bash

# 1. 启动微信
adb shell monkey -p com.tencent.mm -c android.intent.category.LAUNCHER 1

# 2. 等待启动后，dump UI 结构
adb exec-out uiautomator dump /sdcard/dump.xml && adb pull /sdcard/dump.xml /tmp/dump.xml

# 3. 分析 XML，找到搜索按钮坐标
python3 << 'EOF'
import xml.etree.ElementTree as ET
tree = ET.parse('/tmp/dump.xml')
root = tree.getroot()
for node in root.iter():
    text = node.attrib.get('text', '')
    bounds = node.attrib.get('bounds', '')
    if '搜索' in text or 'search' in text.lower():
        print(f"TEXT: {text}, BOUNDS: {bounds}")
EOF

# 4. 点击搜索按钮（如坐标 [912,140][1056,284]）
python3 ~/.openclaw/skills/phone-agent/agent.py tap 984 212

# 5. 输入搜索文字
python3 ~/.openclaw/skills/phone-agent/agent.py text "蓝汐"

# 6. 在搜索结果 XML 中找到联系人坐标，点击进入

流程二：发送消息#

bash

# 1. 在聊天界面，找到输入框和发送按钮的坐标
# 2. 点击输入框
python3 ~/.openclaw/skills/phone-agent/agent.py tap 540 2534

# 3. 输入文字
python3 ~/.openclaw/skills/phone-agent/agent.py text "hello"

# 4. 点击发送按钮（如坐标 [1020,1476][1170,1608]）
python3 ~/.openclaw/skills/phone-agent/agent.py tap 1095 1542

---

第五部分：UI Dump 分析指南#

获取 UI 结构#

bash

adb exec-out uiautomator dump /sdcard/dump.xml && adb pull /sdcard/dump.xml /tmp/dump.xml

分析脚本#

python

import xml.etree.ElementTree as ET

tree = ET.parse('/tmp/dump.xml')
root = tree.getroot()

# 查找所有可点击元素
for node in root.iter():
    text = node.attrib.get('text', '')
    bounds = node.attrib.get('bounds', '')
    clickable = node.attrib.get('clickable', '')
    resource_id = node.attrib.get('resource-id', '')

    if clickable == 'true' and text:
        print(f"TEXT: {text!r}, BOUNDS: {bounds}, ID: {resource_id}")

# 查找特定关键词
for node in root.iter():
    text = node.attrib.get('text', '')
    bounds = node.attrib.get('bounds', '')
    if '微信' in text or '搜索' in text:
        print(f"FOUND: {text!r}, BOUNDS: {bounds}")

从 bounds 计算点击坐标#

python

# bounds = "[228,1766][1008,1835]"
# 中心点: x = (228+1008)/2 = 618, y = (1766+1835)/2 = 1800

---

第六部分：常见问题#

Q: USB 频繁断开#

A:

1. 手机息屏后会断开 → 开启"保持唤醒"或"充电模式下调试"
2. USB 线质量差 → 换一根好线
3. 重启 ADB: adb kill-server && adb start-server

Q: 点击位置不准#

A:

1. 确认屏幕分辨率： adb shell wm size
2. UI Dump 的 bounds 是物理坐标，直接计算中心点点击
3. 多次点击有偏移可以调整 ±10-20 像素

Q: 无法输入中文#

A:

• ADB input text 只能输入 ASCII 字符
• 解决方案：
  1. 在手机上预先打开输入法，让 AI 控制粘贴
  2. 使用 ClipboardManager（需要 App 配合）
  3. 通过 App Inventor 开发专用剪贴板 App

Q: 小米手机点击无效#

A:

• 必须开启"USB 调试(安全设置)"
• 设置 → 更多设置 → 开发者选项 → USB 调试安全设置

Q: 如何获取 App 包名？#

A:

bash

# 方法1: 列出已安装包
adb shell pm list packages | grep 关键词

# 方法2: 在 Play 商店查看 URL 中的 id
# 方法3: 用 UI Dump 分析桌面图标

---

附录：常用 App 包名#

App包名微信com.tencent.mmQQcom.tencent.mobileqq美团com.sankuai.meituan淘宝com.taobao.taobao支付宝com.eg.android.AlipayGphone抖音com.ss.android.ugc.aweme小红书com.xingin.xhsBluedcom.soft.blued