关于 Ghost in the Droid
Ghost in the Droid 是一个开源 Python 框架,让任意 LLM Agent 通过 ADB 或 Appium/WebDriverAgent 控制真实的 Android 手机和 iPhone。它面向需要自动化移动应用、并希望复用技能的开发者和团队,并提供 62 个 MCP 工具。
主要功能
- 01通过 ADB 控制 Android 设备
- 02通过 WebDriverAgent 控制 iOS 设备
- 03实时屏幕串流与点击操作
- 04可复用的 YAML 与 Python 技能
- 05多设备任务队列与定时执行
适用场景
- 01让 Claude Code 等 MCP 客户端直接操作真实手机
- 02用固定技能重放已知的应用操作流程,无需调用 LLM
- 03在手机农场中批量运行移动应用自动化任务
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
Ghost in the Droid
召唤一只幽灵进入你的手机。
它看得见屏幕,会点击按钮,而且永不休眠。
▶ 在 YouTube 上观看带声音的完整高清版 · 下载 mp4
九个 Agent。九台真实设备。一只幽灵。(点击观看。)
一句话介绍
每个 AI Agent 都会思考。几乎没有哪个能操作手机。
Ghost 就是身体。 它为任何大模型 Agent 提供一台真实的 Android 手机或 iPhone:通过简洁的工具界面读取屏幕、点击、滑动和输入,还能从你桌上的一台设备扩展到整座手机农场。让 Claude Code、Codex、Antigravity、Cursor、你的 LangChain 应用,或运行在手机本身内部的模型连接到它,你的 Agent 就有了双手。
自带大脑,身体始终如一。MIT 许可,永远开源。
自由组合:Ghost 矩阵
Ghost 1.3 是唯一一个平台、大脑和驱动程序都可替换的 Android + iOS Agent 框架。每列选一个,它们都能组合使用。
| 选择平台 | 选择大脑 | 选择驱动程序 |
|---|---|---|
| Android,通过 USB ADB | Claude Code(使用 Max/Pro 订阅即可免费) | MCP 客户端(Claude Code、Codex、Antigravity、Cursor、Opencode) |
| Android,通过 Wi-Fi ADB | Anthropic API | LangChain 工具包 |
| Android,使用 Docker + KVM 模拟器池 | OpenRouter(任意模型,一个密钥) | LlamaIndex 工具规范 |
| iPhone,通过 Appium + WebDriverAgent | Ollama(完全本地运行) | Ghost CLI(ghost "book a table" --device pixel) |
| iPhone,通过 Tailscale + WebDriverAgent(无线) | vLLM(使用你自己的 GPU) | Web 仪表板,通过实时手机画面进行聊天 |
设备端 — llama.cpp(.gguf,任意量化版本)、MediaPipe(.task、Gemma 移动端模型包)、MLX(Apple Silicon,可选启用)。模型在手机内部运行,飞行模式下也能使用 | REST API(/docs OpenAPI) |
Docker + KVM 模拟器池仅支持 Android;iOS 使用 Apple 自带的模拟器和 Xcode 签名,这些功能原生支持 macOS。
无论接入什么,大脑背后的身体始终提供相同的 62 个 MCP 工具。每次模型发布更新,都能免费升级你的手机 Agent。
效果演示
九段演示,每项功能一段,均在真实设备上录制。点击任意视频即可查看完整 MP4。
功能介绍
用于通过一个 Agent 框架控制 Android 和 iOS 设备的开源 Python 框架。Android 通过 ADB 运行。iOS 通过 Appium XCUITest 和 WebDriverAgent 运行,以真实 iPhone 为目标路径,并使用模拟器进行开发和 CI。
为任意应用定义技能,从仪表板或 API 运行,并扩展到整个手机集群。
幽灵会帮你点按
- 通过 ADB 控制 Android:点按、滑动、输入、剪贴板、Shell、Intent 和隐身变体
- 通过 WebDriverAgent 控制 iOS:屏幕截图、无障碍树、点按、滑动、输入、启动应用、剪贴板、浏览器操作
- 实时手机屏幕流:Android MJPEG/WebRTC、iOS WDA MJPEG,并提供屏幕截图回退方案
- 在屏幕流上通过触摸进行交互式点按
- 多设备手机集群,配备每台设备专属的作业队列
为任意应用打造可复用技能
- 基于 YAML 的应用 UI 元素定义
- 使用
elements.yaml定义 Android 平台专属选择器,使用elements_ios.yaml定义 iOS 平台专属选择器 - 带前置条件检查的 Python 操作类
- 将多个操作串联起来的多步工作流
- 内置 TikTok 和 Play Store 技能
- iOS 浏览器/新闻演示技能和冒烟级 TikTok iOS 工作流
- Skill Hub:在社区注册表中浏览、搜索和安装技能
- 通过 CLI 安装:
android-agent skill install tiktok
教幽灵新把戏
- 基于 BFS 的应用自动探索器:发现每个屏幕和转换
- LLM 辅助的技能创建器:一边查看实时设备流,一边与 AI 聊天
- AI 识别 UI 元素并生成操作/工作流代码
扩展闹鬼规模
- 多设备手机集群,配备每台设备专属的作业队列
- Bot 运行器:对自动化作业进行排队、安排和监控
- 按设备运行集成测试,并录制 Android 屏幕或 iOS WDA MJPEG
平台支持
| 接入界面 | Android | iOS |
|---|---|---|
| 设备引用 | ADB 序列号,例如 emulator-5554 | ios:<udid> |
| 后端 | ADB + 可选的 Portal 配套应用 | Appium XCUITest + WebDriverAgent |
| 真实设备支持 | 支持 | 支持,需 Mac/Xcode/WDA 签名 |
| 模拟器支持 | Android 模拟器工具 | 通过 Appium/WDA 启动的 iOS 模拟器 |
| 实时流 | Portal WebRTC、MJPEG、屏幕捕获 | WDA MJPEG,或回退到屏幕截图轮询 |
| 屏幕树 | Android UIAutomator XML | 规范化的 XCTest 无障碍树 |
| 技能 | elements.yaml、Android 软件包 | elements_ios.yaml、iOS Bundle ID |
| 目前仅支持 Android | ADB Shell、Intent、无线 ADB、Play Store 助手、Portal 覆盖层 | 不支持,并提供稳定的平台错误信息 |
为什么这样构建
技能成本为 $0。思考需要消耗 Token。 Agent 不应该为了点按已经点过一千次的按钮而调用大模型。已知工作流会编译为技能:确定性的 YAML + Python 方案,可在几秒内重放,且不调用大模型。未知任务交给 AI,已知任务直接重放。
手机是最容易使用的沙盒。 给幽灵一台配有专属 SIM 卡和账户的旧 Android 手机,与自己的生活物理隔离。你已经知道如何设置手机。
默认不安装应用。 全新安装不会触碰 Android 设备上的任何内容:屏幕读取通过 uiautomator 完成,操作通过 adb shell input 完成,无需 Root,也不需要无障碍服务。想要更快?可选的 Portal 配套应用能让 UI 读取速度提升约 30 倍。想要保护隐私?设备端模式会在手机内运行整个流程,不会有任何内容离开手机。所有功能均需主动选择启用。
本地优先,云端可选。 服务和仪表板都运行在你的设备上。使用本地或设备端大脑时,屏幕截图绝不会离开你的网络。选择云端大脑后,提示词会像使用任何工具一样发送给对应的服务商。始终由你决定。
要求
- Python 3.10+
- Android:启用 USB 调试的 Android 手机,且
adb已加入 PATH(adb devices应能列出你的手机) - iOS:安装了 Xcode 的 macOS、Appium 2 + XCUITest 驱动,以及已信任的 iPhone 或已启动的模拟器
- Node.js 18+(用于前端开发服务器)
iOS 支持
Ghost 通过 Appium/WebDriverAgent 驱动 iPhone,并提供相同的工具
接口:ios:<udid> 设备引用会将 tap/swipe/type/screenshot 路由到 WDA,而
支持 iOS 的浏览器基础工具(open_url、read_news、extract_visible_text)
则可用于网页任务。仅限 Android 的工具(shell、launch_intent、Portal overlay)
会返回明确的平台错误,而不会静默失败。
iOS 默认不启用:设置 GITD_ENABLE_IOS=1(或在 .env 中设置 ios_platform_enabled=true)
即可启用。无线控制通过你的 Tailscale tailnet 进行,因此请将 tailnet 视为
信任边界。Appium/WDA
设置请参阅 docs/SETUP_IOS.md,要在 iPhone 本机运行模型,请参阅
on-device on iPhone。
快速开始
使用 uvx(或 pipx)即可零安装运行:
uvx ghost-in-the-droid doctor # green/red preflight: python, adb on PATH, devices, ports, LLM keys
uvx ghost-in-the-droid login # sign in with your Claude subscription, no API key needed
uvx ghost-in-the-droid up # server + dashboard at http://localhost:5055 (API docs at /docs)
当缺少某项内容(例如 adb 未加入 PATH)时,doctor 会打印包含修复提示的检查清单,而不是堆栈跟踪。更喜欢使用 pipx?运行 pipx install ghost-in-the-droid 即可获得 ghost-in-the-droid / android-agent 命令。
使用 Claude 订阅登录(无需 API 密钥)
如果你有 Claude Max/Pro 订阅,就不需要 API 密钥。android-agent login 会通过 claude CLI 自带的 Anthropic OAuth 流程为你登录,并将 Ghost 指向 claude-code 提供方:
android-agent login # opens Anthropic sign-in via the claude CLI
Ghost 从不处理或存储你的令牌;令牌由 claude CLI 管理,包括刷新。登录后,doctor 会显示绿色的 Claude subscription 检查项。若要改用 API 密钥,请设置 ANTHROPIC_API_KEY(或 OPENAI_API_KEY / OPENROUTER_API_KEY),并选择相应的提供方。
使用 Ollama 完全本地运行(无需密钥,无需云服务)
在 Phone Agent 选项卡中选择 Ollama。所有运行都在你的计算机上完成,需使用 Ollama:
brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull llama3.2:3b # 2GB, fast, good tool-use
从克隆的仓库开始(用于开发)
git clone https://github.com/ghost-in-the-droid/android-agent.git
cd android-agent
pip install -e ".[all]"
android-agent doctor # preflight
android-agent up # start server + dashboard on :5055
# Frontend (separate terminal)
cd frontend && npm install && npx vite --host 0.0.0.0 --port 6175
# Dashboard at http://localhost:6175
iOS 快速开始
iOS 支持需要 Mac,因为 Appium 使用 Xcode 的 XCUITest/WebDriverAgent 技术栈。真机 iPhone 还需要进行信任验证、启用开发者模式、按提示授予 UI Automation 权限,并使用 Apple 开发团队对 WDA 进行签名。
# 1. Install and run Appium XCUITest
npm install -g appium
appium driver install xcuitest
appium --base-path /
# 2. Find your iPhone or booted simulator UDID
xcrun xctrace list devices
xcrun simctl list devices booted
# 3. Configure the backend for iOS
export IOS_DEVICE_UDID="<udid>"
export IOS_APPIUM_URL="http://127.0.0.1:4723"
export IOS_BUNDLE_ID="com.google.chrome.ios" # or com.apple.mobilesafari
export IOS_MJPEG_SERVER_PORT="9100" # use unique ports per iOS device
# 4. Run a product-path smoke workflow
uv run python scripts/ios_chrome_news_smoke.py \
--device "ios:<udid>" \
--bundle-id "$IOS_BUNDLE_ID" \
--url https://text.npr.org/ \
--max-headlines 5 \
--max-articles 3 \
--fix-health \
--out-dir data/ios_chrome_news_smoke
有关真机完整签名、模拟器、WDA MJPEG、健康状态恢复、调度器和 MCP 设置的详细信息,请参阅 docs/SETUP_IOS.md。
环境变量
将 .env.example 复制为 .env(如果提供了该文件),或在项目根目录创建 .env 文件。服务器通过 Pydantic Settings 读取配置。可选变量包括:
| 变量 | 用途 |
|---|---|
OPENAI_API_KEY | 大模型功能(Skill Creator、Agent Chat) |
ANTHROPIC_API_KEY | 备用大模型提供方 |
OPENROUTER_API_KEY | OpenRouter 大模型提供方 |
DEFAULT_DEVICE | ADB 序列号(为空时自动检测) |
IOS_DEVICE_UDID | iPhone 或模拟器 UDID;设备地址格式为 ios:<udid> |
IOS_APPIUM_URL | Appium 服务 URL,默认为 http://127.0.0.1:4723 |
IOS_BUNDLE_ID | 默认 iOS 应用/浏览器 bundle,例如 com.google.chrome.ios 或 com.apple.mobilesafari |
IOS_DEVICES_JSON | 多部手机/模拟器的逐设备 iOS 配置,包含 WDA 端口、bundle ID 和 MJPEG 端口 |
IOS_MJPEG_SERVER_PORT | WDA MJPEG 流端口;每台 iOS 设备使用一个唯一端口 |
为任意 AI Agent 装上移动设备的身体(MCP)
Ghost 附带一个 MCP 服务,提供 62 个工具,用于控制真实设备。任何兼容 MCP 的客户端都可以使用这些工具。Android 序列号会使用 Android 实现;ios:<udid> 引用会在支持的情况下路由到 iOS 后端,对于仅支持 Android 的工具,则会返回稳定的“不支持该平台”错误。只需一条命令即可完成接入:
# Claude Code (same shape for Codex, Cursor, VS Code Copilot, Windsurf)
claude mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp
uvx 会安装软件包、构建隔离环境并运行服务。无需克隆仓库,也无需创建 venv。
其他客户端(Codex、Claude Desktop、Cursor、VS Code、Windsurf)
# Codex (OpenAI)
codex mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp
Claude Desktop(claude_desktop_config.json)、Cursor(.cursor/mcp.json)、Windsurf(mcp_config.json):
{
"mcpServers": {
"android-agent": {
"command": "uvx",
"args": ["--from", "ghost-in-the-droid", "android-agent-mcp"]
}
}
}
VS Code Copilot(.vscode/mcp.json)在 "servers" 键下使用相同的配置块。克隆仓库的贡献者会获得一份可直接使用的 .mcp.json,首次启动 claude 时,全部 62 个工具即可使用。
62 个工具,按类别划分:
| 类别 | Ghost 可以做什么 |
|---|---|
| 查看 | screenshot、get_elements、get_screen_tree、get_screen_xml、screenshot_annotated、screenshot_cropped |
| 触控 | tap、tap_element、swipe、long_press、type_text、type_unicode、press_back、press_home、press_key |
| 应用 | launch_app、search_apps、list_apps、launch_intent、force_stop、list_packages |
| 理解 | get_phone_state、classify_screen、find_on_screen、ocr_screen、ocr_region、extract_visible_text |
| 浏览器 / iOS | open_url、browser_back、get_current_url、read_news、extract_articles、wait_for_text |
| 设备 | list_devices、clipboard_get、clipboard_set、get_notifications、open_notifications、toggle_overlay、device_health |
| 技能 | list_skills、run_workflow、run_action、create_skill、explore_app |
| 批处理 | run_flow / chain:一次调用即可在服务端运行完整的多步流程,将 N 次往返压缩为 1 次 |
| 诊断 | list_crashes、get_crash、web_search、屏幕录制、相机 + TTS |
toggle_overlay、launch_intent、Android shell 辅助工具、无线 ADB 和 Play Store 辅助工具仍仅支持 Android,在 iOS 上会返回稳定的平台错误。
在手机内运行大脑
1.3 版新增:模型可以运行在设备上。Ghost 配套应用内置了真实的推理引擎,因此手机既是身体,也是大脑。开启飞行模式后,Agent 仍能工作,所有数据都不会离开设备。
| 平台 | 引擎 | 模型格式 | 最适用场景 |
|---|---|---|---|
| Android | llama.cpp(JNI) | .gguf | 任意 GGUF:Gemma、Llama、Mistral、Qwen、DeepSeek |
| Android | MediaPipe | .task | 小型 Gemma 模型,Android 集成速度最快 |
| iPhone | llama.cpp(Metal) | .gguf | 与 Android 使用相同的 GGUF,Qwen2.5 1.5B 可在 Metal 上运行 |
| iPhone | MLX | Apple Silicon | 在新款芯片上实现更快的解码,可选择启用 |
在 iPhone 上,Qwen2.5 1.5B 通过 Metal 上的 llama.cpp 运行,并操控手机自身的 UI;还可选择启用 MLX 引擎,以便在 Apple Silicon 上加快解码速度。小型模型通过语法约束解码确保输出可靠,从而始终能正确解析工具调用。详情请参阅设备端 LLM 页面。
Skill Hub 命令行工具
android-agent skill search tiktok # search the public registry
android-agent skill install tiktok # install a skill
android-agent skill install github.com/someone/their-skill
android-agent skill list # what is installed
android-agent skill update tiktok # update a skill
android-agent skill validate ./my-skill/ # check before publishing
技能注册表位于本仓库的 registry/ 中。系统每晚会自动发现标记为 android-agent-skill 的仓库中的社区技能。
教幽灵使用新应用
创建技能有两种方式:
社区技能(你自己的仓库):创建一个包含 skill.yaml、elements.yaml、操作和工作流的仓库,为其添加 android-agent-skill 标签,它就会自动出现在 Skill Hub 中(每晚抓取一次)。
官方技能(向此仓库提交 PR):先将其构建并测试为社区技能,然后提交 PR,将其添加到 registry/。CI 会进行验证,维护者会审核,之后它就会获得“Official”徽章。
每项技能都需要:
skill.yaml:元数据(名称、版本、应用包名或 iOS bundle ID、支持的平台、操作、工作流)elements.yaml:Android UI 元素资源 ID 和描述elements_ios.yaml:可选的 iOS 选择器,用于 XCTest 无障碍树actions/:继承Action并实现precondition()和execute()的 Python 类workflows/:继承Workflow并实现steps()的 Python 类
想让 AI 来做?Skill Creator 会监控实时设备流,并在你讲述时生成操作和工作流代码。完整指南请参阅 CONTRIBUTING.md。
控制面板
本地优先的控制室,地址为 http://localhost:5055(开发环境中为 :6175)。提供 WebRTC 和 MJPEG 实时流、屏幕点按、跟踪,以及下表中的所有标签页。
| 标签页 | 功能 |
|---|---|
| Phone Agent | 设备实时流(MJPEG/WebRTC)、屏幕点按/滑动、多设备视图 |
| Scheduler | 类 Cron 的作业调度与队列管理 |
| Skill Hub | 浏览已安装的技能、运行操作和工作流、导出/删除 |
| Skill Creator | 借助 LLM 的技能构建器,支持设备实时流 |
| Skill Miner | 自动应用探索器:通过 BFS 发现状态并截图 |
| Manual Run | 启动/停止机器人作业、队列管理、日志 |
| Tests | 按设备运行测试并回放屏幕录制 |
| Emulators | 创建、启动、创建快照并管理 Android 模拟器 |
| Tracing | 每轮跟踪、令牌统计、工具调用可见性 |
架构
android-agent/
run.py # Uvicorn entry point on :5055
gitd/
app.py # FastAPI app factory + plugin hook
models/ schemas/ # SQLAlchemy 2.0 ORM + Pydantic v2
routers/ services/ # Route handlers + business logic
skills/ # Skill packages (tiktok, play_store, safari [iOS], tiktok_ios)
bots/common/adb.py # Android Device class: tap, swipe, dump tree, wait_for
bots/common/ios.py # iOS Device class: Appium/WDA session, UI tree, gestures
mcp_server.py # MCP server: 62 tools for any LLM agent
frontend/ # Vue 3 + Vite + TypeScript + Tailwind
portal/ # Kotlin companion app (WebRTC, on-device inference)
site/ # Docs site (Astro + Starlight)
工作流程: :5055 上的 FastAPI 后端提供设备控制、技能、机器人、调度和流媒体功能。Vue SPA 通过 /api/* 与其通信。技能定义各应用的交互方式(元素 + 操作 + 工作流)。设备后端根据引用路由:纯序列号使用 bots/common/adb.py,ios:<udid> 引用使用 bots/common/ios.py 和 Appium/WDA。状态通过 SQLAlchemy 2.0 和 Alembic 存储在 SQLite 中。
基准测试(抢先预览)
早期结果,完整的方法说明仍在编写中:由 Claude Code 驱动时,Ghost 在未经修改的上游测试框架上完成了 AndroidWorld 中的 116 项任务中的 115 项(99.1%)。请将其视为预览结果,而非可引用的数据。详细说明和执行轨迹即将发布。请关注 releases。
技术栈
| 层 | 技术 |
|---|---|
| 后端 | FastAPI、Uvicorn、Python 3.10+ |
| 数据 | SQLAlchemy 2.0、Alembic、Pydantic v2、SQLite(WAL) |
| 前端 | Vue 3、TypeScript、Vite、Tailwind CSS 4 |
| 设备控制 | Android 使用 ADB;iOS 使用 Appium XCUITest/WebDriverAgent |
| 流媒体 | Android 通过 Portal 提供 MJPEG/WebRTC;iOS 使用 WDA MJPEG,并在必要时回退到截图 |
| 设备端 | llama.cpp、MediaPipe(Android);iOS 使用 Metal 上的 llama.cpp、MLX |
| 质量 | Ruff、pytest、Playwright |
运行测试
大多数测试都是单元/API 测试,无需连接实时设备即可运行。实时 Android 和 iOS 集成测试需要相应的设备环境。
# Run all tests on a specific device
DEVICE=<serial> python3 -m pytest tests/ -v --tb=short
运行 iOS 实时冒烟测试:
IOS_LIVE_NEWS_TEST=1 \
IOS_DEVICE_UDID="<udid>" \
IOS_APPIUM_URL="http://127.0.0.1:4723" \
IOS_BUNDLE_ID="com.google.chrome.ios" \
uv run --extra test python -m pytest tests/test_browser_news.py::test_live_ios_chrome_news_workflow
使用 adb devices 获取 Android 设备序列号。
数据库迁移
项目使用 Alembic 进行架构迁移:
alembic revision --autogenerate -m "add new_field to my_table" # after editing a model
alembic upgrade head # apply pending
alembic downgrade -1 # rollback one
贡献
每项技能都会让 ghost 变得更强大。有关添加应用技能(影响最大)、编写操作和工作流、后端架构及 PR 流程,请参阅 CONTRIBUTING.md。欢迎在 Skill Hub 加入社区。
许可证
MIT。ghost 是免费的。ghost 是开源的。ghost 属于你。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。








