图图智控（TUTU Smart Control）

图图智控（TUTU Smart Control）— 远程控制 Android 手机，执行 GUI 自动化、系统管理和日常任务。当用户提到以下任何内容时使用此 skill： - 控制手机、操作手机、手机上做某事 - 打开手机上的 App（微信、抖音、支付宝、淘宝等） - 手机截图、查看手机屏幕 - 在手机上点击、输入、滑动 - 手机自动化、GUI 自动化 - 查看手机状态（电量、网络、内存等） - 发短信、打电话、读短信、通讯相关 - 手机定位、获取位置 - 查看手机通知 - 手机震动、语音播报（TTS） - 手机文件管理（列目录、读写删文件、存储分析，仅限 /sdcard/ 用户存储） - 按文字/ID 点击 UI 元素、查找界面元素 - 搜索手机媒体文件（图片、视频、音乐） - 微信自动回复、社交应用自动化 - 手机定时任务、批量操作 - 手机健康检查、系统巡检

通过图图智控（TUTU）硬件设备，无需安装 App，USB 即插即用，让 AI 像人一样远程操控你的 Android 手机 — 截图、点击、滑动、输入、发短信、文件管理、应用管理、锁屏状态查看、网络设置、录屏等 60+ 种操作。

---

⚠️ Token 与鉴权（必读）

API Token 通过环境变量 TUTU_API_TOKEN 自动注入（由 ClawHub 管理），不需要用户在对话中手动提供或粘贴 Token。

首次使用流程

1. 确认环境变量已配置：用户需在 ClawHub 设置中填写 TUTU_API_TOKEN。
2. 调用 status 接口验证设备在线状态。
3. 验证成功后即可开始执行操作。

如何获取 Token

• 在 https://www.szs.chat 购买图图智控硬件并绑定设备后获取。
• Token 是一串加密字符串，由硬件设备自动生成，可在设备管理页面或扫描设备二维码获取。
• 每个 Token 对应一台设备，已包含设备身份信息，无需额外提供设备序列号。

安全原则：

• Token 通过环境变量注入，不在对话中传递或存储
• Token 已加密包含设备身份，无需明文传输设备序列号
• 不要在日志或对话中明文展示 Token

---

连接信息

• API 地址: https://www.szs.chat/api/phone_action.php
• 鉴权方式: Authorization: Bearer $TUTU_API_TOKEN（环境变量自动注入）
• 设备识别: Token 已加密包含设备信息，无需在请求中传递 SN
• 硬件要求: 图图智控 TUTU 硬件设备（USB-C 即插即用，无需安装 App）
• 屏幕分辨率: 默认 1080 x 2400（宽 x 高），坐标使用绝对像素

---

调用方式

通过 HTTP POST 请求调用 API，JSON 格式。Token 通过环境变量 TUTU_API_TOKEN 获取（由 ClawHub 自动注入），无需用户在对话中手动提供。

请求格式

• URL: https://www.szs.chat/api/phone_action.php
• Method: POST
• Headers: Content-Type: application/json, Authorization: Bearer $TUTU_API_TOKEN
• Body: {"action":"<ACTION>", ...其他参数}

Token 已加密包含设备信息，请求体中无需传递 SN 字段。

---

可用操作（完整列表 — 62 项）

一、基础 GUI 控制

1. 截图 — 查看手机当前屏幕

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"screenshot"}'

返回：

json

{
  "success": true,
  "action": "screenshot",
  "screenshot_url": "https://www.szs.chat/screenshots/<SN>_xxx.jpg",
  "screenshot_base64": "data:image/jpeg;base64,...",
  "width": 1080,
  "height": 2400
}

截图是最重要的操作！ 截图后用图像分析能力查看 screenshot_url 来理解屏幕内容，决定下一步操作。

2. 点击 — 点击屏幕上的指定位置

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"click", "x":540, "y":1200}'

参数：x（横坐标 0-1080）、y（纵坐标 0-2400），绝对像素。

3. 长按

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"long_press", "x":540, "y":1200}'

4. 输入文本

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"type", "text":"你好世界", "x":540, "y":600}'

参数：

• text（必填）：要输入的文本。中文自动使用剪贴板粘贴。末尾加 \n 表示输入后按回车。
• x、y（可选）：输入框坐标，会先点击聚焦再输入。

