コアプログラムトラブルシューティング
デバイスと ADB
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
adb devices の結果が空 | エミュレーターのデバッグ機能が未有効化、または adb server が停止 | エミュレーター設定で ADB を有効化し、adb start-server を実行 |
デバイス状態が offline | adb バージョンの不一致（複数エミュレーター間で異なる adb が競合） | エミュレーター付属の adb を使用するか、環境内の adb バージョンを統一 |
| 複数エミュレーター稼働時に誤接続 | Serial の誤記、または auto による誤判定 | host:port 形式で明示的に Serial を手動指定 |
| 接続が頻繁に切断される | エミュレーターの省電力モード、USB セレクティブサスペンド | 省電力設定を無効化し、スクリーンショット方式を ADB_nc に変更 |
| エミュレーターの再起動コマンドが効かない | インストール先パスまたはインスタンス名が未登録 | EmulatorInfo.name / path を正しく設定 |
スクリーンショット
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| 画面が真っ暗 | エミュレーターが独立レンダリング方式を採用しており通常の ADB 経由で取得不可 | DroidCast_raw、nemu_ipc（MuMu）、または ldopengl（LDPlayer）へ変更 |
| タイムアウトする | バックエンドの描画または ADB のフリーズ | スクリーンショット方式を変更。「デバイス未検出時に adb を再起動」を有効化 |
| 画面が乱れる・ティアリング発生 | 画像エンコードまたはスケーリングの不整合 | 「画像のカラーディザリング除去」をオフにして再試行 |
| 解像度が 1280×720 でない | エミュレーター側の解像度や DPI 設定が変更されている | エミュレーターを 1280×720 に修正し、ゲームを再起動 |
| スクリーンショットは正常だがタップ位置がずれる | 画面スケーリングと座標マッピングの不一致 | デフォルトの解像度と DPI に戻し、OS 側の拡大スケーリングを回避 |
画像認識
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| ボタンが検出されない | スキン・特殊装備による遮蔽、またはゲーム UI の仕様変更 | デフォルト衣装に戻す。コアプログラムのリソースを最新に更新 |
| OCR の数値認識ミス | 文字色の前処理不一致、フォントスケーリングの乱れ | 解像度を再確認。OCR モデルバージョン（OcrModelVersion*）を切り替え |
| 未知の画面で停止する | 未対応のポップアップダイアログ等の出現 | エラー現場のスクリーンショットを確認。手動でポップアップを閉じて再開 |
| 実機では認識できるがエミュレーターで失敗する | レンダリングエンジンの差異 | テンプレート画像を変更するのではなく、スクリーンショット方式を変更 |
エラー現場のスクリーンショットの確認
log/error/<インスタンス>/<タイムスタンプ>/ に保存されている画像は、スクリプトが判定に失敗した瞬間の実際の画面です。問題究明において記憶よりも確実に事実を物語ります。
スケジューラー
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| タスクが一切実行されない | 機能が無効、NextRun が未来時刻、実行キューが空 | Enable 設定およびスケジュール時刻を確認 |
| 常に特定のタスクばかり実行される | 当該タスクの優先度が高く、かつ常に期限到来状態 | カスタム優先度またはタスクの実行間隔を調整 |
| ゲームが繰り返し再起動される | GameStuckError または画面が認識不能 | エラー画面およびゲームサーバーのメンテナンス状況を確認 |
| インスタンスが自動停止した | 重要タスクの失敗、または ScriptError が連続3回発生 | ログの直近100行を確認し根本原因を修正 |
| 同一タスクのまま数時間停止 | 処理のデッドロック（ログ出力は継続している場合） | 実行監視機能（Watchdog*）を有効化 |
| タスクが翌日まで延期された | TaskRestartLimit（連続失敗上限）に到達 | 根本原因を解消するか、一時的に上限値を拡大 |
| 複数インスタンスが相互干渉する | 同一の Serial や同一のインスタンス名を指定している | 1インスタンス＝1エミュレーター＝1プロセスの原則を徹底 |
ログの重要キーワード
| キーワード | 意味 |
|---|---|
连续失败（連続失敗） | 失敗カウントが上昇中。設定によりエミュレーター再起動へエスカレーション |
Restart | 再起動タスクがキューに挿入された状態 |
EmulatorOpBusy | 起動・停止処理がすでに実行中であるため今期の処理をスキップ |
ScriptError | スクリプトコードの例外エラー |
RequestHumanTakeover | 安全な自己判断が不可能な状態。手動介入を要求 |
[服务器检查] | メンテナンス検出中 |
設定
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| 設定を変更したのに反映されない | タスク実行中。設定はタスク境界でのみ再ロードされる | タスクの完了を待つか、インスタンスを再起動 |
| 保存した値が元に戻る | override.yaml により設定値が強制上書きされている | 当該フィールドがユーザー編集可能か確認 |
| 保存時にコンフリクトが発生 | 複数のブラウザタブ等から同時に編集された | ページをリフレッシュして再入力 |
| インポート後にフィールドが欠落 | バージョンをまたぐ移行処理の失敗 | 各設定画面を開き重要スイッチを再確認 |
| 日本語が英語キー名で表示される | i18n 辞書の翻訳欠落 | コアリポジトリを更新するか翻訳ファイルを補完 |
リモートアクセス
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| LAN 内から WebUI が開かない | リッスンアドレスが 127.0.0.1、またはファイアウォール | WebuiHost を 0.0.0.0 に変更しポートを開放 |
固定 URL が /error に 302 リダイレクト | デバイスがオフライン、トンネル接続の切断 | リモートアクセス画面の接続ステータスを確認 |
| 画面が読み込み中のまま進まない | 経由ネットワークで WebSocket 通信が遮断されている | ネットワーク環境を変更。ポート 7844 の疎通を確認 |
| ペアリングコードが無効 | 有効期限（5分）を超過 | ペアリングコードを再発行 |
| 接続解除後もクライアントが接続可能 | ローカル側でエントリを削除しただけ | ホスト側の管理画面から明示的にペアリングを取り消し |
| MCP で 401 エラー | パスワード未送信、またはパスワード変更後の WebUI 未再起動 | Authorization: Bearer を設定し WebUI を再起動 |
パフォーマンス
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| 画像認識の処理が遅い | スクリーンショット方式の遅延、OCR の CPU 負荷 | パフォーマンステストを実行し最速方式を選択。OCR デバイスを調整 |
| CPU 使用率が 100% に達する | 複数インスタンスの同時稼働 ＋ 高フレームレート設定 | 同時実行数を減らし、タスクの実行時間帯を分散 |
| メモリ使用量が増加し続ける | 長時間稼働によるキャッシュの蓄積 | 定期再起動機能を有効化し、エラー画面の保持数を制限 |
| ディスク容量が圧迫される | ログ、エラー画面、自動バックアップの蓄積 | RetentionDays、KeepDays の保持日数を短縮設定 |
アップデート後の異常発生時
- 更新前の安定したコミットを
git logで確認します。 frontend/distが正しく再ビルドされているか確認します。uvによる依存関係が同期されているか確認します。- コードをロールバックし、
uv sync --frozenを実行して起動し直します。
bash
git log --oneline -5
git checkout <直前の安定コミット>
uv sync --frozenローカル変更が破棄されるのを防ぐため、安易に git reset --hard を使用しないでください。
推奨される段階的動作確認手順
text
1. スクリーンショットテスト → 画面を取得できるか？
2. 手動タップテスト → 操作方式が正常に動作するか？
3. 単一タスクの「即時実行」 → タスクフローを完走できるか？
4. スケジューラー開始 → スケジュール通りにトリガーされるか？
5. 2つ目のタスクを追加 → タスク間で相互干渉しないか？
6. 2つ目のインスタンスを追加 → マシンスペックが十分か？全タスクを一括で有効化するのではなく、1ステップずつ確認しながら進めることで、障害の原因を素早く特定できます。