ApkClaw内置20+工具全解析:从tap、swipe到scroll_to_find

原创2026-10-26 19:13:181,626 阅读
文章标签:人工智能AI Agent大模型GUI 自动化移动开发工具调用

ApkClaw内置20+工具全解析:从tap、swipe到scroll_to_find

ApkClaw 是一款 AI 驱动的 Android 自动化应用:你只需用自然语言发消息,它内置的 AI Agent 就能替你点击、滑动、输入、打开 App。而 Agent "动手"能力的一切,都来自它内置的 20+ 个自动化工具——从 tap(点击)、swipe(滑动)到高效的 scroll_to_find(滚动查找),覆盖"看屏幕 → 想方案 → 执行操作 → 交付结果"的完整闭环。本文带你全解析这套工具清单与实用技巧。

ApkClaw首页界面:无障碍服务、持续通知、系统窗口等五项权限管理卡片

一、工具系统是如何工作的

ApkClaw 的工具体系由三层构成,理解这个结构有助于你读懂任意一个新工具:

层级 角色 源码位置
BaseTool 所有工具的抽象基类,定义参数、执行、中英文双语描述 BaseTool.kt
ToolRegistry 工具注册中心,按设备类型(手机/电视)动态注册可用工具 ToolRegistry.kt
ClawAccessibilityService 真正的"手",通过无障碍服务执行手势、注入按键、读取界面 ClawAccessibilityService.java

