# Keyboard Maestroの変数基礎

URL: https://webrandum.net/keyboard-maestro-variables/
公開日: 2026-04-23
更新日: 2026-04-23
カテゴリー: 作業効率化
タグ: Keyboard Maestro
出典: Webrandum（著者: サイトウ マサカズ）

Keyboard Maestroでマクロを作り始めると、最初は単純なキー入力やアプリ起動だけで済みます。
しかし、マクロが複雑になるほど「値を一時的に保存しておきたい」「条件によって処理を分岐させたい」という場面が出てきます。

そこで必要になるのが変数です。
今回はKeyboard Maestroにおける変数の種類と使い方についてまとめます。

## 変数の基本

### 変数の設定

Keyboard Maestroの変数は、「Set Variable to 〇〇」系のアクションを使用します。
どのアクションも基本的には「変数名」と「値」を入力して、実行すると指定した変数名に値がセットされます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_1-2.png)

他にも「Prompt for User Input」系と組み合わせることで、ユーザーの入力を変数にセットしてその後の処理で使うことができます。

「Set Variable to 〇〇」系のアクションはかなりの種類が用意されていますが、大抵の場合は「Set Variable to Text」で問題ないでしょう。

また、変数名には日本語も使えますが、基本的には英語の方が望ましいです。
ただし、「Prompt for User Input」を使う場合、設定した変数名がそのままダイアログ内の入力フィールドラベルとして表示されてしまうので、日本語にする場合もあります。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_2-2.png)

### 変数の使用

変数の値を使うときには、「`%Variable%変数名%`」というトークンを使う場合と、変数名だけ入力する場合の2パターンがあります。

入力フィールドにフォーカスしたときに右の方に「T」と表示される場合はトークンを使います。
トークンを入力する必要があるアクションの場合、右上に「Insert Token」が表示されるので、そこからトークンを選択して入力できます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_3-3.png)

入力フィールドの右の方に「V」と表示される場合は変数名だけを入力します。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_4-3.png)

他によく使うのが「Condition（条件）」です。
「If Then Else」アクションを使う場合、「Add Condition」で「Variable Condition」を選択して変数名を入力すると、変数に入っている値によって条件分岐できます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_5-3.png)

### 変数の削除

変数を削除したい場合は、［環境設定］の［Variables］タブを開くと一覧で確認でき、不要な変数は左下のアイコンクリックで削除できます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_6-3.png)

マクロ内から削除したい場合は、変数の値に`%Delete%`をセットすることで削除できます。
※後ほど紹介するローカル変数やインスタンス変数はマクロの実行終了時に自動的に消えるので特に気にする必要はありません

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_7-3.png)

## 変数カテゴリのアクション一覧

変数を扱うアクションは種類が多いので、どんな用途にどのアクションを使うのかを一覧にまとめます。
私自身ほとんど使ったことの無いものもありますが、ざっと眺めておくと必要になったときに探しやすくなります。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_8-3.png)

| アクション名 | 機能 |
| --- | --- |
| Prepend Text to Variable | 指定した変数の先頭にテキストを追加する |
| Set Variable to Text | 変数にテキストをセットする |
| Append Variable with Text | 指定した変数の末尾にテキストを追加する |
| Set Variable to Calculation | 数式の計算結果を変数にセットする |
| Set Variable to Clipboard | 現在のクリップボードの内容を変数にセットする |
| Set Dictionary Value | 辞書（キーと値の組み合わせを持つ変数）の特定のキーに値をセットする |
| Set JSON Value | JSON変数の特定のキーに値をセットする |
| Set Variables to JSON | JSON文字列から複数の変数をまとめて生成する |
| Set Dictionary to JSON | JSON文字列から辞書の中身をまとめて生成する |
| Set Variable to Keychain Password | キーチェーンに保存されているパスワードを取り出して変数にセットする |
| Set Keychain Password to Text | 指定したテキストをキーチェーンのパスワード項目として保存する |
| Set Keychain Password to Variable | 変数の値をキーチェーンのパスワード項目として保存する |
| Filter | 変数の内容を加工する（大文字・小文字変換、URLエンコード、改行の削除、文字数カウントなど） |
| Search and Replace | 変数内の文字列を検索して置換する |
| Search using Regular Expression | 正規表現で変数内の文字列を検索し、マッチした部分やキャプチャグループを別の変数にセットする |
| Substring of Variable or Clipboard | 変数またはクリップボードの一部分を切り出して変数にセットする |
| Split Path | ファイルパスを親フォルダ・ファイル名・拡張子などの要素に分割して変数にセットする |
| Use Variable | 変数の値を使ってテキストのタイピングやペーストなどを実行する |
| Prompt for User Input | 入力ダイアログを表示してユーザーが入力した値を変数にセットする |
| Prompt for Snippet | スニペットを挿入する前にダイアログでユーザーに内容を編集させる |
| Prompt for File | ファイル選択ダイアログを表示して、選ばれたファイルのパスを変数にセットする |
| Prompt With List | リストから1項目を選ばせて、その値を変数にセットする |
| Prompt for Screen Rectangle | 画面上の矩形領域を選択させて、その座標を変数にセットする |
| Custom HTML Prompt | HTMLで作成したカスタムのプロンプト画面を表示してユーザーの入力を受け取る |
| Display Progress | 進捗バーを画面に表示する（長時間かかる処理の進行状況をユーザーに伝えられる） |

