Droidline

コードから実機の Android スマートフォンを自動化できます。
アプリのテスト、繰り返し作業のスクリプト化、複数台のスマートフォンの運用、AI エージェントによる操作が可能です。
Python、Node.js、シェル、HTTP に対応。ADB、USB ケーブル、root は不要です。

ウェブサイト · ドキュメント · ダウンロード · スポンサー · クイックスタート · 対応言語 · ガイド

English · 한국어 · 简体中文

ADB もケーブルも不要 スマートフォンにアプリを1つインストールし、権限を有効にして、QRコードでペアリングします。開発者向けオプション、USB デバッグ、root は不要です。

どこでも同じコマンド touch は Python、Node.js、CLI、HTTP、MCP ツールのいずれでも touch です。すべて1つの仕様から生成されています。

どこにあるスマートフォンでも スマートフォンから PC に接続するため、同じ Wi-Fi 上でも、トンネルや自分で運用するリレーを介したモバイルデータ通信でも動作します。すべての通信はエンドツーエンドで暗号化されます。

どのような用途に使われていますか

• 自分のアプリのテスト。実機で、テキストメッセージに届いたコードを使うログインなど、他のアプリをまたぐフローもテストできます。
• 複数台のスマートフォンの運用。それぞれ独自のネットワークやプロキシを使い、同じルーチンを毎日実行できます。
• AI エージェントに操作を任せる：MCP を通じて、Claude、ChatGPT、Cursor などのエージェントがスマートフォンの画面を確認し、操作できます。
• 個人的な小規模の自動化。夜間に Wi-Fi をオフにしたり、アプリから1時間ごとに値を取得したりできます。

Droidline が使用するのは、通常のアプリが取得できる権限のみです。そのため、一部できないことがあります。詳しくはできないことをご覧ください。

動作を見る

_{同じデモをブラウザーで試し、シミュレートされた画面上の要素を選択できます。droidline.devをご覧ください。}

## クイックスタート

Windows、macOS、Linux のいずれかを搭載した PC と、Android 9 以降を搭載した Android スマートフォンが必要です。初回の試用時は、両方を同じ Wi-Fi に接続してください。インストールガイドでは、スクリーンショット付きで各手順を説明しています。

1. PC でサーバーを起動します。 お使いのシステム用の droidline アーカイブをリリースからダウンロードし、droidline を PATH に追加して起動します。そのまま起動しておいてください。

   droidline serve
   

2. スマートフォンにアプリをインストールします。 同じリリースページから droidline-agent.apk をダウンロードして開きます。アプリの Setup タブで、アクセシビリティサービス、Droidline キーボード、通知、バッテリーの最適化の対象外を有効にします。Android 13 以降では、先にアプリの 制限付き設定 を許可してください。アプリに許可する場所が表示されます。

3. ペアリングします。 PC で次のコマンドを実行し、アプリの Pair タブで QR コードをスキャンします。

   droidline pair
   

   カメラが使えない場合は、アプリで Pair on this Wi-Fi をタップし、表示された6桁のコードを入力します：droidline pair 482913。

4. コマンドを送信します。

   droidline launch com.android.settings
   droidline touch text "Network & internet"
   

スマートフォンが手元にない場合は、すべてのリリースに含まれる droidline-fakephone で、小さなデモアプリを使ってスマートフォンをシミュレートできます。最初のスクリプトのチュートリアルでは、このアプリを使ってログインスクリプトを完成させます。

お使いの言語から利用する

すべてのインターフェースは localhost:8780 の droidline serve と通信し、同じコマンド名を使用します。

Python（pip install droidline、Python 3.9 以降）

from droidline import connect

d = connect()                                  # the phone paired with this PC
d.launch("dev.droidline.demo")
if d.exists("text", "Close ad"):               # conditions never wait and never fail
    d.touch("text", "Close ad")
d.input("id", "email", "knife")                # waits up to 10 s for the element
d.touch("text", "Log in")
print(d.get_text("id", "greeting"))

Node.js と TypeScript（npm install droidline、Node.js 18 以降）

import { connect } from "droidline";

const d = await connect();
await d.launch("dev.droidline.demo");
await d.input("id", "email", "knife");
await d.touch("text", "Log in", { timeout: 15 });
console.log(await d.getText("id", "greeting"));

C# と .NET（dotnet add package Droidline、.NET 8 以降または .NET Framework 4.6.2 以降）

using Droidline;

await using var d = await DroidlineClient.ConnectAsync();
await d.LaunchAsync("dev.droidline.demo");
await d.InputAsync("id", "email", "knife");
await d.TouchAsync("text", "Log in", timeout: 15);
Console.WriteLine(await d.GetTextAsync("id", "greeting"));

コマンドライン（サーバーに同梱）

droidline touch text "Log in"
droidline which text="Log in" id=main_tab --timeout 15
droidline screenshot shot.png

HTTP（あらゆる言語、あらゆるツール）

