Codex カスタムコマンドの使い方と設定・運用の注意点を整理

Codex カスタムコマンドとは何か

Codexでいうカスタムコマンドは、検索する人によって意味が少しずつ違います。/my-reviewのような新しいスラッシュコマンドをCodexの入力欄に追加したい場合もあれば、同じ依頼文を短い名前で呼び出したい場合、プロジェクトの決まりを毎回説明せずに適用したい場合もあります。この三つは似ていますが、設定する場所と確認方法が異なります。

2026年8月15日時点で、OpenAIの公式リファレンスが説明しているのは、Codexに組み込まれたスラッシュコマンドとCLIサブコマンドです。/を入力して候補から選ぶ方式で、モデル変更、権限変更、レビュー、状態確認、要約などを呼び出します。任意の文字列を新しいスラッシュコマンドとして登録する機能は、同じリファレンスに記載されていません。まずこの境界を押さえると、存在しない設定項目を探し続けずに済みます（出典: OpenAI「Developer commands」）。

一方、再利用したい指示を持つこと自体はできます。リポジトリの規約や確認項目はAGENTS.mdに置き、まとまった作業手順はSkillsとして整理し、短い端末操作はシェルの関数や別名で呼び出す、という分け方です。これらはCodexの標準スラッシュコマンドを増やすものではありませんが、利用者から見れば「決まった依頼をすぐ呼び出せる」ため、カスタムコマンドを探す目的に近い使い勝手を作れます。

先に結論：追加登録ではなく役割分担で考える

「カスタムコマンドを作りたい」と思ったら、最初にその依頼がどこで完結するかを決めます。会話中の状態を変えるだけならスラッシュコマンド、端末から一つの処理を開始するならCLIサブコマンド、プロジェクトの前提を毎回共有するならAGENTS.md、複数の資料や検査を含む長い手順ならSkillsが候補です。

なぜ今、Codexのカスタムコマンドを確認するのか

Codex CLIは、対話画面のスラッシュコマンド、端末から呼ぶサブコマンド、プロジェクト指示、入力欄の編集機能が同時に整備されています。便利になった反面、同じ「コマンド」という言葉で別の仕組みを指しやすくなりました。たとえば/reviewは会話中の操作であり、codex reviewは端末からレビューを始めるCLIサブコマンドです。どちらもレビューに使えますが、入口が違うため、設定方法や失敗時の見方も変わります。

直近では、OpenAI Codexの公式GitHubリリース一覧にrust-v0.148.0-alpha.12がプレリリースとして掲載されています。プレリリースは安定版と分けて扱い、版番号と確認結果を残すことが重要です。特定の版で使えるコマンドを断定する前に、手元のcodex --versionと公式のコマンドリファレンスを照合しましょう（出典: OpenAI Codex「0.148.0-alpha.12」）。

さらに公式のCLIカスタマイズ資料では、テーマ、シェル補完、長いプロンプトを編集する方法が説明されています。つまり、現時点の「カスタム」は、任意のスラッシュ名を増やすより、入力しやすさ、指示の置き場、端末からの呼び出しを整える方向に広がっています。これから使い始める人は、まず標準機能の範囲を確認し、それで足りない部分だけ別の層へ分けると判断しやすくなります（出典: OpenAI「CLI customization」）。

alpha版を試すときの確認ポイント

alpha版を使うなら、普段の作業場所と試験用の場所を分け、最初に版番号、ログイン状態、現在のモデル、入力欄の候補を確認します。変更内容がリリースページに十分書かれていない場合もあるため、見つからない機能を新機能だと断定せず、同じ依頼を安定版と比較するのが安全です。

確認対象は、コマンド名だけではありません。引数の受け付け方、権限の確認が出るタイミング、セッション履歴の扱い、レビュー結果の表示も同じ依頼で見ます。差分が小さいうちに戻せるよう、試したコマンドと結果を短く記録しておくと、版を戻す判断もしやすくなります。

標準スラッシュコマンドの使い方

スラッシュコマンドは、Codexの入力欄に/を入力して候補を開き、目的の項目を選ぶ機能です。公式リファレンスには/permissions、/ide、/model、/reasoning、/review、/status、/plan、/mcp、/compactなどが掲載されています。利用できる項目は画面や版によって変わる可能性があるため、記事や動画で見た名前をそのまま入力するより、現在の候補を起点に確認するのが確実です（出典: OpenAI「Developer commands」）。

会話が進行中でも、コマンドを入力してTabで次のターンに回す使い方ができます。現在の作業を中断せずに、次に使うモデルやレビューを予約できる点が便利です。ただし、処理中の状態を変更するコマンドと、単に情報を表示するコマンドは分けて考えます。操作後は/statusや表示された確認文を見て、意図どおり反映されたかを確認しましょう。