三个值得新手注意的通用机制:

  • 按设备切换工具集:启动时通过 registerAllTools(DeviceType.MOBILE / TV) 决定注册手机工具还是电视遥控器工具,通用工具则全部设备共享(见 ToolRegistry.kt#L18-L26)。
  • wait_after 通用参数:几乎所有操作类工具都自动附加 wait_after 参数(最长 10 秒),执行成功后自动等待页面加载,省得 AI 单独再调一次 wait(见 BaseTool.kt#L19-L26)。
  • 坐标安全校验:tap、swipe 等工具会先校验坐标是否在屏幕范围内,越界直接返回错误并提示用 get_screen_info 获取有效坐标。

ApkClaw设置页面:LLM模型配置与钉钉、飞书、QQ、Discord、Telegram等消息渠道配置

二、全部 25 个工具速查表

📱 通用工具(12 个,手机/电视都有)

工具名 作用 常用参数
get_screen_info 获取当前屏幕 UI 层级树(文本、ID、坐标、可点击性),AI 的"眼睛" 无
find_node_info 按可见文本查找元素,返回类名、边界等详情 text
take_screenshot 对当前屏幕截图并返回本地路径(需 Android 11+) 无
input_text 向当前聚焦的输入框输入文本,默认先清空 text、clear_first
open_app 通过包名打开应用 package_name
get_installed_apps 获取已安装应用列表(应用名 + 包名) 无
system_key 模拟系统按键:返回、Home、最近任务、通知栏、锁屏等 key
wait 等待指定毫秒数,用于等动画/加载 ms
repeat_actions 将一组动作组合成序列并循环执行,默认 3~10 秒随机间隔 actions、repeat_count
clipboard 读取或写入剪贴板 action(get/set)、text
send_file 把设备上的文件通过消息渠道发给用户 path
finish 标记任务完成,并附上结果摘要 summary

🤏 手机专属工具(5 个)

工具名 作用 常用参数
tap 在指定坐标 (x, y) 点击 x、y
long_press 在指定坐标长按,默认 1 秒 x、y、duration_ms
swipe 从 A 点滑动到 B 点,默认 500ms start_x/y、end_x/y、duration_ms
scroll_to_find 自动滚动屏幕查找包含指定文本的元素,并返回其坐标 text、direction、max_scrolls
search_app_in_store 自动识别手机品牌并打开对应应用商店 无

📺 电视专属工具(8 个)

工具名 作用
dpad_up / dpad_down / dpad_left / dpad_right 遥控器四方向键,移动焦点
dpad_center 遥控器确认/OK 键
volume_up / volume_down 音量加减
press_menu 菜单键,打开上下文菜单
press_power 电源键,关闭屏幕或休眠

三、重点解析:手机操作四件套

1️⃣ tap —— 最基础的一步

参数只有 x、y 两个整数,执行前校验坐标合法性(见 TapTool.java#L44-L57)。AI 的常规节奏是:get_screen_info 拿到元素坐标 → tap 点击 → 观察结果。

2️⃣ long_press —— 长按触发菜单

在 tap 基础上多了 duration_ms 参数(默认 1000 毫秒)。长按图片保存、长按图标看应用信息,都靠它。

3️⃣ swipe —— 滑动的万能动作

起点、终点四个坐标 + 持续时间。同一个工具可以完成:上下滚动列表、下拉通知栏、左滑删除、横滑切换页面。

4️⃣ scroll_to_find —— 本文主角

在长列表里找某个元素,最朴素的做法是让 AI 循环调用 swipe + get_screen_info,又慢又费 token。scroll_to_find 把这件事封装成一次调用(源码见 ScrollToFindTool.java):

  • 参数简单:只要告诉它找什么 text,滚动 direction(默认 down)和最多滚动次数 max_scrolls(默认 10 次,上限 20 次)都是可选项;
  • 智能滚动:在屏幕中间区域滚动,自动避开状态栏和底部导航栏;
  • 提前结束:每滚一次就搜索一次,同时对比屏幕内容快照,一旦检测到底部/顶部不再变化就立刻停止,不会傻滑;
  • 返回坐标:找到后直接给出元素的 bounds、中心坐标、是否可点击、类名,AI 拿到坐标就可以直接 tap。

一句话:想"边滚边找",永远优先用它而不是手动循环滑动。

5️⃣ search_app_in_store —— 帮你装 App

自动检测手机品牌并打开对应的应用商店,随后 AI 会通过 get_screen_info 找到搜索框、用 input_text 输入关键词完成下载——你只需要说一句"帮我装一下 XX"。

四、观察类工具:AI 的"眼睛"

工具 何时用
get_screen_info 了解当前界面长什么样,是所有决策的依据。默认输出精简模式以节省 token,也可切换完整节点树用于调试
find_node_info 交互前先"点名检查"某个元素:它在哪、能不能点、类名是什么
take_screenshot 需要图片证据时(如任务结果截图发给用户)

配合 BaseTool.kt#L36-L43 的设计,这些观察类工具不会附加 wait_after——因为它们本身就不改变屏幕,等待没有意义。

五、实用技巧:让 Agent 干活更快更稳 💡

  1. 典型任务链路:open_app → get_screen_info → tap → input_text → wait(或 wait_after)→ finish。你在消息里说"帮我给 XX 发条消息",Agent 会自动走这条路。
  2. repeat_actions 模拟真人:把多个工具调用打包成 JSON 数组循环执行,例如"刷 30 条短视频"= <a href="https://link.gitcode.com/i/8cbdf5e9fc22348e9bc82a4f9f28d8e6" target="_blank">swipe] × 30,每轮之间自动加 3~10 秒随机间隔,更像真人操作节奏;还支持设置固定间隔(如"每 10 秒滑一次")。它自带保护:单次最多 2000 步、最长 30 分钟,且禁止在循环里再套 repeat_actions 或调用 finish(源码见 [RepeatActionsTool.java#L39-L48)。
  3. system_key 一鍵多用:back 返回、home 回桌面、notifications 展开通知栏、unlock_screen 唤醒解锁,一个工具覆盖 7 种系统按键。
  4. 结果自动送达:任务完成后 send_file 可直接把截图、文件通过你配置的消息渠道发回来,finish 则附上文字总结——全程无需碰手机。

六、关键源码文件

文件 说明
tool/ToolRegistry.kt 工具注册中心,按设备类型组装工具集
tool/BaseTool.kt 工具抽象基类,wait_after 机制所在
tool/impl/mobile/ 手机工具:tap / swipe / long_press / scroll_to_find 等
tool/impl/tv/ 电视工具:dpad / volume / menu / power
service/ClawAccessibilityService.java 底层手势与节点树读取,所有工具的执行者
README_CN.md 项目整体架构与执行流程说明

掌握这套工具清单后,你就明白为什么 ApkClaw 只凭一句自然语言就能完成"打开应用 → 找到目标 → 执行操作 → 汇报结果"——它只是把这些 20+ 个原子工具,用 AI 的思路串了起来而已。

登录后查看全文
ApkClaw