ApkClaw内置20+工具全解析:从tap、swipe到scroll_to_find
ApkClaw内置20+工具全解析:从tap、swipe到scroll_to_find
ApkClaw 是一款 AI 驱动的 Android 自动化应用:你只需用自然语言发消息,它内置的 AI Agent 就能替你点击、滑动、输入、打开 App。而 Agent "动手"能力的一切,都来自它内置的 20+ 个自动化工具——从 tap(点击)、swipe(滑动)到高效的 scroll_to_find(滚动查找),覆盖"看屏幕 → 想方案 → 执行操作 → 交付结果"的完整闭环。本文带你全解析这套工具清单与实用技巧。
一、工具系统是如何工作的
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获取有效坐标。
二、全部 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 干活更快更稳 💡
- 典型任务链路:
open_app→get_screen_info→tap→input_text→wait(或wait_after)→finish。你在消息里说"帮我给 XX 发条消息",Agent 会自动走这条路。 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)。system_key一鍵多用:back返回、home回桌面、notifications展开通知栏、unlock_screen唤醒解锁,一个工具覆盖 7 种系统按键。- 结果自动送达:任务完成后
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 的思路串了起来而已。

