phone-agent-lan（电话 Agent 局域网）

📱 手机操控技能 (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. 检查连接

adb devices

应显示设备 ID，如 803203a device

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

依赖工具（已预装）

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

验证安装

# 检查 adb
adb version

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

第三部分：Skill 使用方法

基本命令

# 查看连接状态
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

第四部分：典型工作流程

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

# 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 中找到联系人坐标，点击进入

流程二：发送消息

# 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 结构

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

分析脚本

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 计算点击坐标

# 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:

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

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

附录：常用 App 包名