---
url: /ja/troubleshooting.md
description: 現象から根本原因を特定する階層的アプローチ：デバイス、認識、スケジューリングのレイヤー特定、証跡収集、単一変数の変更と検証。
---

# トラブルシューティング手法

自動化システムにおけるトラブルの多くは「システム全体の破損」ではなく、「特定のステップが期待通りに完了しなかった」ことに起因します。当てずっぽうに設定を変更するよりも、レイヤーごとに階層的に切り分けるアプローチが最も迅速です。

##  まずレイヤーを切り分ける

```text
第 0 層：ランチャー / APK アプリ自体が正常に起動できるか
第 1 層：バックエンドプロセスが起動できるか（ポート競合、パスワード、フロントエンド）
第 2 層：エミュレーター/実機と接続できるか（ADB、スクリーンショット、タップ操作）
第 3 層：画面の画像認識が正しく行われているか（ページ判定、ボタン検出、OCR）
第 4 層：タスクロジックとスケジューリング（タスク選定、スケジュール時刻、エラー復帰）
第 5 層：ゲーム側の仕様変更やイベントギミックへの適合
```

調査は必ず下位レイヤーから上位レイヤーへ順に進めてください。第2層（デバイス接続）が成立していない状態で第4層（タスク設定）を変更しても問題は解決しません。

##  証跡収集チェックリスト

| 証跡データ | 格納場所・確認方法 |
| --- | --- |
| 現在のタスクとステータス | WebUI ダッシュボード |
| 直近の実行ログ | `log/<日付>_<インスタンス>.txt` |
| エラー発生時の現場記録 | `log/error/<インスタンス>/<タイムスタンプ>/`（スクリーンショット ＋ log.txt） |
| ランチャーのログ | `log/<日付>_launcher.txt` |
| Android ホストのログ | `log/app.log`、`log/proot/session.log` |
| デバイスの接続状態 | `adb devices`、WebUI のスクリーンショットテスト |
| ソフトウェアバージョン | コアのコミットハッシュ、ランチャーのバージョン、Runtime のバージョン |

::: danger 共有前のマスキング（個人情報の除外）
設定のエクスポートファイルにはエミュレーターの Serial、SSH 秘密鍵、WebUI パスワード、リモート接続用認証情報が含まれます。Issue 等に投稿する前にこれらの機密フィールドを必ず削除してください。
:::

## &#x20;代表的な症状と最初の確認ポイント

| 現象 | 最初に確認すべきポイント |
| --- | --- |
| WebUI が開かない | プロセスが生存しているか、ポートが競合していないか、リッスンアドレスの設定 |
| スクリーンショットが真っ黒 | スクリーンショット方式の選定、解像度の設定、エミュレーターのグラフィックス描画エンジン |
| 画面をタップできない | 操作方式の設定、仮想画面の権限、ユーザー補助/特権サービスの状態 |
| 画像認識の位置がずれる | 解像度が 1280×720 固定になっているか、スキンや特殊装備による立ち絵の遮蔽 |
| タスクが繰り返し失敗する | ログ内の具体的な例外型（単に「失敗」という文字ではなくトレースバック） |
| タスクが実行されない | `Enable` スイッチ、`NextRun` の時刻、優先度設定、重要タスク失敗による一時停止 |
| 設定を変更しても反映されない | タスクが現在実行中であるか（境界時のみリロード）、`override.yaml` による強制上書き |
| アップデート後にクラッシュする | 直前のバージョンへのロールバック、自動生成ファイルの差分確認、依存関係の同期状態 |

## &#x20;変数の隔離（一度に一箇所のみ変更）

トラブルシューティング時は一度に一つの項目のみを変更し、変更前と変更後の結果を記録してください：

1. スクリーンショット方式を変更する場合 → スクリーンショット方式のみ変更し、操作方式には触れない。
2. 操作方式を変更する場合 → 操作方式のみを変更。
3. 海域や編成を変更する場合 → タスクパラメータのみを変更。
4. インスタンスを切り替える場合 → 設定固有の問題か環境全体の問題かを切り分け。

同時に複数の箇所を変更すると、どの修正が有効であったかを判別できなくなります。

## &#x20;直ちに自動化を停止すべきケース

| 状況 | 推奨アクション |
| --- | --- |
| 重要タスク（月またぎ処理、SP海域、アビサル等）での連続失敗 | 無理にリトライを繰り返さず、エラー現場のログと画面を保存して停止 |
| アカウントに異常ログインや運営からの警告通知が表示された | 直ちにすべての自動化スクリプトの実行を停止 |
| ログ内にパスワードや個人情報が出力されているのを発見した | ログの公開・共有を中止し、速やかにマスキングを実施 |
| エミュレーターの連続自動再起動が閾値を超過した | スクリプトの再試行回数を増やすのではなく、エミュレーター側の異常を点検 |

## &#x20;適切な Issue 報告の構成

記載すべき項目：

* 各種バージョン（コアのコミットハッシュ / ランチャー / Runtime）
* OS プラットフォームおよびエミュレーター名（実機の場合は端末型番と Android バージョン）
* 正確な再現手順（どの画面で何を操作したか）
* 期待していた結果 vs 実際の結果
* 該当部分のログ抜粋およびエラー発生時のスクリーンショット
* すでに試行した切り分け作業

記載してはならない項目：

* `deploy.yaml`、`password.txt`、`remote-access.json` などの認証情報
* アカウント情報（UID や艦隊情報等）が無加工で写り込んだスクリーンショット
* 「使えません」などの具体性のない報告

## &#x20;プラットフォーム別トラブルシューティング