mt5-robot-tester

MT5 ロボットテスター

概要

コマンドラインからストラテジーテスターを操作し、candidates フォルダー内の最適な MetaTrader 5 ロボット（エキスパートアドバイザー）を選定します。3 ラウンドのパイプラインを通じて各ボットをフォルダー間で移動させながら、実行を重ねるごとに学習し、選定結果を改善します。実行全体はチェックポイントに保存され、中断後に再開できます。

• ラウンド 1 — スクリーニング（全ペア）： 設定済みの common.symbols リストにある各シンボルで EA をバックテストします（シンボルごとに Optimization=0 のバックテストを 1 回実行します。MT5 ビルド 6061 では Optimization=3 の XML が空になるため、シンボルごとのバックテストを使用します）。通過条件：5 つ以上のシンボルで利益が出ており、かつ最良のシンボルで証拠金の 3 倍以上。
• ラウンド 2 — 最良ペアのバックテスト： 最良のシンボルでバックテストを 1 回実行し、純利益率、最悪ドローダウン率、プラスの月の割合、全年度でプラスかどうか、LR 相関、新高値までの月数を分析します。
• ラウンド 3 — 順次パラメーター最適化： MagicNumber の後にある 5～6 個の入力値を、1 つずつ ±50％、刻み幅 5％の範囲で最適化し、その後に最終バックテストを実行します。
• 最終候補： 最適化後の結果がラウンド 2 の結果を上回り、利益が証拠金の 4 倍以上、かつ最悪ドローダウンが12％以下であること。

テスト済みのボットは in-testing に移動されます。最終候補は、最適化済みの .set とともに finalists にもコピーされます。

使用する場面

• 「MetaTrader 5 でロボット／ボット／EA をテストする」
• MT5 エキスパートアドバイザーのフォルダーをスクリーニングし、すべてのペアから最適なものを選ぶ。
• EA のパラメーターを最適化し、利益／ドローダウン／一貫性に基づいて最終候補を決める。
• 中断したテスト実行を再開する。

前提条件

• Windows と MetaTrader 5 がインストールされていること（テスターは terminal64.exe を実行します）。
• ブローカーのティックデータがダウンロード済みであること（デフォルトのモデリングは実ティックの Model=4 です）。
• MQL5\Experts の下に 3 つのフォルダー candidates、in-testing、finalists があること。
• 設定で common.symbols が指定されていること — ラウンド 1 のバックテスト対象となるペア（ご利用のマーケットウォッチのシンボル）です。
• ボットごとの .set ファイルは任意です（設定の sets_dir）。ラウンド 2 のベースラインとラウンド 3 のパラメーター最適化に使用します。最適化中は、現在検索中のパラメーターを除くすべての入力値が固定されます。.set がない場合、ラウンド 3 はスキップされ、判定はラウンド 2 の結果に基づきます。
• 実行前に MetaTrader 5 を終了してください — テスターがデータフォルダーを排他的に使用する必要があります。
• Python 3.9 以降（標準ライブラリーのみ）。有料 API は不要です。

ワークフロー

ステップ 1 — 設定

assets/pipeline_config.template.json をコピーし、3 つのフォルダーのパスを入力して、 terminal_path に明示的な terminal64.exe のパスを設定します。実際にテスターを実行するには、 パスを指定せずに検出を有効にする場合を除き、ターミナルのパスが必須です。--terminal-path、 設定の terminal_path、または $MT5_TERMINAL_PATH で指定します。 --dry-run はターミナルの解決や起動をせずに INI を生成するため、 ターミナルのパスは不要です。実際の個人用パスは絶対にコミットせず、実行時に設定ファイルを 渡してください。デフォルトには合意済みの設定（2020.01.01→2026.06.30、H1、 Model=4、10000 USD、1:100、ゲートとしきい値）がすでに設定されています。

