Codexのカスタムコマンドとは？種類や活用例・作り方も解説

Codexを使い始め「カスタムコマンド」という言葉を見聞きする機会が増え、どんなものか気になっている人は多いですよね。

そもそもコマンドが何なのかあいまいな人もいるはず。

そこでこの記事ではできることも交え、Codexにおけるカスタムコマンドの特徴を解説します。使い方や活用法も紹介するので、ぜひ参考にしてください。

Codexのカスタムコマンドとは？

Codexのカスタムコマンドとは、ユーザーが独自に定義した指示をスラッシュ（/）付きのコマンドとして呼び出せる機能です。

たとえば「/review」と入力するだけで、あらかじめ設定したコードレビュー用のプロンプトや手順を実行できます。毎回同じ指示を入力する必要がなくなるため、定型作業の効率化に役立ちます。

ここからはカスタムコマンドの違いや注意点を、3つにまとめて解説します。

標準コマンドとの違い

標準コマンドは、Codex CLIにあらかじめ組み込まれている操作用のコマンドです。一方、カスタムコマンドはユーザーが自由に内容を定義できます。

標準コマンドは「Codexが標準で提供している操作」を実行するためのものです。代表的な標準コマンドは次のとおりです。

標準コマンドの内容を変更したり、新しい動作を追加したりすることはできません。一方、カスタムコマンドは自分の開発フローや業務に合わせて自由に定義できる点が大きな違いです。

Codexのコマンドを詳しく知りたい人は、次の記事を参考にしてください。

カスタム指示との違い

カスタム指示は、Codexが常に参照するルールや方針を設定する仕組みです。カスタムコマンドとは役割が異なります。

設定する「AGENTS.md」などのファイルにルールを記述し、その内容をCodexが継続的に参照する運用が推奨されています。

たとえばAGENTS.mdに次のような内容を書くと、Codexは基本的にそのルールに従って動作します。

“`
テストは必ずpytestで実行する
コミットメッセージは日本語で書く
本番環境のファイルは編集しない
“`

一方、カスタムコマンドは特定の操作を必要なときだけ呼び出す仕組みです。たとえば「/review」を実行したときだけ、レビュー用のプロンプトや処理が実行されます。

つまり、カスタム指示は「常に適用されるルール」、カスタムコマンドは「必要なときだけ実行する定型処理」と考えると違いを理解しやすいでしょう。

公式では非推奨化されている

カスタムコマンド機能は、OpenAIの公式ドキュメントで非推奨（deprecated）と明言されています。

現在は、カスタムスラッシュコマンドよりも、AGENTS.mdによる指示管理を利用することが推奨されています。これは、プロジェクト全体のルールを一元管理しやすく、継続的な運用にも適しているためです。

非推奨となった背景には、次のような理由があります。

現時点でもカスタムコマンドは動作しますが、新しく環境を構築する場合は、将来性を考慮してAGENTS.mdを活用した運用を検討するのがおすすめです。

Codexのカスタムコマンドでできること

カスタムコマンドを使うと、繰り返し発生する作業を1つのコマンドに集約して即座に実行できます。

手動で毎回プロンプトを入力する必要がなくなるため、作業時間の短縮だけでなく、入力ミスや指示漏れの防止にもつながります。とくに開発現場で頻繁に行う定型作業との相性が良いです。

カスタムコマンドで実現できる代表的な作業は次のとおりです。

たとえば「/review src/main.py」と入力したとします。src/main.pyに対して事前に定義したレビュー観点で自動チェックが走る流れです。毎回レビュー観点を入力する必要がないため、作業を効率化できます。

また、チーム内で同じカスタムコマンドを共有すれば、メンバー全員が同じ品質基準でレビューやテストを実行可能です。

ただし、前述のとおり、カスタムコマンドは現在OpenAI公式で非推奨となっています。これから新たに環境を構築する場合は、同様のルールや定型指示をAGENTS.mdで管理する方法を検討しましょう。

Codexでできることを詳しく知りたい人は、次の記事を参考にしてください。

Codex・カスタムコマンドの作り方

カスタムコマンドは、Markdownファイルを所定のフォルダに配置するだけで作成できます。

ここからはカスタムコマンドの作成手順を、3ステップにまとめて解説します。

1.コマンドファイルを作成する

カスタムコマンドの作成は、`.codex/commands/`フォルダにMarkdownファイルを配置することで作成できます。

ファイル名がそのままコマンド名になります。たとえば「review.md」を作成すると、「/review」として呼び出せる仕組みです。

具体的な手順は次のとおりです。

1. プロジェクトのルートディレクトリに`.codex/commands/`フォルダを作成する
2. フォルダ内にMarkdownファイルを作成する（例：`review.md`）
3. ファイルにCodexへの指示内容を記述する

