Codexのshell snapshottingとWindows対応を実例で確認

shell snapshottingとは何か

Codex CLIは、リポジトリを読むだけでなく、利用者の端末にあるコマンドを呼び出してテストや確認を進めます。そのとき、ターミナルで普段使っている PATH、別名定義、関数、シェルの起動設定が、Codexのコマンド実行プロセスへ同じ形で渡るとは限りません。shell snapshottingは、この差を小さくするために、現在のシェルから再利用しやすい状態を取り出しておく仕組みです。Codex CLIがローカルのリポジトリを調べ、編集し、手元のツールを使えることは、OpenAIのCodex CLI公式ページでも説明されています。

ここでいう snapshot は、ソースコードの世代管理や作業内容のバックアップとは別物です。ファイルの差分や会話の要約を保存する機能ではなく、コマンドを実行する際の「どのシェルで、どの設定を読み、どの名前を解決するか」に近い情報を整えるものです。そのため、スナップショットの作成に失敗しても、コードの解析機能や対話画面そのものが壊れたとは限りません。警告と本体の失敗を分けて確認する必要があります。

コマンド実行の前提をそろえる仕組み

たとえば端末では、node や python の場所を起動ファイルで追加していることがあります。端末上のシェルでは見つかるのに、Codexから呼んだコマンドでは見つからないなら、問題はモデルの知識ではなく実行環境の差にあります。スナップショットは、その差を毎回手作業で説明する負担を減らすための補助線です。

ただし、スナップショットがあるからといって、別の端末や別のリポジトリの状態まで同一になるわけではありません。作業ディレクトリ、シェルの種類、起動時に読み込まれる設定、利用できる実行ファイルは分けて考えます。Codexへ「何を確認できれば完了か」を伝えることも、実行環境をそろえることと同じくらい重要です。

保存される内容をどう考えるか

現行の公式実装では、スナップショットの保存先として Codex のホームディレクトリ配下に shell_snapshots という名前の領域を使います。シェルの種類に応じたファイルを作り、検証してから後続の処理で参照します。保存期間や検証時間も実装に定義されており、永続的なプロジェクト成果物として扱うものではありません。詳しくは Codexのshell_snapshot実装を確認できます。

ここで注意したいのは、環境の便利さと環境の広さが表裏一体になる点です。エイリアスや関数が引き継がれると作業は楽になりますが、シェル起動ファイルに多くの設定を書いていると、何がCodexの実行環境へ入ったのか分かりにくくなります。後から原因を探せるように、開発に必要な設定と個人用の設定を分けておくと、警告への対処も簡単になります。

2026年8月に確認できる現在地

2026年8月17日に公式リポジトリの実装を確認すると、機能一覧では shell_snapshot が Stable、既定値が有効として定義されています。これは、試験機能を手動で選んだ利用者だけが触る段階から、通常のCodex利用時にも関係する基盤へ移ったことを示します。機能の状態は Codexの機能定義で確認できます。

同時に、機能が安定扱いであることと、すべてのシェルが対応済みであることは別です。現行の実装はローカル環境かどうかを確認し、シェルの種類ごとにスナップショット作成方法を分けています。作成処理には時間上限があり、古いファイルを整理する期間も定められているため、OSや起動設定が違えば見える警告も変わります。

既定有効でも全環境で同じ結果にはならない

既定で有効な機能は、利用者が何も設定しなくても起動時に関係します。そのため、以前は気にしなかったログに shell_snapshot が現れたり、Codexの更新後にシェル関連の警告が見えたりします。まず「機能が有効になった」ことと「作業が失敗した」ことを分け、ファイル編集、テスト、コマンドの終了状態を個別に確認してください。

公式ソースにはスナップショットの生成が成功したかどうかを記録する処理もあります。これは、作成できた場合だけ実行環境の補助に使い、できなかった場合はその事実を記録して先へ進む設計と読めます。ただし、実際に作業が続くかはCodexの版、利用入口、選んだシェルによって異なるため、警告を無条件に無視するのではなく、短い確認依頼で再現性を確かめるのが安全です。

WindowsのPowerShellでは何が起きるか

WindowsでPowerShellを利用している場合、公式の shell_snapshot.rs ではPowerShellとCmdをスナップショット作成の未対応シェルとして扱う分岐があります。さらに、Windows環境でこの警告が表示された事例が Codex公式リポジトリのissue #25833に記録されています。したがって、PowerShellで警告が出たことだけから、プロジェクトのコードやサインイン状態を原因と決めるのは適切ではありません。

確認すべきなのは、警告の直後にCodexの対話が続くか、ファイルの読み取りと編集ができるか、指定したコマンドを実行できるかです。PowerShellに対応していない機能を、設定を何度も変えて対応させようとするより、まず未対応による通知なのか、別の実行エラーなのかを分ける方が早く解決できます。

Windowsで警告を切り分ける手順

