---
title: コアプログラムトラブルシューティング
description: デバイス接続失敗、スクリーンショット・画像認識エラー、スケジューラー停止、設定不反映、リモートアクセス不通の切り分けと対処法。
updated: 2026-10-20
---

# コアプログラムトラブルシューティング

## <DocIcon name="smartphone" /> デバイスと 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` を正しく設定 |

## <DocIcon name="eye" /> スクリーンショット

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| 画面が真っ暗 | エミュレーターが独立レンダリング方式を採用しており通常の ADB 経由で取得不可 | `DroidCast_raw`、`nemu_ipc`（MuMu）、または `ldopengl`（LDPlayer）へ変更 |
| タイムアウトする | バックエンドの描画または ADB のフリーズ | スクリーンショット方式を変更。「デバイス未検出時に adb を再起動」を有効化 |
| 画面が乱れる・ティアリング発生 | 画像エンコードまたはスケーリングの不整合 | 「画像のカラーディザリング除去」をオフにして再試行 |
| 解像度が 1280×720 でない | エミュレーター側の解像度や DPI 設定が変更されている | エミュレーターを 1280×720 に修正し、ゲームを再起動 |
| スクリーンショットは正常だがタップ位置がずれる | 画面スケーリングと座標マッピングの不一致 | デフォルトの解像度と DPI に戻し、OS 側の拡大スケーリングを回避 |

## <DocIcon name="brain" /> 画像認識

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| ボタンが検出されない | スキン・特殊装備による遮蔽、またはゲーム UI の仕様変更 | デフォルト衣装に戻す。コアプログラムのリソースを最新に更新 |
| OCR の数値認識ミス | 文字色の前処理不一致、フォントスケーリングの乱れ | 解像度を再確認。OCR モデルバージョン（`OcrModelVersion*`）を切り替え |
| 未知の画面で停止する | 未対応のポップアップダイアログ等の出現 | エラー現場のスクリーンショットを確認。手動でポップアップを閉じて再開 |
| 実機では認識できるがエミュレーターで失敗する | レンダリングエンジンの差異 | テンプレート画像を変更するのではなく、スクリーンショット方式を変更 |

::: tip エラー現場のスクリーンショットの確認
`log/error/<インスタンス>/<タイムスタンプ>/` に保存されている画像は、スクリプトが判定に失敗した瞬間の実際の画面です。問題究明において記憶よりも確実に事実を物語ります。
:::

## <DocIcon name="zap" /> スケジューラー

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| タスクが一切実行されない | 機能が無効、`NextRun` が未来時刻、実行キューが空 | `Enable` 設定およびスケジュール時刻を確認 |
| 常に特定のタスクばかり実行される | 当該タスクの優先度が高く、かつ常に期限到来状態 | カスタム優先度またはタスクの実行間隔を調整 |
| ゲームが繰り返し再起動される | `GameStuckError` または画面が認識不能 | エラー画面およびゲームサーバーのメンテナンス状況を確認 |
| インスタンスが自動停止した | 重要タスクの失敗、または `ScriptError` が連続3回発生 | ログの直近100行を確認し根本原因を修正 |
| 同一タスクのまま数時間停止 | 処理のデッドロック（ログ出力は継続している場合） | 実行監視機能（`Watchdog*`）を有効化 |
| タスクが翌日まで延期された | `TaskRestartLimit`（連続失敗上限）に到達 | 根本原因を解消するか、一時的に上限値を拡大 |
| 複数インスタンスが相互干渉する | 同一の Serial や同一のインスタンス名を指定している | 1インスタンス＝1エミュレーター＝1プロセスの原則を徹底 |

### ログの重要キーワード

| キーワード | 意味 |
| --- | --- |
| `连续失败`（連続失敗） | 失敗カウントが上昇中。設定によりエミュレーター再起動へエスカレーション |
| `Restart` | 再起動タスクがキューに挿入された状態 |
| `EmulatorOpBusy` | 起動・停止処理がすでに実行中であるため今期の処理をスキップ |
| `ScriptError` | スクリプトコードの例外エラー |
| `RequestHumanTakeover` | 安全な自己判断が不可能な状態。手動介入を要求 |
| `[服务器检查]` | メンテナンス検出中 |

