ApkClaw完整指南:5步上手,用一句话让AI帮你操控手机
ApkClaw完整指南:5步上手,用一句话让AI帮你操控手机
ApkClaw 是一款 AI 驱动的 Android 自动化应用:它通过自然语言让 LLM Agent 直接操控你的安卓手机。你只需在钉钉、飞书、QQ、Discord 或 Telegram 里发一句话,比如"帮我打开微信给张三发消息",AI Agent 就会理解意图、自主执行点击与滑动,并把结果回复给你。这篇完整指南将带你用 5 步快速上手这款 AI 手机操控工具。
ApkClaw 是如何操控手机的?
ApkClaw 的工作原理可以概括为"观察 → 思考 → 行动 → 验证"的 Agent 循环:
- 你通过已连接的消息渠道发送自然语言指令;
ChannelManager把消息路由给TaskOrchestrator,后者获取任务锁并回到桌面,重置设备状态;- Agent 核心 DefaultAgentService.kt 开始循环:先读取屏幕 UI 层级树,再调用 LLM 决策,然后执行对应的操作工具(点击、滑动、输入文字等);
- 工具执行结果反馈给 LLM,循环往复,直到任务完成或调用
finish工具收尾; - 最终结果通过同一渠道回复给你。
底层设备交互由无障碍服务 ClawAccessibilityService.java 完成,支持点击、滑动、长按、按键注入和截屏。
5步快速上手
第1步:获取并构建 ApkClaw
环境要求:Java 17+、Android Studio、Android SDK 36(最低 SDK 28,即 Android 9+)。
git clone https://gitcode.com/gh_mirrors/ap/ApkClaw
cd ApkClaw
./gradlew assembleDebug
将生成的 Debug APK 安装到手机即可,详细构建说明见 README_CN.md。
第2步:一键开启5项核心权限
安装后进入首页,ApkClaw 会用清晰的卡片列表展示全部所需权限,逐项开启即可:
| 权限 | 作用 |
|---|---|
| Accessibility Service(无障碍服务) | AI 操控手机的核心,负责手势注入与 UI 读取 |
| Persistent Notification(常驻通知) | 展示运行状态,防止被系统误杀 |
| System Window(悬浮窗) | 显示悬浮球控制面板 |
| Battery Whitelist(电池白名单) | 防止后台被系统终止 |
| File Access(文件访问) | 读写设备文件 |
全部变为 Enabled(绿色)后,AI 手机自动化能力才算真正就绪。
第3步:填好3项配置,完成 LLM 接入
进入右上角"设置 → LLM Config",只需填写 3 个字段:
| 配置项 | 说明 |
|---|---|
| API Key | 你的 OpenAI 或 Anthropic 密钥 |
| Base URL | LLM 接口地址,默认 https://api.openai.com/v1,使用第三方服务时修改 |
| Model Name | 模型名称,如 gpt-4o、claude-sonnet-4-20250514 |
ApkClaw 通过 LlmClientFactory.kt 提供可插拔的 LLM 后端,同时支持 OpenAI 兼容接口与 Anthropic 接口,并可选开启流式输出。
第4步:接入一个消息渠道
LLM 配置好后,在同一个设置页为你的消息渠道填写机器人凭证。支持的渠道与所需凭证如下:
| 渠道 | 协议 | 所需凭证 |
|---|---|---|
| 钉钉 | App Stream Client | Client ID + Client Secret |
| 飞书 | OAPI SDK | App ID + App Secret |
| QQ Bot API | App ID + App Secret | |
| Discord | Gateway WebSocket + REST | Bot Token |
| Telegram | Bot HTTP API | Bot Token |
各渠道处理器位于 channel/ 目录下,消息统一由 ChannelManager.kt 路由分发。至少接入一个渠道即可开始使用。
💡 小贴士:嫌在手机上一个个填太麻烦?在设置里开启 LAN Config,然后在电脑浏览器访问 http://<设备IP>:9527,即可在网页上配置 LLM 和渠道凭证,敏感信息还会自动脱敏显示。
第5步:发一句话,AI 开始干活
一切就绪后,直接在已接入的渠道里发送自然语言指令,例如:
"打开浏览器搜索今天的新闻,把第一条的标题发给我"
AI Agent 会自动完成:读取屏幕 → 决策打开浏览器 → 点击搜索框 → 输入关键词 → 提取结果 → 通过渠道回复。整个过程无需你碰手机。
ApkClaw 支持哪些手机操作?
工具按设备类型在 ToolRegistry.kt 中注册,常用能力包括:
- 通用工具:获取 UI 层级树、按文字/ID 查找元素、截图、输入文本、打开应用、锁屏、等待、重复一组操作、发送文件等;
- 手机专属工具:
tap点击坐标、long_press长按、swipe滑动、click_by_text按文字点击,甚至在应用商店搜索应用。
每个工具都在 tool/impl/ 中实现,并内置中英文双语描述,供 LLM 准确理解。
实用技巧与注意事项
- 单任务模型:同一时间只执行一个任务,新指令会等待当前任务结束;
- 最大 40 轮迭代:Agent 循环有安全上限,避免无限执行;
- 死循环自动干预:连续 4 轮操作指纹相同时,Agent 会被强制换一种方式尝试;
- 系统弹窗需手动处理:遇到受保护的系统权限弹窗时,AI 会截图发给你并暂停任务,人工确认后继续即可。
关键模块速查
| 模块 | 路径 |
|---|---|
| Agent 循环 | agent/ |
| 消息渠道 | channel/ |
| 无障碍服务 | service/ |
| 工具系统 | tool/ |
| 局域网配置服务器 | server/ |
| 完整文档 | README_CN.md |
至此,ApkClaw 的完整配置流程就走完了:安装 → 授权 → 配 LLM → 接渠道 → 发指令。从此你的一句话,就是一台听话的 AI 手机。