5. 滚动

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"scroll", "x":540, "y":1200, "direction":"down"}'

参数：

• direction：up、down、left、right
• x、y：滚动起始点（默认屏幕中心）

6. 拖拽

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"drag", "x1":540, "y1":1800, "x2":540, "y2":600}'

7. 打开应用

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"open_app", "app_name":"微信"}'

支持中文应用名！ 常用应用名：微信、抖音、支付宝、淘宝、京东、设置、相机、电话、短信、浏览器、地图、日历、时钟、文件管理。也可以用包名（如 com.tencent.mm）。

8. 按键操作

bash

# 按 Home 键（回到桌面）
curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"press_home"}'

# 按返回键
curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"press_back"}'

# 按回车键
curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"press_enter"}'

二、高级 UI 操作

9. 获取 UI 节点树

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_ui_nodes"}'

返回当前屏幕的 UI 元素树（JSON 数组），每个元素包含 cls（类型）、text（文本）、c（中心坐标）等信息。

10. 按文字点击 UI 元素

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"click_by_text", "text":"同意"}'

参数：text（必填）：要查找并点击的文字内容（模糊匹配）。比手动截图+估算坐标+click 更精准，优先考虑使用。

11. 按资源 ID 点击 UI 元素

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"click_by_id", "id":"com.tencent.mm:id/btn_send"}'

12. 查找 UI 元素

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"find_element", "text":"搜索", "className":"android.widget.EditText"}'

参数（至少一个）：text、id、className。返回元素列表含坐标信息。

三、系统信息与状态

13. 获取设备信息 — 电量、网络、内存、屏幕等

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_device_info"}'

返回：电量（battery.level/charging）、WiFi/移动网络状态、存储/内存用量、屏幕方向、前台应用包名、亮度、设备型号、Android 版本等。

14. 查询设备在线状态

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"status"}'

15. 获取服务端版本信息

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_server_info"}'

四、通讯功能

16. 发送短信

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"send_sms", "destination":"13800138000", "text":"你好"}'

17. 读取短信

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"read_sms", "limit":10}'

参数：limit（默认20）、box（inbox 收件箱 / sent 发件箱，默认 inbox）

18. 拨打电话

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"make_call", "number":"10086"}'

五、位置与通知

19. 获取 GPS 位置

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_location"}'

返回：latitude、longitude、accuracy、provider。

20. 读取系统通知

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"read_notifications", "limit":10}'

六、反馈输出

21. 震动

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"vibrate", "duration":500}'

22. 语音播报（TTS）

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"speak_tts", "text":"你好，世界"}'

七、文件管理（仅限 /sdcard/ 用户存储）

安全限制：所有文件操作仅限于 /sdcard/ 目录下的用户存储空间，无法访问系统分区或应用私有数据。删除操作需要用户确认。

23. 列出文件目录

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"list_files", "path":"/sdcard/DCIM"}'

24. 读取文件

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"read_file", "path":"/sdcard/test.txt"}'

参数：maxSize（可选，最大读取字节数，默认 64KB）

25. 写入文件

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"write_file", "path":"/sdcard/test.txt", "content":"Hello World"}'

参数：append（可选，true 为追加模式，默认覆盖）

26. 删除文件（需用户确认）

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"delete_file", "path":"/sdcard/test.txt"}'

27. 存储分析

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"analyze_storage"}'

28. 查找大文件

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"find_large_files", "path":"/sdcard", "minSize":10485760, "limit":20}'

八、媒体搜索

29. 搜索媒体文件

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"search_media", "mediaType":"image", "keyword":"screenshot", "limit":10}'

参数：mediaType（image/video/audio，默认image）、keyword（可选）、limit（默认20）

九、应用管理（v1.2.0）

31. 列出已安装应用

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"list_packages", "thirdPartyOnly":true, "includeVersions":false}'

参数：thirdPartyOnly（仅第三方应用，默认 false）、includeVersions（包含版本信息，默认 false）

32. 获取应用详细信息

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_app_info", "package":"com.tencent.mm"}'

返回：版本号、安装时间、更新时间、数据大小等。

33. 强制停止应用

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"force_stop_app", "package":"com.tencent.mm"}'