Windowsでは、Codexの起動元がPowerShellなのか、Cmdなのか、WSLや別のシェルなのかで結果が変わります。次の手順は、設定を大きく変更する前に、どの層で問題が起きているかを確認するためのものです。ひとつの確認結果を次の判断材料に残し、警告の文面だけで結論を出さないようにします。

同じ警告でも、起動時に一度だけ出る場合と、コマンドを実行するたびに出る場合では見直す場所が異なります。OS、シェル、Codexの版、起動方法、警告後にできたこと・できなかったことを短く記録しておくと、公式 issue の条件と照らし合わせやすくなります。再現条件が分かれば、不要な設定変更や再インストールを避けられます。

Step 1: 使っているシェルとCodexの版を確認する

最初に、警告が表示された画面のシェルを確認します。PowerShellから起動したのか、Cmdから起動したのか、WSLの中でLinuxシェルを起動したのかを書き分けてください。続けてCodexの実行ファイルがどこから呼ばれているかと版を確認します。複数のインストール先があると、更新したつもりの版と起動している版が一致しないことがあります。

codex --version
Get-Command codex
$PSVersionTable.PSVersion

Get-Command の結果が想定外の場所なら、先に呼び出し先を整理します。版が古い場合は、Codex公式のリリース一覧と照らし合わせ、安定版か試験版かも記録します。ここで更新を急ぐのではなく、現在の版で再現するかを残すことが大切です。

Step 2: 警告と本体の失敗を分ける

次に、読み取りだけの短い依頼を行い、プロジェクトの説明を返せるか確認します。その後、変更を伴わないコマンド確認、最後に小さな編集という順に範囲を広げます。各段階で、Codexの返答、端末のエラー、実際のファイル差分を分けて見ます。shell snapshottingの警告だけが出ていて他の処理が完了するなら、少なくとも警告と編集失敗は同じ原因ではありません。

反対に、コマンドが見つからない、作業ディレクトリが違う、設定ファイルが読めないという症状が同時に出るなら、シェルの初期化や実行パスを確認します。PowerShell未対応の通知を消すことだけを目標にせず、Codexが実際に必要なツールを見つけられる状態かを判断します。

Step 3: Codexの保存先を確認する

スナップショットの保存先は、CODEX_HOME を指定しているかどうかで変わります。Windowsでは、まず現在の値を表示し、未指定ならユーザープロファイル配下の .codex を候補として確認します。ファイルが存在しても、内容を編集したり他人へ送ったりする必要はありません。確認の目的は、警告の発生時刻とファイルの有無を照合することです。

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
Get-ChildItem -Force (Join-Path $codexHome "shell_snapshots")

現行実装はシェルの種類に応じて拡張子を分け、古いスナップショットを整理します。PowerShellでは作成自体が未対応なので、対象フォルダーが空であることは直ちに異常を意味しません。存在しないフォルダーを作って解決しようとせず、実際の版とシェルを先に確認します。

Step 4: 設定を一時的に切り分ける

他の処理は動くのに起動時の警告だけが気になる場合は、設定で機能を一時的に無効にして挙動を比較できます。Codexの設定ファイルに次を追加し、Codexを再起動します。設定ファイルの場所や構文は版で変わる可能性があるため、公式の設定スキーマも確認してください。

[features]
shell_snapshot = false

無効化後に警告が消えても、それだけで設定を固定する理由にはなりません。コマンドの探索、テスト、開発用ツールの呼び出しに変化がないかを確認し、必要なら設定を戻します。目的は表示を消すことではなく、shell snapshottingが自分の環境で有益か、別の原因を隠していないかを見極めることです。

LinuxとmacOSでの挙動

PowerShellとCmdの状況はWindows特有なので、LinuxやmacOSの利用者は同じ警告をそのまま当てはめないようにします。現行の実装には、zsh、bash、sh向けのスナップショット生成処理があり、シェルの起動ファイルを読み込んだうえで、関数、別名、設定、エクスポートされた値などを再利用できる形に整えます。ターミナルで設定した開発用ツールがCodexから見えるかどうかは、これらの初期化内容に左右されます。

公式ソースでは、スナップショットを検証する処理にも時間上限が置かれています。起動ファイルが重い、入力待ちをする、対話的な表示を要求する、といった設定があると、生成処理が時間内に終わらず警告になる可能性があります。これはCodexのモデルが遅いという話ではなく、シェルを準備する段階の問題です。

zshとbashで確認する点

zshやbashで警告が出た場合は、まず .zshrc、.bashrc、ログイン時に読む設定を確認します。起動時に表示を出す処理、入力を待つ処理、端末が対話状態であることを前提にした処理があれば、Codexのスナップショット作成と相性がよくありません。開発に必要なパス設定と、表示や便利機能を追加する設定を分離すると、どこで時間を使っているかを把握しやすくなります。

さらに、端末でだけ定義される関数や別名に依存すると、別の入口からCodexを起動したときに再現しないことがあります。Codexが呼び出すコマンドは、明示的な実行ファイル名やプロジェクトの説明で確認できるようにしておくと、スナップショットの成否に過度に依存せずに済みます。

リモート作業は同じ仕組みではない