/modelと/reasoningで応答の条件を整える

モデルや推論の強さを変えたいときは、入力欄で/modelや/reasoningを使います。ここで大事なのは、コマンドを実行したことと、次の応答に設定が反映されたことを同じにしないことです。選択後に表示されたモデル名を読み、必要なら/statusで再確認します。

モデルを切り替えた直後は、長い修正を頼む前に小さな読み取り依頼を一つ送ると、設定の反映と出力の傾向を同時に見られます。モデル名だけを見て性能を決めつけず、同じファイル、同じ質問、同じ検査条件で結果を比べると、自分の作業に合う設定を選びやすくなります。

/reviewと/diffで変更を確認する

レビュー目的なら、会話中の/reviewを使う方法と、端末からcodex reviewを実行する方法があります。公式リファレンスでは、未コミットの変更、基準ブランチとの差分、特定コミットの差分などを対象にでき、独自のレビュー指示をプロンプトとして渡す方法も説明されています。対象を曖昧にすると、見てほしい範囲と結果の範囲がずれるため、最初に確認対象を決めます。

レビュー結果を受け取ったら、指摘をそのまま採用せず、該当ファイル、再現条件、検査の結果を一つずつ確認します。レビューを依頼するための文面を毎回同じにしたい場合は、後述するAGENTS.mdのルールや端末側の関数に分けると、標準の/review自体を変更せずに再利用できます。

/statusは「動かない」ときの最初の確認に使う

コマンドが効かない、想定したモデルにならない、応答が遅いと感じたときは、まず/statusでセッションの状態を見ます。現在のモデル、コンテキストの使用状況、レート制限などを確認できるため、指示の問題と環境の問題を切り分ける入口になります。

/statusの結果を見たあとで、同じ依頼を短くして試します。長い依頼だけ失敗するなら文脈量や入力の構成が原因かもしれません。短い依頼でも候補が出ないなら、版、起動場所、利用している画面が公式資料の対象と一致するかを確かめます。

CLIサブコマンドとスラッシュコマンドの違い

スラッシュコマンドは進行中のセッションを操作する入口で、CLIサブコマンドは端末のコマンドラインからCodexの処理を始める入口です。公式のコマンドリファレンスには、通常の対話起動、codex exec、codex review、codex apply、codex resume、codex archive、codex unarchive、codex completionなどが掲載されています。名前が似ているものでも、どこから実行するかを決めてから選ぶ必要があります。

対話中に使うならスラッシュコマンド

設計を相談しながらモデルを変える、いまの会話を要約する、レビューを開始するといった操作はスラッシュコマンド向きです。候補が表示されるため、コマンド名を暗記しなくても使えます。現在の入力と次のターンの扱いを画面で確認できるので、作業の流れを保ったまま小さな変更を加えられます。

ただし、会話の内容に依存した操作であることを忘れないようにします。別のセッションから同じ結果になるとは限らず、現在開いているプロジェクトや選択中のモデルの影響を受けます。毎回同じ条件で再現したい処理は、端末側の呼び出しや明文化した指示へ移すほうが説明しやすくなります。

端末から使うならCLIサブコマンド

端末からレビューを開始する、保存したセッションを再開する、補完設定を生成するといった処理はCLIサブコマンドが向いています。引数を明示でき、入力と結果を端末の履歴で追えるため、同じ対象をもう一度確認する場面で便利です。codex reviewのように、対象を未コミット変更、基準ブランチ、コミットのいずれかで指定できるものもあります。

端末側で短い関数を作る場合も、それはCodexのスラッシュコマンドを追加する設定ではありません。あくまで端末で使う別名です。利用者が混乱しないよう、関数名に対象と目的を含め、実行前に対象を表示し、終了後に結果を確認できる形にします。

カスタム化の本命：AGENTS.mdに定型指示を書く

プロジェクトの前提を毎回伝えることが負担なら、AGENTS.mdが最も扱いやすい置き場です。OpenAIの公式資料によると、Codexは作業前にAGENTS.mdを読み込み、グローバル、プロジェクト、現在のディレクトリに近い場所という順で指示を組み立てます。下位のディレクトリに置いた指示が、より広い範囲の前提を補足できるため、リポジトリ全体の規約と、特定のサービスだけの確認項目を分けて書けます（出典: OpenAI「Custom instructions with AGENTS.md」）。