34. 卸载应用

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"uninstall_app", "package":"com.example.app", "keepData":false}'

36. 清除应用数据

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"clear_app_data", "package":"com.example.app"}'

十、设备设置控制（v1.2.0）

37. 设置屏幕亮度

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_brightness", "value":128, "mode":"manual"}'

参数：value（0-255）、mode（manual/auto）

38. 设置音量

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_volume", "value":10, "streamType":3}'

streamType：0=通话 1=系统 2=铃声 3=媒体 4=闹钟 5=通知

39. 获取音量

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_volume"}'

40. 设置屏幕旋转

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_rotation", "rotation":0, "lock":true}'

rotation：0=0° 1=90° 2=180° 3=270°。lock：true 锁定旋转，false 自动旋转。

41. 打开 URL

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"open_url", "url":"https://www.baidu.com"}'

十一、网络控制（v1.2.0）

42. 开关 WiFi

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_wifi", "enabled":true}'

43. 开关蓝牙

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_bluetooth", "enabled":false}'

十二、通讯录与通话记录（v1.2.0）

44. 读取通讯录

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"read_contacts", "limit":50, "query":"张三"}'

参数：limit（默认50）、query（按姓名搜索，可选）

45. 读取通话记录

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"read_call_log", "limit":20}'

返回：号码、姓名、类型（incoming/outgoing/missed）、通话时长等。

十三、GPS 模拟与系统设置（v1.2.0）

46. 模拟 GPS 定位

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_location_mock", "latitude":39.9042, "longitude":116.4074, "accuracy":1.0}'

需要开启开发者选项中的"允许模拟位置"。

47. 读取系统设置

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_setting", "table":"system", "key":"screen_brightness"}'

table：system/secure/global

十四、锁屏与安全（v1.3.0）

49. 获取锁屏状态

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_lock_status"}'

返回：屏幕是否亮、是否锁屏、密码类型（none/pin/password/pattern）。

十五、通话补充（v1.3.0）

53. 挂断当前通话

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"end_call"}'

十六、系统信息（v1.3.0）

54. 获取运行中进程

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_running_processes", "appsOnly":true}'

55. 获取电池统计

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_battery_stats"}'

返回：亮屏时间、估计容量、耗电排行等。

56. 获取系统日志

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"logcat", "filter":"scrcpy", "lines":100, "level":"W"}'

参数：filter（关键字过滤）、lines（行数，最大 1000）、level（V/D/I/W/E/F）

十七、文件传输增强（v1.3.0）

57. 从 URL 下载文件到设备

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"download_file", "url":"https://example.com/file.apk", "savePath":"/sdcard/Download/file.apk"}'

超时 120 秒。

十八、UI 自动化增强（v1.3.0）

58. 服务端长按

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"long_click", "x":540, "y":1200, "durationMs":800}'

服务端直接执行，减少 MQTT 往返延迟，比客户端 long_press 更可靠。

59. 服务端滑动

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"swipe", "x1":540, "y1":1800, "x2":540, "y2":600, "durationMs":300}'

60. 发送按键事件

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"input_keyevent", "keycode":"KEYCODE_CAMERA"}'

支持按键名称（如 KEYCODE_CAMERA）或数字编号（如 27）。

十九、网络与外设扩展（v1.3.0）

61. 扫描附近 WiFi

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"get_wifi_list"}'

返回：SSID、信号强度、频率、加密方式等。

62. 开关飞行模式

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_airplane_mode", "enabled":true}'

63. 设置屏幕超时

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_screen_timeout", "timeoutMs":60000}'

常用值：15000/30000/60000/120000/300000/600000 毫秒。

二十、通知与媒体扩展（v1.3.0）

64. 推送本地通知

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"push_notification", "title":"提醒", "text":"任务完成"}'

65. 设置壁纸

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"set_wallpaper", "path":"/sdcard/wallpaper.jpg", "which":"home"}'

which：home（主屏）、lock（锁屏）、both（两者）。图片须已在设备上。

66. 截屏到设备文件

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"take_screenshot_to_file", "path":"/sdcard/screenshot.png"}'

截图保存为 PNG 到设备本地（不返回给客户端）。

67. 录屏

bash