公式実装はリモート環境を検出すると、ローカルのshell snapshottingを作成しない分岐を持っています。クラウド側の作業や別マシンの実行環境について、手元の .zshrc や .bashrc がそのまま渡ると考えるのは危険です。ローカルで使えるコマンドがリモートでも使えるとは限らないため、作業環境の準備状況と実行結果を分けて確認します。

ローカルとリモートを比べるときは、同じモデル名かどうかだけでなく、作業ディレクトリ、利用できる実行ファイル、シェルの種類、設定ファイルの読み込み方をそろえて記録します。shell snapshottingは環境差を減らす補助機能ですが、別の環境を同一にする機能ではありません。

認証情報と環境の扱い

shell snapshottingを理解するとき、便利さだけでなくシェル設定に何を書いているかも確認する必要があります。公式実装の現在の定義では、エクスポート対象から PWD と OLDPWD を除外する指定が見えます。つまり、シェル起動ファイルで多くの値を export している場合、どの値がスナップショットへ入る可能性があるのかを、利用者自身が把握しておく必要があります。認証用の値や個人用の接続先を、すべてのシェルで常時公開する設計は避けた方が安全です。

これは「Codexは危険だ」と単純化する話ではありません。シェルの状態を別のプロセスで再利用する機能では、もともと端末へ渡っている値が別の場所へ複製される可能性があります。利用するコマンドに必要な範囲だけ値を渡し、起動ファイルには最小限の設定を置き、不要になった値は削除するという基本を守ることが重要です。

開発用の値を常にエクスポートしない

たとえば一時的な接続先や認証情報を、シェル起動のたびに export する構成にしていると、スナップショットだけでなくログや診断ファイルにも現れる範囲が広がります。必要なコマンドを実行する直前だけ値を設定する、専用の開発環境でだけ読み込む、利用後に無効化するなど、値の寿命を短くします。値が意図せずファイルへ書かれた疑いがある場合は、利用先の手順に従って更新し、古い値を使い続けないようにします。

WindowsでPowerShellのスナップショット作成が未対応でも、Codex以外のツールや端末の履歴が環境値を扱う可能性は残ります。対応の有無だけで安心せず、端末・エディタ・ビルド用ツールへ何を渡しているかを確認することが、長期的には確実です。

共有・バックアップ前に確認する

shell_snapshots の中身を診断のために確認することはできますが、ファイルをそのまま issue、チャット、共有フォルダーへ添付するのは避けます。パス、ユーザー名、社内ホスト名、環境値などが混ざる可能性があるためです。必要な部分だけを別のテキストへ写し、値や固有名を伏せて、Codexの版、OS、シェル、発生時刻、警告文を伝えます。

バックアップや端末移行の対象を選ぶときも、.codex 配下を一括で扱わず、何を移す必要があるかを確認します。スナップショットは開発成果物ではないため、ソースコードや設定の管理場所と同じ扱いにする必要はありません。公式実装の保存期間があるから任せるのではなく、不要なファイルを残さないという判断を優先します。

Codexの更新後に確認するポイント

CodexはCLI、デスクトップアプリ、エディタ連携など複数の入口で提供され、同じ名前でも同じ版が動いているとは限りません。shell snapshottingの挙動を比較するときは、入口、版、OS、シェル、作業ディレクトリを一組の情報として記録します。更新後に警告が変わった場合も、まず Codexの公式リリース一覧を確認し、利用中の版に対応する実装や既知の issue がないかを探します。

公式の変更履歴や issue は、すべての環境で同じ不具合が起きることを保証するものではありません。PowerShellの未対応警告、zshの起動設定による時間超過、パスが復元されない問題などは、似た文面でも原因が異なります。報告を読むときは、OSとシェルが自分の環境と一致するか、作業が継続できているか、回避策がどの版を前提にしているかを確認してください。

確認のために更新する場合は、更新前の版と設定ファイルを記録し、短いテストを同じ条件で再実行します。更新後に問題が消えたとしても、どの変更が効いたか分からないまま設定を増やすと、次の版で原因を追いにくくなります。警告を消すことより、Codexが必要なファイルとコマンドを一貫して扱えることを優先します。

まとめ

Codexのshell snapshottingは、シェルの状態を再利用して、端末で使える開発環境とCodexが使う実行環境の差を小さくする機能です。現行の公式実装では安定扱いかつ既定で有効ですが、PowerShellとCmdのスナップショット作成は未対応として扱われます。Windowsで警告を見たら、まずシェルの種類、Codexの版、警告後の作業結果を確認し、未対応通知と本体のエラーを分けて考えます。

必要に応じて保存先と設定を確認し、[features] の shell_snapshot を一時的に切り替えて比較します。LinuxやmacOSでは起動ファイルの入力待ちや表示処理、認証情報の常時エクスポートが原因になりやすいため、シェル環境を小さく保つことが有効です。警告の有無だけで結論を出さず、Codexが目的のファイルを読み、必要なコマンドを実行し、結果を確認できるかを基準に運用しましょう。