MemoryLake
すべての記事に戻る
Tutorial2026年11月19日·11 分で読了

コンテキストを失わずに Codex フックを Claude Code へ移行する方法 (2026年)

あなたのチームには、実際に機能している Codex フックがいくつかあるはずです。実行前にすべてのシェルコマンドをポリシースクリプトと照合するもの、チャット開始時にセッションノートを読み込むもの、終了前にエージェントにテスト実行を促すものなどです。ワークフローに Claude Code を導入し、/import codex を使用して指示ファイルやスキルを取り込んだものの、最初のセッションではそれらのフックが一切動作しないことに気づくでしょう。

これは予想通りの動作です。Claude Code のコマンドリファレンスでは、/import が取り込む設定として「指示ファイル、MCP サーバー、コマンド、サブエージェント、スキル」を挙げています。フックはこのリストに含まれていません。これらを移行するには手動の手順が必要です。

幸いなことに、これら2つのツールはフックを非常に似た形式で定義しているため、作業のほとんどは書き換えではなく「翻訳」です。Claude Code のドキュメントでは、フックイベント、「発火タイミングをフィルタリングするマッチャーグループ」、そして1つ以上のハンドラーという3つのネストレベルが説明されています。Codex のドキュメントも、これと同じ3つのレベルを定義しています。

このガイドでは、各ツールにおけるフックの保存場所、変更なしで引き継げるもの、翻訳が必要なもの、片方にしか存在しないイベント、信頼設定の仕組み、コンテキスト読み込みフックを失わずに移行する方法、そしてステップバイステップの手動移行手順について解説します。

各ツールにおけるフックの定義

Codex のドキュメントでは、フックを「Codex の拡張フレームワーク。エージェントのループ中にスクリプトや MCP ツールを実行できるもの」と説明しています。例として「チャットを要約して永続的な記憶(memory)を自動作成する」「チャットのターン終了時にカスタムバリデーションを実行し、標準を強制する」などが挙げられています。

Claude Code のドキュメントでは、フックは「JSON 設定ファイルで定義され」、イベント、マッチャーグループ、ハンドラーとして構成されると述べています。ハンドラーには、シェルコマンド、HTTP エンドポイント、MCP ツール、プロンプト、またはエージェントを指定できます。

Codex がサポートするハンドラータイプはより限定的です。ドキュメントには「command と mcp_tool ハンドラーがサポートされています。prompt と agent ハンドラーは解析されますがスキップされます」とあります。Claude Code はこれらすべてをサポートしているため、Codex で実際に動作しているすべてのハンドラーは、Claude Code に対応するタイプが存在します。

フックの保存場所

Codex では、 フックは hooks.json ファイルに記述するか、config.toml 内にインラインで記述します。ドキュメントに記載されている hooks.json の場所は以下の通りです:

  • システム:macOS および Linux では /etc/codex/hooks.json。
  • ユーザー:$CODEX_HOME/hooks.json(CODEX_HOME が未設定の場合は ~/.codex/hooks.json)。
  • 信頼されたプロジェクト:.codex/hooks.json。

Codex は、有効化されたプラグインに同梱されているフックも読み込みます。1つのレイヤーで両方のファイルが使用されている場合、ドキュメントには「Codex は両方を読み込み、起動時に警告を表示します。1つのレイヤーにつき1つの形式を推奨します」とあります。

Claude Code では、 フックは設定ファイルに記述します。ドキュメントの表には主な場所がリストされています:

  • ~/.claude/settings.json:すべてのプロジェクト用。
  • .claude/settings.json:単一プロジェクト用。「リポジトリにコミット可能」。
  • .claude/settings.local.json:単一プロジェクト用、ローカルに保持。
  • 管理ポリシー設定、プラグイン、スキルまたはサブエージェントのフロントマター。

したがって、Codex のユーザーレベルの hooks.json は ~/.claude/settings.json に、プロジェクトの .codex/hooks.json は .claude/settings.json のトップレベルの hooks キーの下に最も近くマッピングされます。

変更なしで引き継がれるもの

いくつかの要素は翻訳の必要がありません。

構造: イベント名、マッチャーグループ、およびグループごとのハンドラーリスト。

共通のイベント名: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, Stop は両方のツールのリファレンスに登場します。

SessionStart のソース: Codex は startup, resume, clear, compact, fork を挙げています。Claude Code の SessionStart マッチャー表にも、これらと同じ5つの値がリストされています。

共通の入力フィールド: 両ツールとも、session_id, transcript_path, cwd, hook_event_name, permission_mode を含む JSON を標準入力(stdin)経由で送信します。

終了コード 2: Codex では、いくつかのイベントで「終了コード 2 を使用し、ブロック理由を stderr に書き込む」ことができます。Claude Code も、サポートされているイベントにおいて終了コード 2 をブロックシグナルとして扱い、イベントごとの挙動をドキュメント化しています。