curl -s -X POST https://www.szs.chat/api/phone_action.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TUTU_API_TOKEN" \
  -d '{"action":"record_screen", "durationSec":10, "path":"/sdcard/recording.mp4"}'

最长 180 秒，录制期间阻塞等待完成。

---

操作流程（重要！）

执行手机任务时，严格遵循以下循环流程：

步骤 0：验证连接（首次必须）

1. 确认用户已提供 Token 和 SN
2. 调用 status 验证设备在线
3. 调用 get_device_info 了解设备基本情况（电量、网络、前台应用、屏幕方向）

步骤 1：先截图看屏幕

每次操作前必须先截图，了解当前屏幕状态。

步骤 2：分析截图

使用图像分析能力查看截图 URL，理解当前屏幕：

• 当前在什么应用/页面？
• 目标元素在哪里？坐标大概是多少？
• 屏幕是否锁定？
• 是否有弹窗/对话框需要处理？

步骤 3：执行操作

根据分析结果选择合适的操作（参考上方 30 项操作列表）。

优先使用 click_by_text 而非手动坐标点击，精准度更高。

步骤 4：等待 + 再截图验证

操作后等待 2-3 秒让手机响应，然后再次截图验证操作结果。

重复步骤 1-4 直到任务完成。

---

坐标参考

屏幕分辨率 1080 x 2400：

• 屏幕中心：(540, 1200)
• 状态栏高度约：0-80px
• 导航栏高度约：2300-2400px
• 顶部区域：y < 400
• 中部区域：400 < y < 1800
• 底部区域：y > 1800

---

场景示例

场景 1：打开微信并发送消息

text

1. open_app("微信") → 等 3 秒 → screenshot
2. 分析截图，找到目标联系人 → click 或 click_by_text
3. 等 2 秒 → screenshot → 确认进入聊天
4. type("你好", x=输入框x, y=输入框y)
5. click_by_text("发送") 或 click(发送按钮坐标)
6. screenshot → 确认消息已发送

场景 2：微信自动回复

text

1. read_notifications(limit=5) → 检查是否有微信新消息通知
2. 如果有新消息 → open_app("微信")
3. screenshot → 分析聊天列表，找到未读消息
4. click_by_text(联系人名) → 进入聊天
5. screenshot → 阅读对方发来的消息
6. type("收到，稍后回复") → click_by_text("发送")
7. screenshot → 确认发送成功

场景 3：App 签到/打卡

text

1. open_app("目标App") → 等 3 秒 → screenshot
2. 分析截图，找到签到入口
3. click_by_text("签到") 或 click(签到按钮坐标)
4. screenshot → 处理可能的弹窗（点击"确定"/"关闭"）
5. screenshot → 确认签到成功

场景 4：查看手机当前状态（综合巡检）

text

1. get_device_info → 获取电量、网络、内存、前台应用
2. analyze_storage → 查看存储空间
3. read_notifications(limit=10) → 查看未处理通知
4. screenshot → 查看当前屏幕
5. 向用户汇报完整的手机状态

场景 5：存储空间清理

text

1. analyze_storage → 了解总容量和可用空间
2. find_large_files(minSize=50MB) → 找到占空间的大文件
3. 向用户列出大文件，等待确认哪些可以删除
4. delete_file(path=用户确认的文件) → 逐个删除
5. analyze_storage → 再次确认清理效果

场景 6：发短信给某人

text

1. send_sms(destination="13800138000", text="明天下午开会")
2. 检查返回 success=true 确认发送成功

场景 7：查看最近收到的验证码

text

1. read_sms(limit=5, box="inbox") → 读取最近 5 条收件箱短信
2. 从短信内容中提取验证码数字
3. 向用户展示验证码

场景 8：获取手机位置

text

1. get_location → 获取 GPS 坐标
2. 向用户报告经纬度和大致位置描述

场景 9：唤醒屏幕

如果截图显示屏幕熄灭：

text

1. click(540, 1200) → 唤醒屏幕
2. drag(540, 2000, 540, 800) → 上滑（无密码锁屏场景）
3. screenshot → 确认屏幕已亮

场景 10：手机找回/防丢失

text

1. get_location → 获取当前位置
2. vibrate(duration=3000) → 持续震动 3 秒
3. speak_tts("请注意，有人正在寻找这部手机") → 语音提示
4. screenshot → 截图记录当前屏幕状态
5. 向用户报告位置和操作结果

