Keyboard Maestroの「Macro Debugger」で複雑なマクロのデバッグを行う方法

2026年4月2日

Keyboard Maestroのマクロが複雑になるほど、想定通りの挙動にならないときに「どこでうまくいっていないのか」「何が原因なのか」が分からなくなります。
そんなときのために、Keyboard Maestroにはデバッグ機能が用意されています。

私自身いままでデバッグ機能を使わずに何となくでやってきましたが、原因の切り分けや複雑なマクロ作りをラクにするためにも、使い方やどんなことができるか理解しておいた方がいいなと思いました。

そこで、今回はKeyboard Maestroのデバッグ機能についてまとめます。

Macro Debugger

Macro Debuggerの起動

デバッグは「Macro Debugger」というウインドウを開いて行います。
起動方法は2種類あります。

メニューバーから起動する方法
アクションを使って起動する方法

まず、メニューバーのKeyboard Maestroアイコンから［Start Debugging］を選択すると、Macro Debuggerが開きます。

もしくはアクションから起動する方法もあります。
［Debugger］カテゴリに［Debugger Start］があるので、それを実行して開けます。

Macro Debuggerは下記のような表示になっていて、左上には「Pause New Macros（マクロを一次停止させる）」チェックボックスと、右上には変数の表示・非表示を切り替えるボタンがあります。

Macro Debuggerでアクションを順番に実行

Macro Debuggerが表示された状態でマクロを発火させると、実行したアクションが表示されます。
しかし、アクションが一瞬だけ表示されてすぐ消えてしまいます。

その場合は左上にある「Pause New Macros」にチェックを入れることで、マクロを一気に実行せずにアクションを1つずつ止めてデバッグできます。

試しに「Pause New Macros」にチェックを入れた状態で、下記の「Google Chromeで開いているURLを指定プロファイルに切り替えて開き直すマクロ」を実行してみました。

すると、Macro Debuggerに実行したマクロ名と1つ目のアクションである「Set Variable “URL” to Text “%ChromeURL%”」が表示されました。

そしてアクションの表示の左にツールボックスのような表示があります。
これらのボタンをクリックして、停止したアクションが次にどう実行していくのか選んで操作していきます。

アイコンしか表示されていないので分かりにくいですが、全部で下記5種類です。

Continue：続行（次のブレークポイントまで進める）
Pause：一時停止
Step Over：ネストしたアクションをまとめて進めて次のアクションで一時停止
Step In To：ネストしたアクションの中に入って一時停止
Step Out Of：「Step In To」で入ったアクションから外に出るまで進めて次のアクションで一時停止

これらを活用してアクションをステップ実行し、挙動を確認していきます。

ちなみに右側にある「鉛筆」アイコンをクリックするとKeyboard Maestroのエディタが開き、「×」アイコンをクリックすると実行中のマクロがキャンセルされます。

Step 〇〇系の挙動を理解する

Continue（続行）とPause（一時停止）は分かると思いますが、Step 〇〇系が理解しにくいと思います。
これらはネスト（階層化）したアクションの中までステップ実行するかどうかが変わってきます。

例として、下記の「Group」アクションで「Display text」をネストしたマクロを用意しました。

「Step Over」を実行すると、アクションが1つずつ順番に実行されますが、「Group」内のアクションはまとめて実行されます。

もし「Group」まで来たタイミングで「Step In To」を使うと、Group内の最初のアクションに入って一時停止します。
ネストされたアクションまで細かく見るか、そこはスキップして上位のアクションだけPauseしながら見て回るかを使い分けられます。

そして「Step Out Of」は、すでにGroup内などのネストしたアクションでPauseしている状態で使います。
現在の階層にある残りのアクションを実行し、その階層を抜けたところでPauseします。

ちなみに「Execute Macro」アクションを使って別マクロを実行している場合も同様で、「Step In To」を使うと別マクロ内のアクションを1つずつ実行できます。

変数の表示設定

Macro Debuggerの右上にある「x」のボタンをクリックすると、変数の表示・非表示を切り替えられます。

どちらが表示状態か分かりにくいですが、色が濃いグレーになっていれば変数が表示されます。
変数を代入したあとに「変数名 = 値」の形式でMacro Debuggerに表示されるようになります。

