---
title: Android 薄型インターフェース
description: Android ホストと Runtime 間の軽量 HTTP 連携仕様：状態確認、インスタンス制御、ログ取得、ツールタスク、更新時の一時停止。
updated: 2026-10-20
---

# Android 薄型インターフェース

Android ホストはすべての操作を WebSocket 経由で行うわけではありません。インスタンスの開始・停止、状態監視、アップデート時の一時サスペンドなどの制御系操作は、プレフィックス `/android/` を持つ専用の軽量 HTTP API を経由します。

## <DocIcon name="clipboard" /> 有効化の条件

本ルーティングは以下の環境変数が設定されている場合のみ登録されます：

```bash
AZURPILOT_ANDROID=1
```

デスクトップ版の環境ではこれらのエンドポイントは登録されません。

## <DocIcon name="key" /> 認証方式

```http
GET /android/status HTTP/1.1
X-AzurPilot-Android-Token: <token>
```

以下の2つの条件を同時に満たす必要があります：

1. リクエスト送信元がローカルループバックアドレス（`127.0.0.1` または `::1`）であること。
2. 送信されたヘッダー値が Runtime の保持するトークンと定数時間比較で完全一致すること。

条件を満たさない場合は `403 {"error": "loopback only"}` が返却されます。

::: danger 25548 ポートを外部公開してこの保護に頼らないでください
薄型インターフェースのセキュリティモデルは「完全なローカル自機限定」を前提としています。ポートフォワーディング等で外部に露出した場合、残る防壁は WebSocket のパスワード認証のみとなります。
:::

## <DocIcon name="settings" /> インスタンス指定パラメータ

インスタンスを対象とするすべての API はクエリパラメータを受け付けます：

```text
?config=<インスタンス名>
```

パラメータを省略した場合の挙動：

- 実行中のインスタンスが存在する場合は、最初のインスタンスが対象となります。
- 存在しない場合は `alas` が使用されます。

指定したインスタンスが存在しない場合は 400 エラーとなります。

## <DocIcon name="plug" /> エンドポイント一覧

| メソッド | パス | 用途 |
| --- | --- | --- |
| 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

```json
{
  "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行）：

```text
GET /android/logs?config=ap&tail=200
```

### update/suspend

アプリ全体パッケージの更新前に呼び出されます。実行動作：

1. 実行中のすべてのスケジューラーおよびツールタスクを列挙。
2. インスタンス名を `config/reloadalas` に記録。
3. すべてのプロセスをグレースフルに停止。
4. `{"ok": true, "suspended": ["ap", "ap-2"]}` を返却。

次回 WebUI 起動時に `restart_processes()` がこのファイルを読み込み、サスペンドされていたインスタンスを自動復帰させます。

::: warning 通常の停止処理として suspend を使用しないでください
この API は再開リストを生成します。手動で呼び出した後に WebUI を再起動しなかった場合、インスタンスは停止したままとなります。
:::

## <DocIcon name="circle-alert" /> エラーハンドリング

| ステータスコード | 発生シナリオ |
| --- | --- |
| 400 | インスタンスが存在しない、未知のツール名、不正な引数 |
| 403 | 非ループバックリクエスト、または token の不一致 |
| 404 | エンドポイントが存在しない |

エラーレスポンス例：

```json
{ "error": "DEVICE_BUSY" }
```

エラーメッセージには具体的な原因（他のインスタンスが実行中、旧版プロセスが残存している等）が記載されています。

## <DocIcon name="scale" /> WebSocket との役割分担

| 操作内容 | 使用するプロトコル |
| --- | --- |
| 設定の読み書き、タスクパラメータの更新 | WebSocket |
| ログおよび統計ストリームの購読 | WebSocket |
| インスタンスの起動・停止、状態ポーリング | HTTP 薄型インターフェース |
| ホットアップデートの実行 | HTTP 薄型インターフェース |

Android ホストは HTTP を「電源スイッチ」として、WebSocket を「データプレーン」として使い分けます。これにより、万が一 WebSocket が切断された場合でも、ホストは HTTP 経由でインスタンスを安全に強制停止できます。