## <DocIcon name="settings" /> 設定

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| 設定を変更したのに反映されない | タスク実行中。設定はタスク境界でのみ再ロードされる | タスクの完了を待つか、インスタンスを再起動 |
| 保存した値が元に戻る | `override.yaml` により設定値が強制上書きされている | 当該フィールドがユーザー編集可能か確認 |
| 保存時にコンフリクトが発生 | 複数のブラウザタブ等から同時に編集された | ページをリフレッシュして再入力 |
| インポート後にフィールドが欠落 | バージョンをまたぐ移行処理の失敗 | 各設定画面を開き重要スイッチを再確認 |
| 日本語が英語キー名で表示される | i18n 辞書の翻訳欠落 | コアリポジトリを更新するか翻訳ファイルを補完 |

## <DocIcon name="cloud" /> リモートアクセス

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| LAN 内から WebUI が開かない | リッスンアドレスが `127.0.0.1`、またはファイアウォール | `WebuiHost` を `0.0.0.0` に変更しポートを開放 |
| 固定 URL が `/error` に 302 リダイレクト | デバイスがオフライン、トンネル接続の切断 | リモートアクセス画面の接続ステータスを確認 |
| 画面が読み込み中のまま進まない | 経由ネットワークで WebSocket 通信が遮断されている | ネットワーク環境を変更。ポート 7844 の疎通を確認 |
| ペアリングコードが無効 | 有効期限（5分）を超過 | ペアリングコードを再発行 |
| 接続解除後もクライアントが接続可能 | ローカル側でエントリを削除しただけ | ホスト側の管理画面から明示的にペアリングを取り消し |
| MCP で 401 エラー | パスワード未送信、またはパスワード変更後の WebUI 未再起動 | `Authorization: Bearer` を設定し WebUI を再起動 |

## <DocIcon name="badge-dollar" /> パフォーマンス

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| 画像認識の処理が遅い | スクリーンショット方式の遅延、OCR の CPU 負荷 | パフォーマンステストを実行し最速方式を選択。OCR デバイスを調整 |
| CPU 使用率が 100% に達する | 複数インスタンスの同時稼働 ＋ 高フレームレート設定 | 同時実行数を減らし、タスクの実行時間帯を分散 |
| メモリ使用量が増加し続ける | 長時間稼働によるキャッシュの蓄積 | 定期再起動機能を有効化し、エラー画面の保持数を制限 |
| ディスク容量が圧迫される | ログ、エラー画面、自動バックアップの蓄積 | `RetentionDays`、`KeepDays` の保持日数を短縮設定 |

## <DocIcon name="refresh" /> アップデート後の異常発生時

1. 更新前の安定したコミットを `git log` で確認します。
2. `frontend/dist` が正しく再ビルドされているか確認します。
3. `uv` による依存関係が同期されているか確認します。
4. コードをロールバックし、`uv sync --frozen` を実行して起動し直します。

```bash
git log --oneline -5
git checkout <直前の安定コミット>
uv sync --frozen
```

ローカル変更が破棄されるのを防ぐため、安易に `git reset --hard` を使用しないでください。

## <DocIcon name="compass" /> 推奨される段階的動作確認手順

```text
1. スクリーンショットテスト → 画面を取得できるか？
2. 手動タップテスト → 操作方式が正常に動作するか？
3. 単一タスクの「即時実行」 → タスクフローを完走できるか？
4. スケジューラー開始 → スケジュール通りにトリガーされるか？
5. 2つ目のタスクを追加 → タスク間で相互干渉しないか？
6. 2つ目のインスタンスを追加 → マシンスペックが十分か？
```

全タスクを一括で有効化するのではなく、1ステップずつ確認しながら進めることで、障害の原因を素早く特定できます。