【免费下载】 DroidRun 使用与启动教程

2026-01-31 05:05:35作者：瞿蔚英Wynne

1. 项目介绍

DroidRun 是一个强大的框架，用于通过 LLM 代理控制 Android 设备。它允许用户使用自然语言命令自动化 Android 设备的交互。

特点

使用自然语言命令控制 Android 设备
支持多种 LLM 提供商（OpenAI、Anthropic、Gemini）
易用的 CLI
可扩展的 Python API 以实现自定义自动化
屏幕截图分析，用于对设备进行视觉理解

2. 项目快速启动

安装

方法一：从 PyPI 安装（推荐）

pip install droidrun

方法二：从源码安装

git clone https://github.com/droidrun/droidrun.git
cd droidrun
pip install -e .

准备工作

一个通过 USB 或 ADB over TCP/IP 连接的 Android 设备
安装并配置好 ADB（Android Debug Bridge）
在 Android 设备上安装 DroidRun Portal 应用
至少一个支持的 LLM 提供商的 API Key：OpenAI、Anthropic、Google Gemini

设置 ADB

安装 ADB 以便 DroidRun 与 Android 设备通信：

Windows：下载 Android SDK Platform Tools 并解压 ZIP 文件
macOS：brew install android-platform-tools
Linux：sudo apt install adb（Ubuntu/Debian）或 sudo pacman -S android-tools（Arch）

将 ADB 添加到系统环境变量 PATH 中：

Windows：将解压后的 platform-tools 文件夹路径添加到系统的 PATH 环境变量中
macOS/Linux：将以下内容添加到 ~/.bashrc 或 ~/.zshrc 中：

export PATH=$PATH:/path/to/platform-tools

验证 ADB 安装：

adb version

在 Android 设备上启用 USB 调试：

进入 设置 → 关于手机，连续点击 版本号 7 次以启用开发者选项
进入 设置 → 系统 → 开发者选项（位置可能因设备而异），启用 USB调试

设置

第 1 步：安装 DroidRun Portal 应用

DroidRun 需要在 Android 设备上安装 DroidRun Portal 应用：

从 DroidRun Portal 仓库下载 DroidRun Portal APK
使用 DroidRun 安装门户应用：

droidrun setup --path=/path/to/droidrun-portal.apk

或者，你可以使用 ADB 手动安装：

adb install -r /path/to/droidrun-portal.apk

第 2 步：设置 API 密钥

在当前工作目录下创建一个 .env 文件或设置环境变量：

# 选择至少一个基于你偏好的提供商
export OPENAI_API_KEY="your_openai_api_key_here"
export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export GEMINI_API_KEY="your_gemini_api_key_here"

从 .env 文件加载环境变量：

source .env

第 3 步：连接到 Android 设备

通过 USB 连接设备或设置无线 ADB：

# 列出已连接设备
droidrun devices

# 通过 Wi-Fi 连接到设备
droidrun connect 192.168.1.100

第 4 步：验证设置

验证设置是否正确：

# 应列出你的连接设备和显示门户状态
droidrun status

使用 CLI

DroidRun 的 CLI 设计为简单直观，有两种使用方式：

基础使用

# 格式：droidrun "任务描述" [选项]
droidrun "打开设置应用"

使用提供商选项

# 使用 OpenAI
droidrun "打开计算器应用" --provider openai --model gpt-4o-mini

# 使用 Anthropic
droidrun "检查电池电量" --provider anthropic --model claude-3-sonnet-20240229

# 使用 Gemini
droidrun "安装并打开 Instagram" --provider gemini --model gemini-2.0-flash

额外选项

# 指定特定设备
droidrun "打开 Chrome 并搜索天气" --device abc123

# 设置最大步骤数
droidrun "打开设置并启用暗模式" --steps 20

创建一个最小测试脚本

如果你想在 Python 代码中使用 DroidRun 而不是通过 CLI，可以创建一个最小测试脚本：

#!/usr/bin/env python3
import asyncio
import os
from droidrun.agent.react_agent import ReActAgent
from droidrun.agent.llm_reasoning import LLMReasoner
from dotenv import load_dotenv

# 从 .env 文件加载环境变量
load_dotenv()

async def main():
    # 创建一个 LLM 实例（选择你偏好的提供商）
    llm = LLMReasoner(
        llm_provider="gemini",
        model_name="gemini-2.0-flash",
        api_key=os.environ.get("GEMINI_API_KEY"),
        temperature=0.2
    )
    # 创建并运行代理
    agent = ReActAgent(
        task="打开设置应用并检查 Android 版本",
        llm=llm
    )
    steps = await agent.run()
    print(f"执行完成，共 {len(steps)} 步")

if __name__ == "__main__":
    asyncio.run(main())