デフォルトのタイムアウト: Codex はほとんどのフックで 600 秒を使用します。Claude Code もコマンドフックのデフォルトとして 600 をリストしています。

翻訳が必要なもの

マッチャー(Matchers): 両ツールともマッチャーを使用してツール名や開始ソースでフィルタリングしますが、評価方法が異なります。Codex はマッチャーを「正規表現文字列」として扱います。Claude Code は、英数字と少数のセパレーターのみで構成されるマッチャーは完全一致の名前として扱い、それ以外はアンカーなしの JavaScript 正規表現として扱います。Codex の ^apply_patch$ のようなマッチャーは Claude Code でも正規表現として機能しますが、内部のツール名を変更する必要があります。

ツール名: Codex のシェルツールは Bash としてマッチし、これは Claude Code でも同じ名前です。ファイル編集は異なります。Codex では apply_patch は apply_patch, Edit, または Write としてマッチさせることができます。Claude Code では、編集ツールは Edit や Write などの名前でマッチします。Codex フックですでに Edit|Write を使用している場合はそのまま引き継げますが、apply_patch を使用している場合は変更してください。

MCP ツール名: 両ツールとも例の中で mcp__server__tool パターンを使用しているため、MCP マッチャーはそのまま引き継げます。サーバー名が両方のツールで同じであることを確認してください。

スクリプトパス: Codex の例では、.codex/hooks/ 下のパスを使用して Git 経由でプロジェクトスクリプトを参照しています。Claude Code はこれに代わるプレースホルダー ${CLAUDE_PROJECT_DIR}(セッションが開始されたプロジェクトルート)を提供しています。スクリプトを .claude/hooks/ に移動する場合は、パスも更新してください。

model フィールド: Codex は model を共通入力フィールド(Codex 固有の拡張)としてリストしています。Claude Code では「SessionStart フックのみが model フィールドを受け取ることができ、Claude Code は常にそれを含めるとは限らない」としています。すべてのイベントでモデルを読み取る Codex スクリプトには、フォールバックが必要です。

ターン ID: Codex はターン(turn)スコープのフックに turn_id を追加します。Claude Code の共通フィールドには、処理中のユーザープロンプトを識別する prompt_id が含まれます。ターン ID をキーにしているロギングスクリプトは調整が必要です。

コンテキスト制限: Codex の additionalContextLimit フィールドは、Codex が全文をディスクに保存する前にフックが送信できるコンテキスト量を制御します。Claude Code のハンドラーフィールド表にはこのフィールドがないため、ハンドラーをコピーする際に削除してください。

片方にしか存在しないイベント

Codex には、Claude Code のフックリファレンスに同じ名前で含まれていないイベントが3つあります:PreModelRequest, PostModelRequest, Interrupt です。Codex は最初の2つを「各モデルリクエストの試行ごと」に実行し、Interrupt はアクティブなターンを中断したときに実行します。

これらに依存している場合は、Claude Code で最も近いイベントを探すか、その挙動が引き継がれないことを受け入れる必要があります。逆に Claude Code には、PostToolUseFailure, Notification, FileChanged, PreModelSwitch など、Codex にはない多くのイベントがあります。移行は、これらの新しいイベントがより適していないか確認する良い機会です。

各ツールにおける信頼設定の仕組み

Codex はフックを個別に信頼します。ドキュメントには「管理されていないフックを実行する前に、Codex は正確なフック定義を確認し信頼することを要求します。Codex はフックの現在のハッシュに対して信頼を記録するため、新規または変更されたフックは確認対象としてマークされ、信頼されるまでスキップされます」とあります。

Claude Code は代わりにワークスペースの信頼を確認します。対話型セッションでは、「フォルダのワークスペース信頼ダイアログを受け入れるまで、自分の ~/.claude/settings.json を含むすべての設定ファイルからのフックを保留」します。-p または SDK セッションでは、「フォルダを信頼済みとして扱い」ます。

Claude Code の /hooks メニューは、各フックとそのソースを表示する読み取り専用のブラウザです。移行後にこれを使用して、すべてのフックが期待通りの場所に配置されたか確認してください。

プラグイン、管理フック、無効化されたフック

すべてのフックが自分で移動すべきものとは限りません。

プラグインフック: これらはプラグインと共に移動します。Codex では、有効なプラグインはマニフェスト、またはデフォルトでプラグインルートの hooks/hooks.json を通じてフックを提供できるとしています。Claude Code もプラグイン内で同じファイル名を使用し、ドキュメントには「プラグインが有効になると、そのフックはユーザーおよびプロジェクトのフックとマージされる」とあります。フックがプラグイン由来の場合は、フックをコピーするのではなく、そのプラグインの Claude Code 版をインストールしてください。