`review.md`の記述例は次のようになります。

“`
以下の観点でコードをレビューしてください。

変数名が意味のある名前になっているか
エラーハンドリングが適切か
不要なコメントが残っていないか
パフォーマンスに問題がある箇所はないか

問題がある場合は修正案も提示してください。
“`

保存後は、Codex CLI上で「/review」と入力するだけで、このプロンプトを呼び出せます。

なお、複数のプロジェクトで共通して使いたい場合は、ホームディレクトリの`~/.codex/commands/`に配置してください。プロジェクト専用コマンドとグローバルコマンドを用途に応じて使い分けることが可能です。

なお、複数のプロジェクトで共通して利用したい場合は、ホームディレクトリの~/.codex/commands/に配置できます。プロジェクト専用のコマンドとグローバルコマンドを用途に応じて使い分けることが可能です。

2.引数を定義して渡す

カスタムコマンドでは、`$1`や`$2`といったプレースホルダーで引数を受け取れます。

引数を使うと、同じコマンドで異なるファイルや条件を指定できます。そのため、毎回コマンドを作り直す必要はありません。

たとえば`review.md`を次のように記述します。

“`
$1 のコードを以下の観点でレビューしてください。

変数名が意味のある名前になっているか
エラーハンドリングが適切か
$2 に関連する処理が正しく実装されているか

問題がある場合は修正案も提示してください。
“`

この状態で「/review src/main.py ユーザー認証」と入力すると、`$1`に「src/main.py」、`$2`に「ユーザー認証」が渡され、それぞれの内容がプロンプトに反映されます。

引数を活用する際のポイントは次の3つです。

引数を省略した場合、意図したプロンプトにならないことがあります。必須の引数がある場合は、コマンドの説明やコメントで利用方法を明記しておくとよいでしょう。

3.動作を確認する

コマンドファイルの作成後は、Codex CLIを起動して動作を確認してください。

確認手順は次のとおりです。

1. ターミナルでプロジェクトのルートディレクトリに移動する
2. `codex`コマンドでCodex CLIを起動する
3. 作成したカスタムコマンド（例：`/review src/main.py`）を実行する
4. 出力結果が意図した内容になっているか確認する

確認時にチェックすべき観点は次の3点です。

もし「Unknown command」と表示される場合は、ファイル名や配置場所が正しいかを確認してください。とくに`.codex/commands/`フォルダの場所やディレクトリ構成の誤りが原因となるケースが多いです。

動作確認まで完了すれば、カスタムコマンドの作成は終了です。

Codexのカスタムコマンドが動かないときの対処法

カスタムコマンドが動かない場合、ファイルの配置場所や設定内容に原因があるケースがほとんどです。

よくあるトラブルと対処法を次の表にまとめました。

症状	原因	対処法
Unknown commandと表示される	ファイルの配置場所が間違っている	`.codex/commands/`または`~/.codex/commands/`にファイルがあるか確認する
コマンド名が認識されない	ファイル名が適切でない	ファイル名や拡張子（.md）が正しいか確認する
引数が反映されない	プレースホルダーの記述が誤っている	`$1`や`$2`などの記述や、コマンド実行時の引数を確認する
意図しない出力になる	プロンプトの内容が曖昧	指示内容を具体的に記述する
コマンド自体が使えない	Codex CLIのバージョンが古い	`npm update @openai/codex`で最新版に更新する
標準コマンドと競合する	標準コマンドと同じ名前を使用している	ファイル名を別のコマンド名に変更する

上記を確認しても解決しない場合は、Codex CLIの再インストールを試してみてください。設定ファイルの不整合やインストール時の問題が原因となっている場合があります。

また、同様の事象が報告されていないか、Codex CLIの公式GitHubリポジトリのIssuesページを確認するのも有効です。カスタムコマンドは非推奨機能であり、CLIのバージョンアップで挙動が変わる可能性があるため注意が必要です。

なお、今後も継続的に利用する環境を構築するのであれば、AGENTS.mdへの移行を検討することをおすすめします。AGENTS.mdは公式に推奨される仕組みのため、将来的な互換性や保守性の面でも安心して利用できます。

まとめ

本記事では、Codexのカスタムコマンドの作成方法と運用上の注意点を解説しました。

カスタムコマンドは、コードレビューやテスト生成、ドキュメント作成など、繰り返し行う作業をスラッシュコマンドとして登録し、効率化できる機能です。引数を組み合わせれば、対象ファイルや処理内容を柔軟に切り替えられるため、定型作業の自動化やチーム内での運用ルールの統一にも役立ちます。

まずは`.codex/commands/`にMarkdownファイルを配置してスラッシュコマンドを試してみましょう。