Codexのローカル環境は、新しいWorktreeを使うときの準備と、起動・テストなどのよく使う操作をまとめる設定です。「普段のフォルダーなら動くのに、別の作業場所では動かない」を減らすために、何を最初に準備し、何をその都度実行するかを分けます。
この記事は2026年10月28日に確認したOpenAI公式資料に基づきます。編集部は今回、デスクトップアプリ上でローカル環境を作成・実行していません。依頼文や点検表は、設定前に使える編集部の教材です。記載したコマンドの実行成功や、特定の開発環境への適合を保証するものではありません。 本記事では製品操作の実測は行っていません。
Codexのローカル環境は、プロジェクトの準備をそろえる設定
OpenAIのLocal environmentsによると、この機能はChatGPTデスクトップアプリ内のCodexで利用します。アプリの設定から構成し、プロジェクトのルートにある.codexフォルダーへ設定を保存します。生成された設定をGitで管理し、チームで共有することもできます。
「Localで作業する」と「ローカル環境を設定する」は同じ意味ではありません。前者は作業場所の選択、後者は準備や繰り返し操作の設定です。例えば、LocalでWebアプリを編集しつつ、新しいWorktreeを作るたびに必要な準備をローカル環境へ登録する、といった組合せになります。
モデルやCodex全体の振る舞いを選ぶconfig.tomlとも役割が違います。記事の目的は、プロジェクトを動かすための準備を毎回再現できるようにすることです。モデル設定が目的ならconfig.tomlの解説を先に読んでください。
ローカル環境に登録する前に、動く条件を書き出す
普段使っているフォルダーには、過去に入れたライブラリーや、手作業で作った設定が残っています。そのため、そこで動いたという事実だけでは、新しい作業場所でも動くとは判断できません。まず「ソースコード以外に、何が必要か」を調べます。
| 確認すること | 記録する例 | 不足したときの影響 |
|---|---|---|
| 道具と版 | プロジェクトで指定するNode.jsやPythonの版 | 構文やライブラリーの互換性が変わる |
| 依存関係 | 採用しているパッケージ管理方法 | 必要なモジュールが見つからない |
| 作業場所 | 実行するディレクトリ | 設定や入力ファイルを見つけられない |
| ローカル設定 | 必要な変数名、設定ファイルの用途 | 外部サービスやデータへ接続できない |
| 確認方法 | テスト対象と起動後に見る画面 | 準備ができたか判断できない |
ここでは秘密の値を説明文に並べる必要はありません。必要な変数の名前と、どの仕組みで渡すかを区別して記録します。また、READMEと実際の起動手順が違うなら、どちらが現在のプロジェクトに合っているかを確かめてから登録します。
ローカル環境のセットアップは、最初の準備に使う
公式資料では、セットアップスクリプトは新しい会話の開始時にWorktreeを作成すると自動実行されると説明されています。用途は依存関係のインストールやビルドなど、作業を始めるための準備です。公式例はTypeScriptプロジェクトのnpm installとnpm run buildですが、そのまますべてのプロジェクトへ貼り付けるのではなく、既存の構成に合わせます。
編集部では、準備の各段階に「成功を何で確認するか」を添えることを勧めます。インストールなら終了状態とエラー、ビルドなら生成物と失敗ログ、設定なら必要項目の有無、といった形です。途中で失敗しているのに最後のメッセージだけが成功にならないよう、処理の区切りを明確にしてください。
このプロジェクトのローカル環境の案を作ってください。
まず既存のREADME、依存関係の定義、起動・テスト手順を読みます。
新しいWorktreeで不足する準備だけを挙げてください。
各処理の実行場所、前提、成功確認、失敗時の扱いを説明してください。
本番への接続、公開、データ更新は準備処理に含めません。
実行していない項目は未確認として残してください。これは設計用の依頼文です。実際の登録前には、返ってきた処理が依頼した範囲に収まるか読みます。「必要そう」という理由で大量の道具を追加するより、今のプロジェクトが必要とするものを確定させるほうが、失敗時の原因を絞れます。
ローカル環境のアクションは、起動やテストに使う
公式のActionsは、開発サーバーの起動やテストなど、頻繁に使う操作を登録する機能です。登録した操作はアプリ上部から選べ、統合ターミナルで実行されます。セットアップが最初の準備を担当し、アクションがその後の繰り返し操作を担当する、と分けると用途を整理できます。
アクションの名前は、「実行」のように曖昧なものより、「開発画面を起動」「変更箇所のテスト」のように、何をするか分かるものにします。これは編集部の命名例で、製品が自動でそう分類するという意味ではありません。操作する人が違っても、押した後に何が起きるか予測できることを目指します。
| 処理の目的 | 置き場所の候補 | 確認する結果 |
|---|---|---|
| 新しい作業場所の依存関係を準備 | セットアップ | 必要な依存がそろい、準備が終了した |
| 変更後にテストを実行 | アクション | 対象テストと成否が確認できた |
| 開発用画面を開くために起動 | アクション | プロセスだけでなく目的の画面が表示された |
同じアクションをもう一度押す前に、前の処理が終わったかを見ます。特にサーバー起動では、画面が出ない理由が「未起動」なのか「別の場所で起動済み」なのかを分けます。無条件に繰り返すと、原因を増やす可能性があります。
ローカル環境の教材：準備できた状態を一つずつ確かめる
架空の社内検索アプリを例にします。普段のフォルダーでは起動しますが、新しいWorktreeではモジュールが見つからないと表示されました。この場合、先にアプリの検索ロジックを修正するのではなく、依存関係の準備が実行されたか、実行場所が合っているかを確認します。
依存関係を準備してエラーが消えたら、次は小さなテストを実行します。そこで設定が足りないと分かった場合は、変数名と設定の渡し方を確認します。値の全文をログへ出して調べる必要はありません。最後に開発サーバーを起動し、検索画面を表示して、既知の入力で結果を確かめます。
この例の受入条件は「セットアップが終わった」「テストが通った」「目的の画面で期待どおりの結果が出た」の三つです。実際の一件で成功した結果ではなく、確認の順番を説明する教材として示しています。各段階を分けることで、後から失敗したときに戻る場所が決まります。
成果の報告にも同じ区別を使います。「動いた」だけではなく、「依存関係の準備は成功、テストは合格、外部サービスを使う検索は未確認」と書けば、次の担当が残りを引き継げます。確認していない部分を成功に数えないことが、再現性のある準備につながります。
ローカル環境を共有するときの注意
公式資料では、OSごとのセットアップやアクションを定義して既定の処理を上書きできます。macOSだけで動いたスクリプトをWindowsの担当へそのまま渡す前に、パス、シェル、必要な道具の違いを確認します。全OS対応にする必要がなければ、対応している環境を明記するだけでも誤解を減らせます。
一つのリポジトリに複数のプロジェクトがある場合は、共有する.codexフォルダーを含むプロジェクトのディレクトリを開く、という公式の注意もあります。別の階層の設定を読んでいると、編集したのに動作が変わらないように見えることがあります。
共有前に、個人の絶対パスや、その人だけが使える接続先を探します。設定ファイルをGitへ入れる場合も、共有するのは必要な手順であり、秘密の値ではありません。誰が更新するか、変更後に何を試すかを決めると、古い設定が残りにくくなります。
ローカル環境が動かないときの確認順
- デスクトップアプリのCodexを選んでいるか確認する。
- 対象プロジェクトと、設定のある階層を確認する。
- 準備のどの処理が失敗したか、ログと終了状態を確認する。
- 依存関係・必要な設定・OS差を順に確かめる。
- 準備が直ったら、テストと画面で結果を確認する。
最初から全部の設定を作り直すより、最後に成功した段階を残して調べるほうが比較できます。Worktreeの作成自体や、Localへの引き継ぎが目的なら公式のWorktreesを参照してください。クラウドで動かす環境は別の設定であり、手元の設定やサインインがそのまま使われるとは考えないようにします。
ローカル環境の最初の目標は、よく使うプロジェクト一つで「準備、テスト、起動」を説明どおりに進められることです。確認できた手順だけを少しずつ共有すると、担当者や作業場所が変わっても、同じ条件から仕事を始めやすくなります。