よく使うのは「Set Variable to Text」と「Prompt for User Input」、あとは「Search and Replace」と「Search using Regular Expression」くらいで、それ以外は必要になったときにアクション一覧から探せば十分です。

## 変数の種類

Keyboard Maestroの変数にはスコープ（有効範囲）の異なる4種類があります。
変数名の付け方によって種類が決まります。

| 種類 | 変数名の付け方 | スコープ | 永続性 |
| --- | --- | --- | --- |
| グローバル変数 | なし（通常の名前） | すべてのマクロから参照可能 | 再起動後も保持 |
| ローカル変数 | local で始まる（大文字小文字不問） | そのマクロ内のみ | マクロ終了時に消滅 |
| インスタンス変数 | instance で始まる（大文字小文字不問） | そのマクロの実行インスタンス内 | 実行終了時に消滅 |
| パスワード変数 | PWまたはPasswordが名前に含まれる | すべてのマクロから参照可能 | メモリ上のみ（再起動で消滅） |

最近まで知りませんでしたが、Keyboard Maestroにもちゃんとローカル変数の概念がありました。

### グローバル変数

プレフィックスなしの通常の変数名で作成するとグローバル変数になります。
例えば`MyFavoriteEditor`という変数を作ると、すべてのマクロからこの変数を参照・変更できます。

グローバル変数の値はKeyboard Maestroが永続的に保存するので、Macを再起動しても消えません。
複数のマクロで共通して使う設定値（よく使うフォルダパスやアプリ名など）を格納しておくのに向いています。

しかし、すべてのマクロから見える分、意図せず値が上書きされるリスクがあります。
一時的な処理にグローバル変数を使うと、同じマクロが同時に複数実行された場合に値が競合してしまいます。

あとはマクロが増えてくると変数も大量に生まれてしまいます。
多すぎると「Insert Token」で変数を探すときにも大変です。一時的な値の格納にしか使わない場合は避けた方が管理しやすいかもしれません。

### ローカル変数

変数名の先頭に`local`を付けるとローカル変数になります（大文字小文字は区別されません）。
例えば`localCounter`や`local_counter`は、その変数を使っているマクロの中でのみ有効です。

ローカル変数はマクロの実行が終わると自動的に消えるので、一時的な値の保存に適しています。
「ループのカウンタ」「処理中の一時的なテキスト」など、そのマクロ内でしか使わない値はローカル変数にしておくのが良さそうです。

しかし、マクロから別のマクロを「Execute a Macro」で呼び出した場合、呼び出し元のローカル変数は呼び出し先からは見えません。

### インスタンス変数

変数名の先頭に`instance`を付けるとインスタンス変数になります。
ローカル変数と似ていますが、「Execute a Macro」で呼び出したサブマクロにも値が引き継がれる点が異なります。

例えば、メインマクロで`instanceFilePath`に値を設定し、サブマクロ内で`instanceFilePath`を参照すると、メインマクロで設定した値が取得できます。

マクロを分割して部品化する場合に、サブマクロにパラメータを渡す手段として使えます。

### パスワード変数