変数の値が意図通りになっているか確認できるので、こちらはオンにしておいた方が良さそうです。

ブレークポイントを設定する

「Pause New Macros」にチェックを入れて1つずつアクションを見ていってもいいですが、それだと長いマクロの場合に面倒です。

そこで活用するのが「ブレークポイント（Breakpoint）」です。
設定したい箇所にアクションを追加しておくことで、その位置でマクロを止められます（長いマクロでブレークポイントを活かしたいなら、Macro Debuggerの「Pause New Macros」は外しておいた方が分かりやすいです）。

「Debugger Breakpoint」のアクションは3種類ありますが、基本的には「Debugger Breakpoint This Macro」を使うことになります。

「Continue」を押せばブレークポイントの位置まで一気に進み、そこから細かく見たい場合は「Step Over」や「Step In To」でステップ実行していきます。

ステップ実行の注意点

Macro Debuggerを使えばアクションをステップ実行できて、なにが起こっているのかを把握するのには非常に便利です。

しかしステップ実行はアクション間に遅延が入るため、マウスクリックやUI操作を含むマクロは通常実行時と挙動が変わることがあります。

例えば、ボタンをクリックしてからメニューが表示されるまでにタイムラグがある場合、ステップ実行では問題なく動くのに通常実行では失敗する可能性があります。

ステップ実行だと問題ないのに普通に実行するとうまくいかない場合、遅延の差を疑って「Pause」アクションを追加するなどしてみてください。

Debugger関連のアクション一覧

基本的にデバッグ関連のアクションは「Debugger Breakpoint This Macro」を使って、それ以外はあまり使う機会がなさそうですが、念のためDebuggerカテゴリのアクションを整理しておきます。

アクション	内容
Debugger Start	Macro Debuggerを起動する
Debugger Finish	Macro Debuggerを終了する
Debugger Toggle	Macro Debuggerの起動・終了を切り替える
Debugger New Macros Paused	新しく実行するマクロを一時停止した状態で開始する
Debugger New Macros Run	新しく実行するマクロを停止させずそのまま実行する
Debugger Breakpoint This Macro	現在のマクロを一時停止
Debugger Breakpoint All Other Macros	他のすべてのマクロを一時停止
Debugger Breakpoint All Macros	すべてのマクロを一時停止
Debugger Step Over Other Macros	一時停止中の他のマクロをStep Overで1つ進める
Debugger Step Into Other Macros	一時停止中の他のマクロをStep Intoで1つ進める
Debugger Step Out Other Macros	一時停止中の他のマクロをStep Outで抜けるまで進める
Debugger Continue This Macro	現在のマクロの実行を再開する
Debugger Continue All Macros	一時停止中のすべてのマクロの実行を再開する

デバッグを便利にするために、Macro Debuggerの起動やContinueなどの操作にショートカットキーを割り当てたい場合に使えそうです。

「All Macros」や「Other Macros」系は、マクロの実行中に別のマクロがトリガーされて干渉しているケースなどで使います。

その他のデバッグ方法

変数の監視（Value Inspector）

変数の値が原因でマクロがうまく動かないことも多いです。
Value Inspectorを使うと、変数の値をリアルタイムで確認できます。

Keyboard Maestroエディタを開いてメニューバーの［Window］→［Value Inspector］から開けます。

ウインドウ左下にある「+」ボタンから監視対象の変数を追加し、あとはマクロの実行で値が変わるたびにリアルタイムで反映されます。

Macro Debuggerを使う場合は変数表示をオンにしておけば問題ないので、わざわざこちらも使う必要はないのかもしれませんが、複数の変数を常に表示して監視したいときに便利です。

Display Textアクションで変数を表示する

無理矢理な方法ですが、「Display Text」アクションを使うと変数の値をポップアップで表示できます。

Value Inspectorを開くのが面倒なときなど、とりあえず変数の値を表示したいときにこの方法を使うときがあります。

表示方法	内容
Display Text In a Window	テキストをOKボタン付きのウインドウに表示
Display Text Briefly	通知として一時的に表示（数秒で消える）
Display Text Large	テキストを画面中央に大きく表示

私の場合は「Display Text In a Window」をよく使っています。
OKを押すまでマクロが一時停止してくれるので、値をゆっくり確認できます。