Codex Handoff の仕組み — Local、Worktree、リモートホスト間でチャットと共に移動するもの (2026)

Handoff は2つの段階を経て導入されました。まず、2026年3月初旬に Local と Worktree 間のチャット移動が可能になりました。OpenAI の週間サマリーによると、「コンテキストを保持したままアクティブなチャットを移動できるようになった」とのことです。続いて6月にホスト間の移動が可能になりました。「Chat handoff は、チャットとその Git 状態をローカルコンピュータと接続されたリモートホストの間で移動させます。」

Local と Worktree

worktree とは、リポジトリの2つ目のチェックアウトのことです。OpenAI の worktree に関するページでは、その関係を次のように説明しています。「Local をフォアグラウンド、Worktree をバックグラウンドと考えることができます。Handoff を使うと、その間でチャットを移動できます。」

チャットをフォアグラウンドに持ってくるには、チャットヘッダーで「Hand off」を選択し、Local に移動させます。逆も可能で、自分が他の作業をしている間に Codex が作業を続けられるよう、チャットを Local から worktree に移動させることもできます。

Handoff が重要な理由の1つに Git のルールがあります。worktree のページでは次のように説明されています。「Git では、一度に1つの場所でしかブランチをチェックアウトできません。」Handoff は Git の手順を処理してくれるため、ローカルで作業を確認したいときにその制限にぶつかることがありません。

往復を容易にする詳細な仕様もあります。「各チャットは、時間の経過とともに同じ関連付けられた worktree を保持します。後でチャットを worktree に戻すと、Codex はそれを同じバックグラウンド環境に戻すため、中断したところから再開できます。」

ホスト間

リモートホストとは、SSH ホストなど、デスクトップアプリが接続する別のコンピュータのことです。リモート接続のページでは、そのユースケースを次のように説明しています。「ローカルで作業を開始し、リモートコンピュータ上の worktree で継続し、後でチャットを戻すために使用します。」

チャットを開き、チャットフッターで現在の実行場所を選択し、移動先のホストを選び、移動先とブランチを確認して「Hand off」を選択します。OpenAI によれば、移動先では「Codex が移動先ホストで worktree を作成または再利用し、チャットと Git 状態を転送し、チャットをそのホストに切り替えます。」

会話。 チャットそのものが移動するため、次のメッセージで同じスレッドを継続できます。タスクを説明し直す必要はありません。

Git 状態。 Handoff は2つのチェックアウト間の Git 操作を処理します。リモートホストの場合、OpenAI は「チャットと Git 状態」を転送すると述べています。

戻りリンク。 worktree の場合、各チャットは同じ worktree を保持するため、戻すと同じ環境に復帰します。

これは、最初の Handoff を行う前に読んでおく価値があるセクションです。

無視されたファイル (Ignored files)

Handoff は Git を使用するため、Git が無視するファイルは移動しません。worktree のページには次のようにあります。「Handoff は Git 操作を使用するため、.gitignore ファイルに含まれるファイルは、Codex が .worktreeinclude を使用してローカルの管理対象 worktree にコピーしない限り、チャットと共に移動しません。」

これには .env やローカルのシークレットなどのファイルが含まれます。リポジトリのルートにある .worktreeinclude ファイルには、管理対象 worktree の作成時に Codex がコピーすべき無視されたパスをリストします。OpenAI は、この動作は「ローカルの ChatGPT デスクトップアプリが管理する worktree に適用され、リモートの worktree やコマンドラインから自分で作成した Git worktree には適用されない」と注意を促しています。リモートホストの場合は、それらのファイルを自分でセットアップするように計画してください。

1つだけ組み込みの例外があります。「Codex は無視された AGENTS.override.md をローカルの管理対象 worktree に自動的にコピーするため、.worktreeinclude にリストする必要はありません。」

他のマシンのセットアップ

チャットがリモートホストに移動すると、そのホストの環境で実行されます。リモート接続のページでは、これが一般的に何を意味するかを明確にしています。「リモートアクセスは、接続されたホストのプロジェクト、チャット、ファイル、認証情報、権限、プラグイン、Computer Use、ブラウザ設定、およびローカルツールを使用します。」