ターミナルの選択はオプトインです。 安全のため、パイプラインは Program Files 内の terminal64.exe を自動検出しません。ライブ取引も行うマシンでは、 自動検出されるターミナルがブローカーのライブ用ターミナルであることがよくあります。生成される INI には Login がないため、最後に使用したアカウントで起動し、 終了時に ShutdownTerminal=1 によって閉じられます。ライブ用ターミナルを気付かないまま使用して 閉じてしまうことを避けるには、専用データディレクトリを備えた /portable フォルダーなどの テスター専用のポータブルインストールへの明示的なパスを渡してください。リスクを承知のうえで 明示的に許可する場合は、--terminal-path、$MT5_TERMINAL_PATH、 config.terminal_path のいずれも設定されていないときに限り、--allow-auto-detect によって Program Files の検出が有効になります。

以前の優先順位／フォールバック動作からの変更： 選択の優先順位は --terminal-path > config.terminal_path > MT5_TERMINAL_PATH になりました。設定値は 環境変数より優先されます。最も優先順位の高い指定パスは存在している必要があります。 パスが存在しない場合は、--allow-auto-detect を指定していてもフォールバックせず、致命的なエラーになります。 たとえば、古い config.terminal_path が有効な MT5_TERMINAL_PATH を妨げます。 古い設定値を修正または削除するか、有効な CLI パスで上書きしてください。 自動検出はオプトインであり、パスが指定されていない場合に限り適用されます。

ステップ 2 — ドライラン（任意）

MT5 を解決または起動せずに、生成された Round-1 INI を確認します。このオフラインのドライランでは、 ターミナルのパスも、MT5 のインストールも不要です。

python3 skills/mt5-robot-tester/scripts/mt5_batch_tester.py \
  --config my_config.json --output-dir reports/mt5_pipeline --dry-run

ステップ 3 — パイプラインを実行

python3 skills/mt5-robot-tester/scripts/mt5_batch_tester.py \
  --config my_config.json --output-dir reports/mt5_pipeline \
  --terminal-path "C:\Program Files\MetaTrader 5\tester\terminal64.exe"

各ボットは R1 → R2 → R3 → 最終候補の判定へと進みます。各ステップの後に、 進捗が state.json と run.log に書き込まれます。

ステップ 4 — 中断した場合に再開

python3 skills/mt5-robot-tester/scripts/mt5_batch_tester.py \
  --config my_config.json --output-dir reports/mt5_pipeline --resume \
  --terminal-path "C:\Program Files\MetaTrader 5\tester\terminal64.exe"

--resume は完了済みのボットをスキップし、実行設定、EA バイナリ、入力 .set のフィンガープリントが 一致している間に限り、完了済みラウンドを再利用します。期間、シンボルリスト、バイナリ、 または .set が変更されると、そのボットは安全に再起動します。

任意 — HTML コントロールパネル

ローカルダッシュボードを起動すると、各フォルダー内のボット、各ボットのフェーズと判定、 起動ボタンを確認できます。起動後は CLI は不要です。

python3 skills/mt5-robot-tester/scripts/dashboard.py \
  --config my_config.json --output-dir reports/mt5_pipeline

http://127.0.0.1:8765/ で配信されます（自動的に開き、localhost のみで利用できます）。ページは 3 秒ごとに自動更新され、フォルダーの内容、ボットごとのフェーズ（R1/R2/R3/done）、 合格／不合格の判定、集計、実行中の run.log が表示されます。開始／停止リクエストは正確なローカル オリジンに限定され、サーバーごとの CSRF トークンが必要です。

ステップ 5 — 結果を確認

• leaderboard_<ts>.md / .json — 判定と主要指標を含むランキング。
• learnings.json / learnings.md — このループでスキルが学習した内容（パラメーターの影響とシンボルの事前情報）。設定された出力ディレクトリに保存されます。
• mt5_reports/ と mt5_ini/ — ボット／ラウンドごとの MT5 レポートと設定ファイル。

ラウンドの詳細

Round 1 のゲート（両方必須）

1. count_positive_profit(passes) ≥ round1_min_positive（デフォルト 5）。
2. best_symbol_profit ≥ round1_min_profit_multiple × deposit（デフォルト 3×）。