AGENTS.mdには、何を目指すか、触ってよい範囲、確認に使うコマンド、完了と判断する条件を書きます。長い背景説明や毎回変わる依頼を詰め込むと、必要な指示が埋もれます。短い文で「必須」「避ける」「確認する」を分け、実際の作業で読み返せる量に保つことが大切です。

この方法は、新しいスラッシュコマンドを登録するものではありません。しかし、Codexを開くたびに同じプロジェクトの前提を読み込めるので、「このリポジトリでは必ずこの検査をする」「このディレクトリは読み取りだけにする」といったカスタム指示を安定して適用できます。

最初に固定する四つの項目

最初のAGENTS.mdは、次の四項目に絞ると読みやすくなります。第一に目的です。何を変更する作業なのかを一文で示します。第二に制約です。触らないディレクトリ、採用する言語、互換性の条件を書きます。第三に確認です。テスト、型検査、表示確認など、変更後に必ず行うものを具体的にします。第四に完了条件です。どの結果なら利用者へ返せるのかを明記します。

たとえば、次のように書くと、依頼ごとの説明が短くなります。コマンド名はプロジェクトで実際に使えるものへ置き換え、存在しない検査を例として残さないようにします。

# Project instructions

Purpose:
- 既存の画面とAPIの挙動を保ったまま、小さな修正を行う。

Constraints:
- public/の生成物は直接編集しない。
- 依存パッケージを増やす前に理由を説明する。

Checks:
- 変更した機能のテストを実行する。
- 差分を読み、不要なデバッグ出力がないことを確認する。

Done when:
- テスト結果と残った注意点を最後にまとめる。

グローバルとプロジェクトの指示を分ける

すべてのリポジトリで共通する好みと、特定のプロジェクトだけの規約は分けます。前者をグローバル側、後者をリポジトリのルートへ置くと、別の場所で作業したときに無関係なルールが混ざりにくくなります。さらに特定のサービスだけに必要な確認項目は、そのディレクトリに置いたAGENTS.mdで補足します。

公式資料では、Codexは現在の作業場所までの階層をたどり、より近い場所にある指示を後から結合します。大きなファイルを一つ置くより、全体、アプリ、テストのように関心の範囲で分けるほうが管理しやすい場合があります。ただし、同じ規約を複数箇所へ重ねて書くと、修正漏れが生まれるため、共通部分は上位にまとめます。

AGENTS.mdに置かないもの

AGENTS.mdはプロジェクトの作業ルールを伝える場所です。パスワード、アクセストークン、個人の認証情報、短期間だけ有効な依頼内容を置く場所ではありません。必要な値をファイルへ書き込む設計にすると、共有範囲が広がり、レビューで見落としやすくなります。Codexに伝えるべきなのは、値そのものではなく、どの設定を使い、どの結果を確認するかです。

また、指示ファイルだけで安全性を保証できるとは考えないでください。書き込み範囲やコマンドの許可は、Codexの権限設定、端末の権限、プロジェクトのレビューで別に確認します。AGENTS.mdは判断材料を揃えるものと捉え、重要な変更には人が差分と検査結果を確認します。

Skillsと端末側の呼び出しを使い分ける

定型作業が長くなると、AGENTS.mdだけでは説明が膨らみます。公式のCodexユースケースには、繰り返す作業をSkillsとして保存する考え方や、Codexが使えるCLIを用意する考え方が示されています。プロジェクト全体の前提はAGENTS.md、特定の作業を呼び出すまとまりはSkills、端末から対象を選び処理を始める短い入口はシェル関数、と三つに分けると責任範囲が明瞭です（出典: OpenAI「Codex use cases」）。

Skillsへ移す目安は、入力資料、判断手順、出力形式、確認項目が一つのまとまりになったときです。たとえば、変更差分を読み、関連テストを選び、結果を要約する作業は、毎回同じ順で頼みたい一方、プロジェクトごとの対象は変わります。共通部分をSkillに置き、対象や例外だけをその場の依頼で渡すと、指示ファイルが過度に長くなりません。

長い依頼はSkill、短い入口は端末関数

Skillは、複数のファイルを読む、条件に応じて確認先を変える、結果を定めた形式でまとめる、といった長めの作業に向いています。対して端末関数は、codex review --uncommittedのように引数が少なく、処理の入口が明確な場合に向いています。どちらを使う場合も、対象、前提、成功条件を明示し、結果を人が確認できるようにします。

端末関数の例は次のとおりです。これはPowerShellで使う別名であり、Codexの入力欄に新しい/review-localを追加するものではありません。名前から対象が分かり、実行する処理が一つなので、短い呼び出しとして管理できます。

function Invoke-CodexLocalReview {
    codex review --uncommitted
}