管理フック: これらは管理者によって管理されます。Codex は、システム、MDM、クラウド、または requirements.toml ソースからのフックを管理対象(managed)かつポリシーによって信頼済みとしてマークします。Claude Code には管理ポリシー設定があり、ユーザー、プロジェクト、ローカル、プラグインのフックをブロックする allowManagedHooksOnly 設定があります。管理フックを自分で再現する前に、管理者に確認してください。

フックの無効化: 方法が異なります。Codex ではフックはデフォルトで有効で、config.toml の機能フラグでオフにします。Claude Code では、設定ファイルの disableAllHooks スイッチがドキュメント化されていますが、これは管理設定外から管理フックを無効にすることはできません。

コンテキスト読み込みフックの移行

コンテキストを読み込む SessionStart フックは、エージェントが最初のターンから何を知っているかを決定するため、最も正確に移行する価値があります。

Codex では、「標準出力(stdout)のプレーンテキストは追加の開発者コンテキストとして追加」され、JSON の additionalContext フィールドも同様に機能します。また、Codex はセッションを要約(compact)した後に compact にマッチする SessionStart フックを実行するため、要約後もコンテキストが戻ってきます。

Claude Code も同様に動作します。ドキュメントによると、SessionStart において「Claude Code は標準出力のプレーンテキストを、Claude が参照・操作できるコンテキストとして追加」します。その compact ソースは「自動または手動の要約」の後に発火します。

Claude Code は、そもそも何がフックにふさわしいかについてもアドバイスしています。SessionStart セクションでは、このイベントは「既存のイシューやコードベースへの最近の変更など、開発コンテキストを読み込むのに便利」とした上で、「スクリプトを必要としない静的なコンテキストには、CLAUDE.md を使用してください」と述べています。

したがって、Codex フックが毎回同じ規約を出力するだけのものであれば、移行を機にそのテキストを CLAUDE.md に移動し、フックは動的に変化するコンテキストのために残しておくのが良いでしょう。どの Claude Code フックがコンテキストを追加できるか、またいつ CLAUDE.md が適しているかについては、Claude Code フックのガイドで詳しく解説しています。

よくある間違い

/import codex がフックも取り込むと期待すること: ドキュメント化されたリストに含まれるのは、指示ファイル、MCP サーバー、コマンド、サブエージェント、スキルのみです。

hooks.json を .claude/ にコピーすること: Claude Code でドキュメント化されている場所は、設定ファイル、プラグイン、およびスキルやサブエージェントのフロントマターです。

マッチャーに apply_patch を残すこと: Claude Code の編集ツールは異なる名前を使用します。

すべてのイベントで model を読み取ること: Claude Code では、SessionStart のみがそれを受け取ることができます。

静的な規約をフックに残すこと: Claude Code は静的なコンテキストには CLAUDE.md を推奨しています。

手動移行の手順

ステップ 1: Codex フックをリストアップする

Codex CLI で /hooks を開き、各フックのソース、イベント、マッチャー、コマンドをメモします。

ステップ 2: Claude Code の設定ファイルを選択する

個人のフックには ~/.claude/settings.json を、共有プロジェクトのフックには .claude/settings.json を使用します。

ステップ 3: 構造をコピーする

hooks キーの下に各イベントとマッチャーグループを再現し、TOML 形式のフックがあれば JSON に変換します。

ステップ 4: マッチャーとパスを翻訳する

apply_patch を置き換え、正規表現マッチャーを確認し、スクリプトパスを ${CLAUDE_PROJECT_DIR} に向けます。

ステップ 5: Codex 固有のフィールドを読み取るスクリプトを調整する

model と turn_id にフォールバックを追加し、additionalContextLimit を削除します。

ステップ 6: 静的なコンテキストを CLAUDE.md に移動する

変化するコンテキストのためにフックを残し、固定の規約は CLAUDE.md に記述します。

ステップ 7: フォルダを信頼して検証する

ワークスペース信頼ダイアログを承認し、/hooks を確認して各イベントを一度トリガーします。

より良い方法:フックが強制するルールを一箇所にまとめる

フックはルールを強制し、コンテキストを読み込みます。なぜコマンドがブロックされるのか、どのポリシーがチェックを実装しているのか、セッションノートに何を含めるべきかといった「理由」は、プロジェクトのコンテキストです。フックをツール間で移動させるとスクリプトは引き継がれますが、その背後にある推論は誰かの記憶の中にしか残らないことがあります。

MemoryLake は、ポリシー、規約、チェックの理由などのプロジェクトコンテキストを一箇所で管理し、ChatGPT、Claude Code、Codex など接続したアシスタントから利用可能にする記憶(memory)レイヤーです。

エントリはあなた自身の言葉で記述します。hooks.json ファイル、設定ファイル、フックスクリプト、Codex や Claude Code のセッション、あるいはベンダーのストレージから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。フックは OpenAI や Anthropic が説明している通りに動作します。