curl -s -X POST localhost:8780/devices/_/touch \
  -H 'content-type: application/json' -d '{"by":"text","value":"Log in"}'

MCP 経由の AI エージェント（Claude、Cursor、VS Code など）

{ "mcpServers": { "droidline": { "command": "droidline", "args": ["mcp"] } } }

Claude Code を使う場合：claude mcp add droidline -- droidline mcp。Claude Desktop では、リリースから droidline.mcpb を開く方法もあります。このファイルには独自の droidline が含まれています。また、MCP Registry に io.github.KnifeLemon/droidline として掲載されています。エージェントが利用できるツールを減らすには、引数に --tools dump,screenshot,touch または --read-only を追加してください。詳しくはエージェントが利用できる範囲を制限するをご覧ください。ほかの言語からは TCP ソケットを開き、コマンドごとに JSON を1行送信できます。Go、Java、PHP についてはその他の言語をご覧ください。

機能

• ピクセルではなく、要素を選択します。 dump() は、すべての要素について text、id、desc を含むツリーとして画面を返します。コマンドにはフィールドと値を渡します：touch("id", "login")。要素をクリックできない場合、Droidline は自動的に親要素または要素の境界の中央をタップします。
• 待機機能が組み込まれています。 touch、input、wait は、デフォルトで 10 秒間、対象の要素が現れるのを待ちます。exists、checked、which などの条件は即座に結果を返し、要素が見つからなくても例外を発生させません。
• 明確なエラー。 すべての失敗にはコード、英語・韓国語・中国語のメッセージ、再試行が有効かどうかを示すフラグが含まれます：NOT_FOUND: Could not find text 'Log in' within 10s. Current screen: com.example / .MainActivity。
• スマートフォンをまとめて管理。 1 台の PC から複数のスマートフォンを操作できます。同じスマートフォンへのコマンドは順番に実行され、異なるスマートフォンへのコマンドは並列実行されます。各スマートフォンには任意の名前を付けられます。
• アプリごとのプロキシ。 ルート化せずに、ローカル VPN を使って選択したアプリを socks5 または http の上流プロキシ経由で通信させられます。スマートフォンごとに上流プロキシを 1 つ設定できます。
• PC への通知。 通知を 1 件待つ、すべての通知に反応する、返信する、開く、閉じる、または署名付き Webhook に転送できます。
• 新しいモバイル IP アドレス。 cuts_network を指定した batch は、スマートフォンがオフラインの間も処理を続けるため、機内モードのオン、待機、オフを 1 回の呼び出しで実行できます。intent は最初に設定ページを開きます。手順についてはレシピをご覧ください。
• 同じ処理は二度実行されません。 モバイルデータ通信が切断されたスマートフォンは、中断した箇所から処理を再開します。実行中に通信が切断されたコマンドには、再実行せず、スマートフォンのキャッシュから応答します。
• 安定したセレクター。 条件を組み合わせたり、近くの要素を使って要素を指定したりできます：touch({"class": "android.widget.Switch", "row": {"text": "Wi-Fi"}})。find はクリックしたり内部を検索したりできる要素を返し、wait_idle は画面の変化が止まるまで待機します。
• 任意のツールは起動するまで無効です。 droidline inspect は画面とその要素を表示し、コード付きのセレクターを提案し、スマートフォンの操作中にスクリプトを記録します。droidline webdriver を使うと、Appium のクライアントやスクリプトからスマートフォンを操作できます。また、pytest プラグイン、スクリプト間でスマートフォンを共有するためのリース、要素のない画面向けの画像・テキストマッチング機能もあります。
• アプリ、エラーメッセージ、ドキュメントは英語、韓国語、簡体字中国語に対応しています。

スクリーンショット

セットアップ：各権限と、その設定画面を開くボタン	ペアリング：QR コードをスキャンするか、6 桁のコードを使用	ステータス：接続、経路、権限

## どこからでもスマートフォンに接続

接続は常にスマートフォン側から開始するため、ポートを開く必要はありません。ネットワークに合った接続方法を選んでください。スマートフォンは順番に試し、可能な場合は Wi-Fi に戻ります。

接続方法	必要なもの	仕組み
同じ Wi-Fi	なし	スマートフォンが UDP ブロードキャストで PC を見つけ、直接接続します。
ポートフォワード	ポートを 1 つ転送	スマートフォンは TLS 経由で公開アドレスに接続し、PC の証明書をピン留めします。
トンネル	cloudflared、ngrok など	PC がトンネルを開いたままにし、スマートフォンはトンネルのアドレス経由で接続します。
自分のリレー	Cloudflare Workers または VPS	PC とスマートフォンが、デプロイしたリレーにそれぞれ外向きに接続します。リレーは内容を読み取れない行を転送します。

2 行のハンドシェイク後は、PC とスマートフォンだけが保持する鍵（P-256 と AES-256-GCM）ですべての行が暗号化されるため、トンネルやリレーを通るのは暗号文のみです。リモート接続ガイドでは、それぞれの方法を順を追って説明しています。