関数に処理を詰め込むほど、何を変更したのか分かりにくくなります。レビュー対象の指定、モデルの選択、結果の保存などを追加する前に、利用者が端末から実行したときに何が起こるかを説明できるか確認します。説明できない処理は、SkillやAGENTS.mdへ移す前に小さく分けると保守しやすくなります。

公式の範囲と自分で足す範囲を明記する

記事やチーム内の手順で「カスタムコマンド」と呼ぶときは、標準機能、プロジェクト指示、Skills、端末関数のどれを指すのかを最初に書きます。これを省くと、読者は/my-commandが使えると誤解し、候補に出ない理由を設定の不具合だと思ってしまいます。

説明の中では、標準のコマンド名を公式リファレンスへのリンク付きで示し、自分で用意するファイルや関数には別名を付けます。公式に書かれていない機能を、版番号だけを根拠に利用できると断言しないことも重要です。変更が速い部分は、確認日と参照先を残しておくと更新時に差し替えやすくなります。

実際にカスタムコマンドを整える手順

ここまでの区別を踏まえ、検索語としての「Codex カスタムコマンド」を、自分の作業で使える入口へ変換します。最初から複数の仕組みを作るのではなく、手動で一度最後まで実行し、入力と結果を確認してから再利用の層を選びます。以下は、標準コマンドの確認、指示の整理、短い呼び出しの作成、結果の検証という順序です。

大事なのは、短縮する前の作業を基準として残すことです。何を入力し、どのファイルを対象にし、どの検査を通れば完了なのかが分からないまま入口だけを短くすると、失敗したときに原因を追えません。最初の一回は少し手間をかけ、再利用後に同じ結果へ近づけるための比較材料を作ります。

Step 1: 目的を一文にする

まず「誰が、何を対象に、どの結果を得たいか」を一文で書きます。「レビューする」だけでは対象と完了条件が曖昧です。「現在の未コミット差分から、動作を変える恐れのある指摘を見つけ、該当ファイルと確認方法をまとめる」のように、入力と出力を入れると入口を選びやすくなります。

この一文で現在の会話だけに必要な操作ならスラッシュコマンド、端末から何度も呼ぶならCLIサブコマンド、プロジェクト全体に共通するならAGENTS.mdと判断します。判断を先に置くことで、存在しないスラッシュコマンドの登録方法を探す時間を減らせます。

Step 2: 標準コマンドで小さく試す

次に、現在のCodexで/を入力し、候補に目的に合う標準コマンドがあるか確認します。レビューなら/review、状態なら/status、モデルなら/modelというように、標準機能で足りる範囲を先に使います。候補にない場合は、公式リファレンスと手元の版番号を照合し、未掲載の名前を無理に入力しません。

小さな対象で試すのは、結果の比較を簡単にするためです。変更範囲を一つのファイルに限定し、依頼文を短くし、出力と検査結果を保存します。標準コマンドだけで目的を満たせるなら、追加の指示や端末関数を作らないほうが、版が変わったときの確認箇所も少なくなります。

Step 3: 共通部分をAGENTS.mdへ移す

同じ前提を二回以上伝えたら、依頼文から共通部分を取り出します。たとえば「差分を最小にする」「既存のテストを先に読む」「結果に検査名を含める」は、個別の変更内容ではなくプロジェクトの作業ルールです。これらをAGENTS.mdへ移し、今回だけの対象ファイルや期限は会話の依頼に残します。

移した後は、新しいセッションで同じ小さな依頼を行い、Codexが指示を読み込んだかを確認します。指示が適用されたかは、単に回答の文章を見るだけでなく、ファイルの差分、実行された検査、残った注意点で判断します。期待した前提が反映されなければ、ファイルの場所、名前、内容量、現在の起動ディレクトリを確認します。

Step 4: 端末関数やSkillへ分ける

依頼の入口を短くしたい場合は、対象を明示する端末関数を用意します。資料の読み込みや複数の判断を含むならSkillとして整理し、端末関数から大きな処理を隠しすぎないようにします。作る前に、手動で実行したコマンド、渡した入力、期待した結果をメモしておくと、短縮後の挙動を比較できます。

この段階でも、Codexのスラッシュコマンドを増やしたと表現しないことが大切です。端末関数ならPowerShellの関数名、SkillならSkill名、プロジェクト規約ならAGENTS.mdというように、実際の呼び出し方を説明します。名前と入口を正しく伝えるだけで、利用者が迷う場面は大きく減ります。

Step 5: 失敗時の戻り方を確認する