ステップ 1: API キーを作成する

サインインしてダッシュボードからキーを生成します。他の認証情報と同様に、リポジトリの外に保存してください。

API キー画面を表示している MemoryLake コンソール。エージェントで使用するために新しいキーが作成されコピーされている
API キー画面を表示している MemoryLake コンソール。エージェントで使用するために新しいキーが作成されコピーされている

ステップ 2: 最初の記憶(memory)をアップロードする

手動移行のステップ 1 でリストアップしたフックから始めましょう。それぞれについて、何を強制しているのか、そしてその理由を書き留めます。1つのエントリにつき1つのフックを記述します。

最初のドキュメントがアップロードされた MemoryLake ワークスペース。各ファイルが検索可能な記憶(memory)としてリストされている
最初のドキュメントがアップロードされた MemoryLake ワークスペース。各ファイルが検索可能な記憶(memory)としてリストされている

ステップ 3: AI とエージェントを接続する

Claude Code、Codex、および使用している他のアシスタントを接続します。どのツールがフックを実行しても、同じ理由(reasoning)を参照できるようになります。

記憶(memory)レイヤーに接続可能な AI クライアントとエージェントフレームワークがリストされている MemoryLake の統合画面
記憶(memory)レイヤーに接続可能な AI クライアントとエージェントフレームワークがリストされている MemoryLake の統合画面

実践で何が変わるか

第一の違いは、翻訳が容易になることです。フックの目的が明文化されていれば、名前が異なっていても適切な Claude Code イベントを選択できます。

第二に、重複が減ります。変化しないコンテキストは、毎セッション出力するスクリプトではなく、CLAUDE.md に一度記述するだけで済みます。

第三に、ツール間での一貫性です。Claude Code でも Codex でも、同じポリシーと理由を利用できるようになります。

Codex フックを Claude Code に移行するためのベストプラクティス

まず棚卸しをする。 Codex で /hooks を使用してすべてのソースを確認します。

ファイルを意図的にマッピングする。 ユーザーフックは ~/.claude/settings.json へ、プロジェクトフックは .claude/settings.json へ。

ツール名を翻訳する。 apply_patch は Edit または Write になります。

スクリプトには ${CLAUDE_PROJECT_DIR} を使用する。 これはセッションが開始されたプロジェクトルートを指します。

Codex 固有のイベントを確認する。 PreModelRequest, PostModelRequest, Interrupt には対応策が必要です。

静的なテキストは CLAUDE.md へ移動する。 フックは変化するコンテキストのために残します。

スクリプト実行前に .claude/ を確認する。 -p セッションではフォルダが信頼済みとして扱われます。

結論

Claude Code の /import codex は指示ファイル、MCP サーバー、コマンド、サブエージェント、スキルを取り込みますが、フックはそのリストに含まれていません。手動での移行は、両ツールが同じ3つのレベル(イベント、マッチャーグループ、ハンドラー)を使用しているため、主に翻訳作業となります。ほとんどのイベント名、SessionStart のソース、共通入力フィールド、終了コード 2、デフォルトのタイムアウトはそのまま引き継げます。

変更点は細部にあります。マッチャーの評価方法、apply_patch のツール名変更、${CLAUDE_PROJECT_DIR} を使用したスクリプトパス、そして model, turn_id, additionalContextLimit を読み取るスクリプトの調整が必要です。Codex はハッシュで各フックを信頼しますが、Claude Code はワークスペースの信頼を確認します。この移行を機に、静的なコンテキストは CLAUDE.md にまとめ、フックは動的な要素のために活用しましょう。

よくある質問

/import codex は Codex フックを取り込みますか?

Claude Code のリファレンスには指示ファイル、MCP サーバー、コマンド、サブエージェント、スキルがリストされていますが、フックはそのリストに含まれていません。

Claude Code でフックはどこに記述しますか?

~/.claude/settings.json や .claude/settings.json などの設定ファイル内にある hooks キーの下に記述します。

Codex の hooks.json の構造を再利用できますか?

大部分は可能です。両方ともイベント、マッチャーグループ、ハンドラーを使用します。ツール名とパスを翻訳してください。

Claude Code のマッチャーで apply_patch の代わりになるものは何ですか?

Claude Code の編集ツールである Edit や Write です。

Codex の SessionStart フックは Claude Code でも同じように動作しますか?

両方とも標準出力のプレーンテキストをコンテキストとして追加し、同じ開始ソースをサポートしています。

Claude Code に同じ名前のイベントがない Codex フックイベントは何ですか?

PreModelRequest, PostModelRequest, および Interrupt です。

Claude Code でフックを再度信頼する必要がありますか?

対話型セッションでは、ワークスペース信頼ダイアログを承認するまで、設定ファイルのフックは保留されます。