场景 11：批量处理通知

text

1. read_notifications(limit=20) → 获取所有通知
2. 按 App 分类整理通知内容
3. 向用户汇总：哪些是重要的、哪些可以忽略
4. 如用户要求，open_app 进入对应 App 处理

场景 12：手机上搜索和整理照片

text

1. search_media(mediaType="image", keyword="screenshot") → 搜索截图
2. 向用户列出找到的图片
3. 如需删除 → delete_file(path=图片路径) 逐个清理

场景 13：安装应用状态检查

text

1. list_packages(thirdPartyOnly=true) → 列出所有第三方应用
2. 格式化展示已安装应用列表
3. 如用户要求 → get_app_info(package="com.example.app") 查看特定应用信息

场景 14：应用管理 — 查看/卸载/清除数据

text

1. list_packages(thirdPartyOnly=true, includeVersions=true) → 列出第三方应用
2. 向用户展示应用列表和版本
3. get_app_info(package="com.example.app") → 查看特定应用详情
4. 如用户要求卸载 → uninstall_app(package="com.example.app")
5. 如用户要求清理 → clear_app_data(package="com.example.app")

场景 15：查看锁屏状态

text

1. get_lock_status → 查看当前锁屏状态和密码类型
2. 向用户报告锁屏状态

场景 16：WiFi 管理

text

1. get_wifi_list → 扫描附近 WiFi 网络
2. 向用户展示可用网络（名称、信号、频段）
3. set_wifi(enabled=true) → 确保 WiFi 已开启
4. 如需连接特定网络 → 引导用户在手机上手动操作或通过 GUI 自动化点击设置

场景 17：设备设置调整

text

1. set_brightness(value=128, mode="manual") → 调节亮度
2. set_volume(value=10, streamType=3) → 调节媒体音量
3. set_rotation(rotation=0, lock=true) → 锁定竖屏
4. set_screen_timeout(timeoutMs=300000) → 5 分钟屏幕超时

场景 18：GPS 模拟定位

text

1. set_location_mock(latitude=39.9042, longitude=116.4074) → 模拟北京天安门
2. get_location → 验证位置是否已更改
3. 向用户报告模拟位置结果

场景 19：通讯录与通话记录查询

text

1. read_contacts(limit=20, query="张") → 搜索姓张的联系人
2. read_call_log(limit=10) → 查看最近通话记录
3. 向用户汇总联系人和通话信息
4. 如需拨打 → make_call(number="13800138000")
5. 如需挂断 → end_call

场景 20：系统信息收集

text

1. get_device_info → 硬件信息
2. get_server_info → 服务端版本
3. get_running_processes(appsOnly=true) → 运行中应用
4. get_battery_stats → 电池详细统计
5. logcat(filter="error", lines=50, level="E") → 错误日志
6. 汇总为系统信息报告

场景 21：语音助手模式

text

1. 用户下达语音/文字指令
2. speak_tts("好的，正在为您执行") → 语音反馈
3. 执行对应操作（打开App、发短信、查信息等）
4. speak_tts("操作完成") → 语音通知结果
5. screenshot → 发送截图给用户确认

场景 22：社交应用内容浏览

text

1. open_app("抖音") → 等 3 秒 → screenshot
2. scroll(direction="up") → 上滑查看下一个视频
3. screenshot → 分析当前视频内容
4. 重复滑动浏览，或 click_by_text("关注"/"点赞")

场景 23：电商比价/下单辅助

text

1. open_app("淘宝") → 等 3 秒 → screenshot
2. find_element(className="android.widget.EditText") → 找到搜索框
3. click(搜索框坐标) → type("蓝牙耳机\n")
4. screenshot → 分析搜索结果，汇报价格和商品信息
5. 如用户要求，点击进入商品详情

场景 24：下载文件到设备

text

1. download_file(url="https://example.com/document.pdf", savePath="/sdcard/Download/document.pdf")
2. 等待下载完成（超时 120 秒）
3. list_files(path="/sdcard/Download") → 确认文件已保存

场景 25：录屏与截图保存

text

