droidclaw最新版

想象一下，你手头有一台闲置的旧安卓手机。与其让它落灰，不如将其转化为一个能够理解人类意图、自主操作屏幕的人工智能代理。

• 官网：https://droidclaw.ai
• GitHub：https://github.com/unitedbyai/droidclaw

droidclaw 不仅仅是一个自动化脚本工具，更像是一个拥有大型语言模型（LLM）“大脑”的虚拟操作员。你只需用简单的英语（或自然语言）下达一个目标，它便能像人一样读取屏幕内容、思考下一步动作、通过 ADB（Android Debug Bridge）执行点击与输入，并不断循环这一过程，直到任务完成。

核心理念：当自动化遇上 LLM

几年前，安卓自动化主要依赖预定义的流程（如 Tasker 或 MacroDroid）。你需要精确指定“点击坐标 (x, y)”或“查找特定 ID 的控件”。一旦应用界面更新，脚本便会失效。

droidclaw 改变了这一范式。它将传统的自动化层与大型语言模型相结合：

• 无需 API 密钥： 不需要为每个应用申请开发者接口。
• 无需构建集成： 只要手机上安装了应用，代理就能操作。
• 通用性： 它能理解任何屏幕布局，决定点击哪里、输入什么。

最令人兴奋的是，droidclaw 可以将复杂请求委托给手机上的现有应用。例如，让它“查询天气并发送给妈妈”，它会自主打开浏览器或搜索应用，获取信息，再切换到 WhatsApp 发送消息。这一切都像是在模仿真人的操作路径，完全绕过了服务端的 API 限制。

运行实录

以下是一次典型的任务执行日志，展示了代理如何一步步拆解并完成任务：

$ bun run src/kernel.ts
enter your goal: open youtube and search for "lofi hip hop"

--- step 1/30 ---
think: i'm on the home screen. launching youtube.
action: launch (842ms)

--- step 2/30 ---
think: youtube is open. tapping search icon.
action: tap (623ms)

--- step 3/30 ---
think: search field focused.
action: type "lofi hip hop" (501ms)

--- step 4/30 ---
action: enter (389ms)

--- step 5/30 ---
think: search results showing. done.
action: done (412ms)

工作原理：感知 → 推理 → 行动

droidclaw 的核心运行逻辑是一个闭环系统，不断重复以下三个步骤，直至目标达成或达到最大步数限制：

1. 感知 (Perceive)： 通过 ADB 获取当前的无障碍功能树（Accessibility Tree），将其解析为可交互的 UI 元素列表。同时，它会对比上一帧的屏幕状态以检测变化，必要时截取屏幕截图作为视觉补充。
2. 推理 (Reason)： 将当前的屏幕结构、用户设定的目标以及过往的操作历史打包发送给大型语言模型。LLM 会返回一个包含“思考过程”、“下一步计划”和“具体行动”的结构化指令（例如：“我看到搜索图标在坐标 (890, 156)，我应该点击它”）。
3. 行动 (Act)： 根据 LLM 的指令，通过 ADB 执行具体的点击、输入、滑动等操作。执行结果（成功或失败）会被反馈给下一轮的推理过程，形成闭环。

稳定性机制：如何避免“死循环”

让 LLM 控制图形用户界面（GUI）本质上是不稳定的。为了防止代理陷入混乱或死循环，droidclaw 内置了多层防御机制：

• 卡死检测 (Stuck Loop Detection)： 如果连续 3 步屏幕内容未发生变化，系统会自动向提示词中注入恢复策略，并根据之前的失败类型（是点击无效还是滑动无效）提供上下文建议。
• 重复操作追踪： 维护一个最近行动的滑动窗口。如果代理在短时间内多次点击同一坐标（例如超过 3 次），系统会强制其停止并尝试其他路径。
• 偏离行为纠正： 若代理在未与任何具体元素交互的情况下，频繁执行导航操作（如盲目滑动、返回或等待），系统会提示其采取更直接的行动。
• 视觉回退 (Visual Fallback)： 针对无障碍树无法获取的场景（如 WebView、Flutter 应用或游戏），系统会自动切换至截图模式，利用多模态模型基于图像坐标进行点击建议。
• 行动反馈闭环： 每一步操作的结果（成功/失败及错误信息）都会如实反馈给 LLM，使其知晓上一步是否有效，从而动态调整策略。
• 多轮记忆： 跨步骤维护完整的对话历史，确保 LLM 清楚已经尝试过哪些方法，避免重复造轮子。