つまり、Handoff 後に利用可能なプラグイン、認証情報、ツールは、ノート PC のものではなく、移動先ホストにあるものになります。

メモリと個人指示 (Memories and personal instructions)

Codex の memory はマシンに紐付いています。memory のページでは、この設定を「選択したマシンに対して機能をオンまたはオフにする」と説明しており、memory ファイルはそのマシンの ~/.codex/memories/ に保存されます。IDE 拡張機能も同じパターンに従い、「接続された Codex ホストのローカルメモリ保存場所を使用」します。

グローバルな指示も同様に機能します。Codex は、実行されているマシンの Codex ホームディレクトリ（デフォルトは ~/.codex）からグローバルガイダンスを読み取ります。

Handoff のドキュメントには、ホスト間での memory やグローバルな AGENTS.md のコピーについては記載されていません。したがって、チャットがリモートホストに移動した後は、そのホストの memory やグローバル指示（もしあれば）を使用して動作することを想定してください。Git にコミットされているリポジトリ内の AGENTS.md は、両方の場所に存在します。

ドキュメントにはいくつかの制限が挙げられています。

• 一致するプロジェクトが必要。 「チャットを Handoff する前に、移動先ホストを接続し、そのホスト上で同じ Git リポジトリのプロジェクトを保存してください。」プロジェクトがサブディレクトリの場合は、両方のホストで同じサブディレクトリを保存します。「Codex は、一致する保存済みプロジェクトがある移動先のみを表示します。」
• 実行中の作業を中断する。 「チャットが実行中の場合、Handoff は転送前に現在のレスポンスを中断します。」
• クラウドには移動できない。 別のチャットで Codex に特定のチャットを Handoff するよう依頼することはできますが、「Codex はリクエストを行っているチャット自体を Handoff することはできず、Codex クラウド環境への Handoff はサポートされていません。」
• 1つのブランチ、1つの場所。 「Create branch here」で worktree 上にブランチを作成した場合、それを同時にローカルでチェックアウトすることはできません。OpenAI のアドバイスは次の通りです。「ブランチをローカルでチェックアウトする予定がある場合は、同じブランチを両方の場所で同時にチェックアウトしたままにしようとするのではなく、Handoff を使用してチャットを Local に移動してください。」

OpenAI のクラウドで作業を実行したい場合は、プロジェクトのコンテキストを使用して Codex クラウド環境を準備するためのガイドでその方法を解説しています。

別のマシンで新しいチャットを開始する。 機能はしますが、会話の流れが失われ、最初の数メッセージを再説明に費やすことになります。

worktree のブランチをローカルでチェックアウトしようとする。 ブランチがすでに worktree でチェックアウトされているため、Git が拒否します。Handoff が推奨される方法です。

リモートホストがローカルと同じセットアップを持っていると期待する。 リモートホストでは、チャットはノート PC のものではなく、そのホストのファイル、プラグイン、認証情報、および memory を使用します。

タスクの途中で実行中のチャットを Handoff する。 Handoff は現在のレスポンスを停止させるため、区切りの良いところまで待つようにしましょう。

ステップ 1：Handoff 前に移動先の準備を整える

worktree の場合は、.env ファイルなど、新しいチェックアウトに必要な無視されたファイルをリストした .worktreeinclude ファイルを追加します。リモートホストの場合は、接続を確立し、同じリポジトリのプロジェクトを保存し、環境（無視されたファイル、認証情報、プラグイン、依存しているグローバル指示など）をセットアップします。memory を使用している場合は、そのホストでも memory をオンにするかどうかを決定します。memory のページでマシンごとのオン・オフ設定について説明されています。

ステップ 2：チャットが区切りの良いところに達したら Handoff する

現在のレスポンスが完了するまで待ちます。その後、Codex に現在の状況（完了したこと、次にすべきこと、途中で下した決定事項など）の短い要約を求めます。その要約はチャット内に残るため、チャットと共に移動し、移動先のチャットに明確な開始点を提供します。その後、Hand off を使用します。