不合格 → ボットは却下されます（in-testing に移動）。

Round 2 の品質プロファイル（参考しきい値）

純利益 ≥300%、最悪 DD <15%（残高／エクイティの % のうち大きい方）、利益が出た月

70%、すべての年で利益がプラス、LR Correlation ≥0.80、最高値更新までの月数 ≤3。 ボットごとに報告されます。最終候補を決めるハードゲートは Round 3 です。

ラウンド3：逐次最適化

MagicNumber以降の5～6個の入力について（学習した順序を優先）、ほかのすべての.set入力を固定したまま、そのパラメーター1つを[V×0.5, V×1.5]の範囲で、刻み幅V×0.05（Optimization=1）で最適化します。最適値を固定してから次のパラメーターに進みます。最終候補については、保存した入力一式を正確に指定して最終バックテストを実行します。

最終候補

evaluate_finalist：ラウンド2より改善し、かつ利益が入金額の4倍以上、かつ最大DDが12%以下の場合、finalistsに<bot>.setとともにコピーします。

ループ間の自己学習

learnings.jsonには、実行ごとにパラメーターごとの平均利益改善（影響の大きいパラメーターを先に試すよう、ラウンド3の最適化順を変更します）、シンボルの事前確率（各シンボルが最良ペアとなった頻度）、ボットごとの判定が蓄積されます。これにより、各ループで選定がより速く収束します。決定論的な単純集計統計です。

出力形式

• leaderboard_<ts>.json — {name, verdict, best_symbol, r2_profit, final_profit, final_dd_pct, lr, reason}のリスト。最終候補を利益順に先頭へ並べます。
• leaderboard_<ts>.md — 同じ内容を表形式で記載します。
• state.json — ボット／ラウンドごとの再開可能なチェックポイントです。

リソース

• scripts/mt5_batch_tester.py — パイプラインのオーケストレーターとINIビルダー（CLI）。
• scripts/parse_mt5_optimization.py — 最適化レポート（XML/HTML）のパーサーとラウンド1のゲート。
• scripts/parse_mt5_report.py — バックテストレポートのパーサーと残高系列の指標。
• scripts/mt5_learnings.py — 実行間の学習ストア。
• scripts/mt5_common.py — 共通の解析ヘルパー（EN/ESヘッダー、数値）。
• references/mt5-cli-reference.md — MT5の[Tester]／[TesterInputs]キー、列挙値、レポート形式、注意事項。
• assets/pipeline_config.template.json — プレースホルダーを含む設定テンプレート。

主な原則

1. 個人のパスをコミットしない — フォルダーとターミナルは設定／ENV／引数から指定します。
2. Report=には相対パス名を使用する — ビルド6061は絶対レポートパスを無視するため、完了したレポートはターミナルのデータディレクトリから収集します。
3. **リアルティック（Model=4）**にはブローカーのティックデータが必要です。処理に時間がかかるため、長時間の実行を想定してください。
4. 再開可能：各ラウンドでチェックポイントを保存します。--resumeはフィンガープリントが一致する作業のみを再利用し、実行エラーは再試行します。
5. フェイルクローズ：不完全、タイムアウト、古い、または解析不能なレポートによって、候補を却下、昇格、移動することはありません。ラウンド1のすべての一意なシンボルの処理が完了する必要があります。
6. MT5の単一所有者：共有MT5データフォルダーごとに、プロセスの存続期間中はOSロックを保持します。子プロセスの終了を確認できない場合、実行全体を停止して.blockedマーカーを書き込みます。そのマーカーを手動で削除する前に、記録されたPID／プロセスツリーが終了していることを確認してください。
7. 全期間の指標：期間の最初や最後、または丸1年にわたって取引がない月も、設定されたテスト期間に含めます。
8. 各ループで学習：パラメーター／シンボルの統計を使い、今後の実行が勝ちにつながる方向へ調整されます。
9. 使用するビルドで検証する：レポートのレイアウト（特に取引テーブル）と32 msの遅延マッピングは異なる場合があります。リファレンスの*(verify)*に関する注記を参照してください。