部署指南

快速安装

一行命令即可完成环境准备（自动安装 bun 和 adb，克隆仓库并配置环境变量）：

curl -fsSL https://droidclaw.ai/install.sh | sh

手动安装与配置

如果你希望掌控每一个细节，可以按以下步骤操作：

前置要求：

• Bun： 必须使用 Bun 运行时（Node.js 不适用，因依赖 Bun.spawnSync 等特性）。
• ADB： Android Debug Bridge（含于 Android SDK Platform Tools）。
• 设备： 一台已开启 USB 调试的安卓手机。
• LLM： 任意大模型 API Key，或使用 Ollama 本地部署。

安装步骤：

# 1. 安装 ADB
# macOS
brew install android-platform-tools
# Linux
sudo apt install android-tools-adb
# Windows: 请前往 Android 开发者官网下载 Platform Tools

# 2. 安装 Bun
curl -fsSL https://bun.sh/install | bash

# 3. 克隆项目并安装依赖
git clone https://github.com/unitedbyai/droidclaw.git  
cd droidclaw
bun install
cp .env.example .env

配置大模型：

编辑 .env 文件。推荐使用 Groq（免费层级速度快）作为入门：

LLM_PROVIDER=groq
GROQ_API_KEY=gsk_your_key_here

或者使用 Ollama 实现完全本地化运行（无需联网，数据不出设备）：

ollama pull llama3.2
# .env 配置
LLM_PROVIDER=ollama
OLLAMA_MODEL=llama3.2

连接设备：

1. 进入手机 设置 → 关于手机，连续点击 版本号 7 次开启开发者选项。
2. 进入 设置 → 开发者选项，开启 USB 调试。
3. 通过 USB 连接电脑，在手机弹窗中点击“允许”。
4. 验证连接：adb devices 应显示你的设备序列号。

启动运行：

bun run src/kernel.ts
# 随后输入你的目标即可

三种核心模式：适配不同场景

droidclaw 提供了三种运行模式，分别对应从“即时探索”到“固定宏”的不同需求。

1. 交互模式：即兴发挥

适用于临时起意的任务。只需输入指令，代理会自行摸索路径。

bun run src/kernel.ts
# 输入：open settings and turn on dark mode

2. 工作流模式：AI 驱动的跨应用协作

通过 JSON 文件定义一系列子目标。LLM 负责在每个步骤中决定如何导航和操作，甚至可以在不同应用间切换。支持通过 formData 注入动态数据。

示例：天气查询并发送 WhatsApp

{
  "name": "weather to whatsapp",
  "steps": [
    {
      "app": "com.google.android.googlequicksearchbox",
      "goal": "search for chennai weather today"
    },
    {
      "goal": "share the result to whatsapp contact Sanju"
    }
  ]
}

示例：Slack 每日站会

{
  "name": "slack standup",
  "steps": [
    {
      "app": "com.Slack",
      "goal": "open #standup channel, type the message and send it",
      "formData": {
        "Message": "yesterday: api integration\ntoday: tests\nblockers: none"
      }
    }
  ]
}

3. 流程模式：确定性宏

适用于那些不需要 AI 思考、只需机械重复的任务。基于 YAML 编写，不调用 LLM，执行速度极快，类似于传统宏工具。

示例：发送固定 WhatsApp 消息

appId: com.whatsapp
name: Send WhatsApp Message
---
- launchApp
- wait: 2
- tap: "Contact Name"
- wait: 1
- tap: "Message"
- type: "hello from droidclaw"
- tap: "Send"
- done: "Message sent"