変数名の先頭か末尾に「Password」または「PW」が付く変数は、パスワード変数として扱われます。
例えば`PasswordMyAccount`や`MyAccountPassword`、`PWMyAccount`や`MyAccountPW`といった命名が対象になります。

パスワード変数の値はディスクに保存されず、メモリ上にのみ存在します。
また、シェルスクリプトやAppleScriptから直接アクセスできないようになっているため、APIキーやトークンなど機密性の高い値を一時的に扱うときに向いています。

私の場合はそこまで機密性の高い情報を扱うマクロを作ったことがありませんが、必要になったときのために覚えておいた方が良さそうです。

## 配列としての活用

Keyboard Maestroの変数は基本的にすべて文字列ですが、区切り文字で分割したリストを配列のように扱えます。

例えば、変数`browserList`に「`chrome,firefox,safari`」というカンマ区切りの値を設定しておくと、使うときに下記のように角括弧で数字を指定することで、配列内の特定の情報を取得できます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_9-2.png)

```
%Variable%browserList[1]%
```

この例では1番目の要素である「`chrome`」が返ります。
インデックスは1から始まり、負のインデックス（`-1`など）を使うと末尾からの指定になり、インデックスに`0`を指定すると配列の要素数が返ります。

ただ、実際によく使うのはインデックス指定よりも「For Each」アクションとの組み合わせで、ループさせて中の要素を順番に取り出して処理させたいときに使います。

区切り文字はデフォルトではカンマですが、改行やタブなど任意の区切り文字を使うこともできます。

また、「For Each」アクションと組み合わせるとリスト内の各要素に対して順番に処理を実行できます。例えば、複数のファイルパスを改行区切りで変数に保存しておき、「For Each」で1つずつ処理します。

## Named Clipboard（名前付きクリップボード）

変数と似た仕組みとして「Named Clipboard（名前付きクリップボード）」があります。

変数がテキスト（文字列）しか格納できないのに対し、Named Clipboardは画像やリッチテキストなど、クリップボードに入るものなら何でも格納できます。

「Set Clipboard to 〇〇」系のアクションで「System Clipboard」以外を選択すると使えます。システムクリップボードを使ってもいいですが、システムクリップボードだと普通にコピーしたときにどんどん上書きされていくので、それとは別で残しておきたいならNamed Clipboardにしましょう。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_10-2.png)

また、Named Clipboardは［環境設定］の［Clipboards］タブで作成・管理もできます。

![](https://webrandum.net/mskz/wp-content/uploads/2026/04/image_11-3.png)

テキストだけを扱うなら変数で十分ですが、画像を一時的に保存して別の場所に貼り付けるような処理ではNamed Clipboardが便利です。

## まとめ

一時的な値には変数名の先頭に`local`を付けるだけで、余計な変数名を変数一覧に出さないようにできますし、変数名が被って予期せぬ挙動になることを防げます。

いままでずっとグローバル変数を使っていて、マクロの最後で変数を`%delete%`で消すようにしていましたが、今後作成するマクロはローカル変数を活用していこうと思います。

ただ、ローカル変数やインスタンス変数はValue Inspectorで表示できないというデメリットもあります。
デバッグツールなら問題無く変数表示もできるので、ローカル変数を使う場合はデバッグツールもうまく活用して、予期せぬ挙動を防いでいきましょう。

[![](https://www.google.com/s2/favicons?domain=webrandum.net)Webrandum![](//webrandum.net/mskz/wp-content/uploads/2026/04/eyecatch.png)Keyboard Maestroの「Macro Debugger」で複雑なマクロのデバッグを行う方法https://webrandum.net/keyboard-maestro-macro-debuggerKeyboard Maestroのマクロが複雑になるほど、想定通りの挙動にならないときに「どこでうまくいっていないのか」「何が原因なのか」が分からなくなります。そんなときのために、Keyboard Maestroにはデバッグ機能が用意されています。私自身いままでデバッグ機能を使わずに何となくでやってきましたが、原因の切り分けや複雑なマクロ作りをラクにするためにも、使い方やどんなことができるか理解しておいた方がいいなと思いました。そこで、今回はKeyboard Maestroのデバッグ機能についてまとめます。Macro DebuggerMacro Debuggerの起...](https://webrandum.net/keyboard-maestro-macro-debugger)