ステップ 3：移動先でチャットが見ているものを確認する

Handoff 後、Codex に従っている指示を要約させ、プロジェクトを実行できることを確認させます。何かが足りない場合、それは通常、無視されたファイル、認証情報、または別のマシンにあるグローバル指示です。移動先でそれを修正して継続します。Codex が AGENTS.md のルールをスキップするのを防ぐためのガイドでは、指示の確認について詳しく解説しています。

Handoff はチャットとそのコードを移動させます。作業に関するコンテキスト、好みのやり方、決定済みの事項、プロジェクトの規約などは、一部はチャットに、一部はあるマシンのファイルに、そして一部はそのマシンに残る memory に存在します。

MemoryLake は、それらのコンテキストを1つのリストとして維持し、Codex や、接続している ChatGPT、Claude Code などの他のアシスタントから利用できるようにするためのメモリレイヤーです。

エントリは自分自身の言葉で記述します。Codex チャット、Codex memory、worktree、リモートホスト、またはベンダーのストレージから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。業務用のリポジトリについては、リポジトリ外に保持するものに関する組織のポリシーに従ってください。

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

サインインし、ダッシュボードからキーを生成します。キーは MemoryLake ワークスペースに属し、ChatGPT アカウントとは別個のものです。

ステップ 2：最初のメモリをアップロードする

解決策のステップ 2 で作成した要約や、各ホストで再設定することになる規約から始めましょう。1つのエントリにつき1つのポイントを記述し、日付を入れ、適用されるリポジトリのラベルを付けます。

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

Codex や使用している他のアシスタントを接続します。ノート PC、リモートホスト、あるいはチャットが着地したどのチェックアウトでも、同じコンテキストが利用可能になります。

第一の違いは、チャットの移動が「賭け」ではなくなることです。会話と Git 状態が一緒に移動し、どのローカル要素が移動しないかを把握できるようになります。

第二に、到着前に移動先の準備が整います。無視されるファイルがリストされ、リモートプロジェクトが保存され、依存しているセットアップが整った状態になります。

第三に、重視するコンテキストが、チャットがどのマシンで実行されているかに依存しなくなります。チャットを Handoff するのではなく、コンピュータ自体を新しく買い替える場合は、Codex のセットアップを新しいコンピュータに移行するためのガイドで移行プロセス全体を解説しています。

バックグラウンド作業には worktree を、その確認には Local を使用する。 これが Handoff が想定している使い分けです。

無視されるセットアップファイルを .worktreeinclude にリストする。 そうしないと、それらのファイルは元の場所に残ります。

すべてのホストで一致するプロジェクトを保存する。 Handoff は、保存済みプロジェクトがある移動先のみを提示します。

区切りの良いところで Handoff する。 実行中のレスポンスは中断されます。

移動前に要約を求める。 要約はチャットと共に移動し、移動先での助けになります。

マシンごとに memory を設定する。 Codex はマシンごとに memory を設定します。Codex のローカルメモリをオンにするためのガイドで設定方法を解説しています。

1つのブランチを2つの場所でチェックアウトしたままにしない。 代わりに Handoff を使用してチャットを移動させてください。

Codex Handoff は、チャットとその Git 状態をローカルのチェックアウトと worktree の間、あるいはコンピュータと接続されたリモートホストの間で移動させます。これは、新しい会話を始めることなく、バックグラウンド作業をフォアグラウンドに持ってくる、あるいは作業を別のマシンに送るための手段です。

.worktreeinclude によってローカルの管理対象 worktree にコピーされない限り、無視されたファイルは移動しません。また、リモートホストでは、そのホストのプラグイン、認証情報、memory、およびグローバル指示を使用して動作します。Codex クラウド環境への Handoff はできません。移動先を準備し、区切りの良いところで Handoff し、到着後にチャットが見ているものを確認しましょう。Claude Code も併用している場合は、Claude Code の worktree がメモリを共有するかどうかに関するガイドで、同様の疑問について解説しています。