1. record_screen(durationSec=10, path="/sdcard/recording.mp4") → 录制 10 秒视频
2. take_screenshot_to_file(path="/sdcard/screenshot.png") → 截图保存到设备
3. list_files(path="/sdcard") → 确认文件已生成

场景 26：系统日志排查

text

1. logcat(filter="crash", lines=200, level="E") → 查看错误日志
2. get_running_processes(appsOnly=true) → 查看运行中应用
3. get_battery_stats → 查看耗电排行
4. 向用户汇报异常信息和建议

场景 27：通知推送与壁纸设置

text

1. push_notification(title="提醒", text="该起床了") → 推送通知
2. set_wallpaper(path="/sdcard/DCIM/photo.jpg", which="both") → 设置壁纸
3. screenshot → 确认壁纸已更换

---

安全设计

本 Skill 遵循最小权限原则，在保障远程控制功能的同时限制潜在的安全风险：

• 无 Shell 执行权限：不提供任意 shell 命令执行能力，所有操作通过专用 API 完成，防止命令注入攻击
• 无系统设置写入权限：不支持修改 Android 系统设置，仅支持只读查询（如亮度、超时时间）用于状态诊断
• 文件访问沙箱化：文件操作仅限 /sdcard/ 用户存储空间，无法访问系统分区、应用私有数据或敏感系统文件
• 无密码/解锁权限：不支持远程解锁屏幕、设置或清除锁屏密码，避免在对话中传递 PIN/密码等敏感凭据。仅支持只读查询锁屏状态
• 无 APK 安装权限：不支持远程安装应用，消除 download + install 远程代码执行链
• 不在对话中收集敏感凭据：本 Skill 不会在对话中要求用户输入设备 PIN、密码或其他凭据。唯一需要的密钥 TUTU_API_TOKEN 通过环境变量注入
• 隐私数据读取需确认：读取短信、通讯录、通话记录、GPS 位置等个人隐私数据均标记 confirmation: true，需用户明确确认后才能访问
• 敏感操作需确认：发短信、打电话、卸载应用、删除文件、下载文件、GPS 模拟、飞行模式等操作均标记 confirmation: true，需用户明确确认后执行
• confirmation 机制说明：标记 confirmation: true 的工具在执行前由平台（ClawHub/OpenClaw）拦截并弹出确认对话框，用户必须在平台 UI 中显式批准后工具才会执行。这是平台级的强制拦截，不是对话中的文字确认，AI Agent 无法绕过此机制
• 系统信息仅只读：logcat、get_running_processes、get_setting、get_battery_stats 等工具仅提供只读诊断信息，用于设备健康检查和问题排查，不具备任何系统修改能力
• Token 通过环境变量注入：API Token 通过 TUTU_API_TOKEN 环境变量由 ClawHub 安全注入，不在对话中传递或存储，避免泄漏风险
• 所有请求经服务端鉴权：每个 API 调用都通过 Bearer Token 鉴权，无匿名访问

---

注意事项

• 截图操作可能需要 3-5 秒，这是正常的（需要通过图图智控服务端中转）
• 操作后一定要截图验证，不要盲目连续操作
• 坐标是绝对像素，不是百分比。屏幕宽 1080、高 2400
• 中文输入会自动通过剪贴板粘贴，无需特殊处理
• 如果截图超时，先用 status 检查设备状态
• 每次操作后等待 2-3 秒再截图（open_app 等待 3 秒）
• 可通过 get_device_info 的 foregroundApp 字段确认当前前台应用
• 执行网络相关任务前，先检查 network 状态确认设备有网络连接
• click_by_text 比手动截图+估算坐标+click 更精准，优先使用
• find_large_files 扫描大文件可能较慢（超时 30 秒）
• 发短信 send_sms 和打电话 make_call 依赖手机的 SIM 卡和信号
• 图图智控硬件通过 USB 连接手机，利用 ADB 协议控制，完全不影响手机日常使用
• download_file 超时 120 秒，适合较大文件
• record_screen 会阻塞直到录制完成，超时 = 录制时长 + 15 秒
• set_location_mock 需要手机开启开发者选项中的"允许模拟位置"
• set_airplane_mode 会断开所有无线连接，需用户确认后执行
• v1.3.0 新增 long_click、swipe、input_keyevent 在服务端直接执行，比客户端多次 touch 更可靠