できないこと

Droidline は通常のアプリが取得できる権限のみを使用するため、実行できないこともあります。始める前に確認しておきましょう。

• アプリが公開していない別のアプリの画面を開くことはできません。launch は代わりにスタート画面を開きます。
• PIN、パターン、パスワードで保護されたロック画面を解除することはできません。
• アプリを強制停止したり、データを消去したり、ネットワークを切り替えたりする単一のコマンドはありません。設定画面はスマートフォンのメーカー、Android のバージョン、言語によって異なるため、レシピではボタンを押して操作します。スマートフォンに合わせてラベルを調整する必要がある場合があります。オプションのデバイスオーナーモードでは、clear_data でアプリのデータを直接消去できます。
• ゲームや一部の独自描画アプリでは、要素が公開されません。その場合は座標を指定した tap と color(x, y) を使用してください。
• Android 15 以降では、通知内のワンタイムコードがアプリから見えないようになっています。コードが届いたことは確認できますが、コードはアプリ内で読む必要があります。

全項目の一覧では、それぞれについて説明しています。

ドキュメント

目的	参照先
すべてを順を追ってインストールする	インストール
スマートフォンなしで最初のスクリプトを書く	最初のスクリプト
使用する言語を選ぶ	Python · Node.js · CLI · HTTP · AI エージェント
画面上の適切な要素を見つける	要素の検索
アプリ、リンク、設定画面を開く、またはインストール済みの項目を一覧表示する	アプリ
要素を指し示す、またはスクリプトを記録する	インスペクターとレコーダー
Appium スクリプトを実行する	Appium と WebDriver
pytest または Node.js でテストする	テストフレームワーク
動作するパターンを参考にする	レシピ
コマンドを調べる	コマンドリファレンス
モバイルデータ通信でスマートフォンに接続する	リモートスマートフォン
動作しない問題を解決する	トラブルシューティング
通信フォーマットを理解する	spec/PROTOCOL.md

ソースからビルドする

必要なもの：Go 1.26 以降、Node.js 22、Python 3.9 以降。アプリには、Android SDK と JDK 17 以降が必要です（Android Studio に同梱されている JDK も使用できます）。

git clone https://github.com/KnifeLemon/Droidline.git
cd Droidline
go build ./server/cmd/...              # droidline, droidline-relay, droidline-fakephone
go test ./spec/ ./server/...
node scripts/gen.mjs --check           # SDK methods match spec/commands.json
cd sdk/python && python -m pytest
cd sdk/node && npm ci && npm test
dotnet test sdk/dotnet
cd agent && ./gradlew assembleDebug testDebugUnitTest

scripts/integration.sh はサーバー、シミュレートされたスマートフォン、両方の SDK デモをまとめて実行します。CI でも同じ処理を行います。

パス	内容
spec/	commands.json（3 言語すべての全コマンド）、PROTOCOL.md、暗号化のテストベクトル
server/	Go：droidline（サーバー、CLI、MCP）、droidline-relay、droidline-fakephone
agent/	Kotlin 製の Android アプリ
sdk/python、sdk/node、sdk/dotnet	仕様から生成された公式 SDK と、薄いクライアント
relay/worker	Cloudflare Workers 向けのリレー
examples/	シミュレートされたスマートフォンで実行するデモスクリプト

コントリビュート

プルリクエストを歓迎します。CONTRIBUTING.md では、仕様、ジェネレーター、テストがどのように連携するかを説明しています。今もっとも役立つコントリビュートは、実機からの報告です。メーカーと Android のバージョン、そして強制停止、データの消去、ネットワークの切り替えに関する 設定手順 が、その機種のラベルで機能するかを教えてください。Droidline によってタップ操作を減らせたら、ほかの人が見つけやすくなるよう ⭐ を付けていただけると助かります。

ステータス

バージョン 0.1 です。サーバー、CLI、MCP アダプター、リレー、両方の SDK は、スマートフォンシミュレーターを使ったテストに合格しています。また、アプリは単体テストに合格し、Android 13 エミュレーターで動作します。次のステップは、さまざまなメーカーのスマートフォンでテストすることです。docs/STATUS.md には、検証済みの内容とその方法が詳しく記載されています。

セキュリティとプライバシー

ペアリングによって、スマートフォンを操作できるユーザーが決まります。ハンドシェイク以降の通信はすべてエンドツーエンドで暗号化されます。セキュリティ上の問題は、SECURITY.md の説明に従って非公開で報告してください。

Droidline は使用状況データを収集せず、テレメトリーも送信しません。サーバーはご自身のマシンで待ち受けます。アプリが通信するのは、ペアリングした PC と、新しいリリースを確認するために 1 日 1 回接続する GitHub だけです。Droidline は、ご自身が所有する、または自動化する権限のあるスマートフォンとアカウントでご利用ください。用途については利用規約をご確認ください。

ライセンス

MIT です。LICENSE をご覧ください。