Android 薄型インターフェース
Android ホストはすべての操作を WebSocket 経由で行うわけではありません。インスタンスの開始・停止、状態監視、アップデート時の一時サスペンドなどの制御系操作は、プレフィックス /android/ を持つ専用の軽量 HTTP API を経由します。
有効化の条件
本ルーティングは以下の環境変数が設定されている場合のみ登録されます：
AZURPILOT_ANDROID=1デスクトップ版の環境ではこれらのエンドポイントは登録されません。
認証方式
GET /android/status HTTP/1.1
X-AzurPilot-Android-Token: <token>以下の2つの条件を同時に満たす必要があります：
- リクエスト送信元がローカルループバックアドレス（
127.0.0.1または::1）であること。 - 送信されたヘッダー値が Runtime の保持するトークンと定数時間比較で完全一致すること。
条件を満たさない場合は 403 {"error": "loopback only"} が返却されます。
25548 ポートを外部公開してこの保護に頼らないでください
薄型インターフェースのセキュリティモデルは「完全なローカル自機限定」を前提としています。ポートフォワーディング等で外部に露出した場合、残る防壁は WebSocket のパスワード認証のみとなります。
インスタンス指定パラメータ
インスタンスを対象とするすべての API はクエリパラメータを受け付けます：
?config=<インスタンス名>パラメータを省略した場合の挙動：
- 実行中のインスタンスが存在する場合は、最初のインスタンスが対象となります。
- 存在しない場合は
alasが使用されます。
指定したインスタンスが存在しない場合は 400 エラーとなります。
エンドポイント一覧
| メソッド | パス | 用途 |
|---|---|---|
| GET | /android/status | 実行状態の確認 |
| GET | /android/configs | インスタンス名の一覧 |
| GET | /android/logs?tail=N | プレーンテキストログ取得（N ≤ 2000） |
| POST | /android/start | インスタンスの起動 |
| POST | /android/stop | インスタンスの停止 |
| POST | /android/tool/start?name=<tool> | ユーティリティタスクの開始 |
| POST | /android/tool/stop | ユーティリティタスクの停止 |
| GET | /android/update/status | ホットアップデート状態の確認 |
| POST | /android/update/apply | ホットアップデートの適用 |
| POST | /android/update/suspend | 全体パッケージ更新に向けた全インスタンスのサスペンド |
status
{
"runner_alive": true,
"pid": 12345,
"config": "ap",
"gui_alive": true,
"tool_alive": false,
"tool_name": null,
"log_lines": 128
}| フィールド | 意味 |
|---|---|
runner_alive | インスタンスが動作中であり、ツールタスクではない状態 |
pid | スケジューラーのプロセス ID |
config | 現在のインスタンス名 |
gui_alive | バックエンドプロセスの生存（現在の実装では常に true） |
tool_alive / tool_name | ユーティリティタスクの実行状態 |
log_lines | ログのエントリ数 |
start / stop
start：他に実行中のインスタンスがあれば先に停止させ、その後にターゲットのインスタンスを起動します。すでに同一タスクを実行中である場合は現在の状態をそのまま返します。stop：対象のインスタンスのみを停止します。- どちらの操作も、事前に旧版ホストプロセスがデバイスを占有していないかをチェックします（
22300および22400ポートへのプローブ）。占有されている場合はDEVICE_BUSYを返し、旧版タスクの停止を促します。
tool/start
サポートされているユーティリティタスク：
name | 対応タスク |
|---|---|
daemon | Daemon（半自動タップ補助） |
event_story | EventStory（イベントストーリー自動再生） |
未定義の名前を指定した場合は 400 エラーとなります。ツールタスクは同時に1つのみ実行可能です。
logs
text/plain 形式で1行ずつ返却されます（デフォルト80行）：
GET /android/logs?config=ap&tail=200update/suspend
アプリ全体パッケージの更新前に呼び出されます。実行動作：
- 実行中のすべてのスケジューラーおよびツールタスクを列挙。
- インスタンス名を
config/reloadalasに記録。 - すべてのプロセスをグレースフルに停止。
{"ok": true, "suspended": ["ap", "ap-2"]}を返却。
次回 WebUI 起動時に restart_processes() がこのファイルを読み込み、サスペンドされていたインスタンスを自動復帰させます。
通常の停止処理として suspend を使用しないでください
この API は再開リストを生成します。手動で呼び出した後に WebUI を再起動しなかった場合、インスタンスは停止したままとなります。
エラーハンドリング
| ステータスコード | 発生シナリオ |
|---|---|
| 400 | インスタンスが存在しない、未知のツール名、不正な引数 |
| 403 | 非ループバックリクエスト、または token の不一致 |
| 404 | エンドポイントが存在しない |
エラーレスポンス例：
{ "error": "DEVICE_BUSY" }エラーメッセージには具体的な原因（他のインスタンスが実行中、旧版プロセスが残存している等）が記載されています。
WebSocket との役割分担
| 操作内容 | 使用するプロトコル |
|---|---|
| 設定の読み書き、タスクパラメータの更新 | WebSocket |
| ログおよび統計ストリームの購読 | WebSocket |
| インスタンスの起動・停止、状態ポーリング | HTTP 薄型インターフェース |
| ホットアップデートの実行 | HTTP 薄型インターフェース |
Android ホストは HTTP を「電源スイッチ」として、WebSocket を「データプレーン」として使い分けます。これにより、万が一 WebSocket が切断された場合でも、ホストは HTTP 経由でインスタンスを安全に強制停止できます。