最後に、対象を空にした場合、検査が失敗した場合、権限確認が必要になった場合に、どの表示が出るかを確かめます。成功だけを確認すると、次に同じ入口を使ったときに失敗理由を判断できません。入力を小さくして再試行する方法、標準コマンドへ戻る方法、端末関数を外して手動で呼ぶ方法を決めておきます。

結果の確認では、処理が終了したことと、目的を満たしたことを分けます。レビューが終わっても修正が必要かもしれず、テストが通っても表示確認が残るかもしれません。作業の最後に「実行したもの」「確認できたもの」「未確認のもの」を簡潔に並べれば、カスタム化によって見えなくなった確認工程を防げます。

使えない・期待と違うときの切り分け

カスタムコマンドを用意したのに候補へ出ない、AGENTS.mdが読まれない、端末関数は動くが結果が期待と違う、といった問題は、仕組みの境界を確認すると解決しやすくなります。最初から設定を増やすのではなく、標準コマンド、版番号、起動場所、入力内容の順に一つずつ変えます。

切り分けの記録には、試した入口、対象、表示されたエラー、最後に確認できた結果だけを残します。複数の設定を一度に変更すると、どの変更が影響したのか分からなくなるためです。標準機能で再現するかを先に確かめ、次に指示ファイル、最後に端末側の短縮を調べると、確認の範囲を小さく保てます。

候補に新しいスラッシュ名が出ない

/my-commandのような名前が候補に出ない場合、まず現在の公式リファレンスに掲載されている標準コマンドか確認します。掲載されていない名前を設定ファイルへ追加する方法が公式に案内されていないなら、入力欄の不具合と決めつけず、AGENTS.md、Skill、端末関数のいずれかへ目的を移します。これが、カスタムコマンドという検索語を実際の作業へつなぐ最短ルートです。

ブラウザや別のアプリのコマンドメニューと、Codex CLIの候補を混ぜないことも重要です。OpenAIのリファレンスは、ChatGPTのWeb画面、デスクトップアプリ、CLIで利用できるコマンドを分けて説明しています。どの画面を使っているかを確認し、別の画面向けの手順を適用しないようにします。

AGENTS.mdが反映されない

AGENTS.mdが反映されないときは、ファイル名、配置場所、起動したディレクトリを確認します。公式資料では、グローバルの指示とプロジェクトの指示を階層で読み込むため、似た名前の上書きファイルや、現在地より上にある別のルールが影響する場合があります。空のファイルや、対象ディレクトリから外れた場所に置いたファイルも読み込まれません。

確認用の依頼は短くします。「読み込んだ指示の出所を示してください」と頼み、表示されたファイル名と実際の配置を比べます。その後、目的の作業を小さく一つだけ依頼し、期待した制約が守られたか差分で確認します。長い指示が途中で切れているときは、共通ルールを上位、専門ルールを下位へ分けます。

端末関数は動くが結果が一定しない

端末関数が起動しても結果が一定しない場合、関数の中で対象を暗黙に決めていないか確認します。現在のディレクトリ、未保存のファイル、選択されたモデル、会話履歴などが毎回違えば、同じ関数名でも入力が変わります。関数の開始時に対象を表示し、必要な引数を明示し、終了時に出力を確認する形へ直します。

それでも差が出るなら、関数を外して同じCLIサブコマンドを手動で実行します。手動では再現するのに関数だけ違うなら、引数の渡し方や文字コードを見直します。手動でも違うなら、モデル、版、対象ファイル、セッションの状態を一つずつ揃えます。短い入口は便利ですが、結果の根拠を隠さないことが長く使うための条件です。

まとめ：Codexのカスタムコマンドは入口を分けて作る

Codexのカスタムコマンドを調べるとき、まず覚えておきたいのは、標準スラッシュコマンドを任意の名前で増やす手順が公式リファレンスに示されているわけではないことです。/model、/review、/statusなどの組み込み機能はそのまま使い、プロジェクトの共通ルールはAGENTS.md、長い定型作業はSkills、短い端末操作はPowerShellなどの関数へ分けます。

この分け方なら、何がCodex本体の機能で、何が利用者の設定なのかを説明できます。標準コマンドの候補が出ないときも、存在しない登録方法を探し続けるのではなく、同じ目的を別の層で実現できます。版を更新したときは、公式のコマンドリファレンスと手元の版番号を照合し、小さな対象で入力、結果、検査を順に確認してください。

最後に、カスタム化の価値は呼び出し名を短くすることだけではありません。目的、制約、確認方法を整理し、誰が使っても同じ入口から同じ判断材料を得られるようにすることが本質です。Codex CLIの標準機能と自分の指示を正しく分ければ、変更が続く環境でも、必要な作業を迷わず再利用できます。