はじめに
Windows PCを新しくしたため、旧PCで使っていたCodex Desktopのタスク履歴を新PCへ移行しました。
移したかったのは設定だけではありません。
- 過去のタスク一覧
- 各スレッドの会話本文
- プロジェクトごとの分類
- 添付ファイル
- アーカイブ済みタスク
- ピン留めやプロジェクト表示情報
最終的には移行できましたが、途中で「一度は表示されるのに、スレッドを開くと一覧から消える」という厄介な問題に遭遇しました。
この記事では、失敗した方法も含めて、解決までの流れを整理します。
この記事で紹介する方法は、Codex Desktopのローカル保存形式を扱うコミュニティーツールです。OpenAI公式の移行ツールではありません。Codexの更新によってDBスキーマや保存場所が変わる可能性があります。必ずバックアップを作成し、移行完了まで旧PCを消去しないでください。
環境
- 旧PC／新PC：Windows 11
- Codex Desktop
- Windows PowerShell 5.1
- Python 3
- 新旧PCでWindowsユーザー名は同一
新PCでは、プロジェクトフォルダを次のように変更しました。
旧PC: C:\Dev\ProjectA
新PC: D:\Workspace\ProjectA
旧PC: C:\Training
新PC: D:\Workspace\Training
この「プロジェクトフォルダの変更」が、問題を複雑にした大きな要因でした。
Codex Desktopの履歴はどこにあるのか
Codex Desktopのローカルデータは、主に次の場所に保存されています。
%USERPROFILE%\.codex
重要なデータは次のとおりです。
.codex
├─ state_5.sqlite
├─ session_index.jsonl
├─ sessions
│ └─ YYYY
│ └─ MM
│ └─ DD
│ └─ rollout-....jsonl
├─ archived_sessions
├─ attachments
└─ .codex-global-state.json
| データ | 役割 |
|---|---|
state_5.sqlite |
スレッドID、タイトル、所属プロジェクト、履歴ファイルの場所 |
sessions |
会話本文のJSONL |
session_index.jsonl |
スレッド一覧の補助インデックス |
.codex-global-state.json |
プロジェクトやワークスペースの登録情報 |
attachments |
添付ファイル |
archived_sessions |
アーカイブ済み履歴 |
最初の移行
旧PCのデータを移行パッケージとしてエクスポートしました。
Set-ExecutionPolicy -Scope Process Bypass
.\migrate_codex_history.ps1 `
-Mode Export `
-PackagePath 'D:\Codex-History-Transfer'
エクスポート後、ファイルサイズとSHA-256を検証します。
.\migrate_codex_history.ps1 `
-Mode Verify `
-PackagePath 'D:\Codex-History-Transfer'
成功時は次のように表示されます。
Verification passed: 65 files
一見するとタスクが表示され、成功したように見えました。しかし、ここからが大変でした。
問題：スレッドを開くと一覧から消える
新PCで移行済みスレッドを開くと本文は読めました。ところが別のタスクへ移動すると、先ほど開いたスレッドが一覧から消えます。
DBを確認しても、データそのものは残っていました。
DB threads: 48
Missing rollout files: 0
Missing index entries: 0
つまり、スレッドが削除されたのではなく、Codex Desktopの画面上で所属プロジェクトとの対応が外れて非表示になっていました。
調査したポイント
SQLiteへの登録
Codexのバージョンや移行履歴によっては、SQLiteが複数の場所に存在する可能性があります。
%USERPROFILE%\.codex\state_5.sqlite
%USERPROFILE%\.codex\sqlite\state_5.sqlite
存在するDBを検出してメタデータを登録するようにしました。しかし、今回の本当の原因はこれだけではありませんでした。
session_index.jsonlの不足
DBにはスレッドがある一方、インデックスに一部のIDがありませんでした。SQLiteのスレッド情報から不足分を補完しました。
Session index repaired: 6 entries added
それでも、開いたスレッドが消える現象は続きました。
プロジェクトパスの変更
SQLiteのcwdだけでなく、Codex Desktopのプロジェクト登録情報も変換する必要がありました。
- SQLiteのスレッド
cwd - プロジェクト表示順
- 保存済みワークスペース
- アクティブワークスペース
- ピン留め情報
それでも、まだ完全には直りませんでした。
最終原因：JSONL内ではパスがエスケープされていた
最終的な原因は、会話JSONLの中にありました。
通常のWindowsパスは次のように見えます。
C:\Dev\ProjectA
しかしJSONL内では、バックスラッシュがエスケープされています。
C:\\Dev\\ProjectA
当初の変換処理は通常表記のパスしか置換していなかったため、処理結果は次の状態でした。
Session log paths repaired: 0 files
Codex Desktopはスレッドを開いた際、JSONL内のsession_metaから元のcwdを読み直します。
その結果、次の流れが発生していました。
- SQLiteでは新しいプロジェクトに所属している
- タスク一覧には一度表示される
- スレッドを開く
- JSONLから旧
cwdが読み込まれる - 旧プロジェクトへ所属が戻る
- 現在のプロジェクト一覧から消える
JSONエスケープ形式も変換すると、次の結果になりました。
Session log paths repaired: 45 files
その後Codex Desktopを再起動すると、スレッドを開いても一覧から消えなくなりました。
最終的なインポートコマンド
新PCでは、Codex Desktopを完全に終了してから実行します。
cd C:\Tools\codex-desktop-history-migration
Set-ExecutionPolicy -Scope Process Bypass
.\migrate_codex_history.ps1 `
-Mode Import `
-PackagePath 'D:\Codex-History-Transfer' `
-PathMap `
'C:\Dev\ProjectA=D:\Workspace\ProjectA',
'C:\Training=D:\Workspace\Training'
成功時の出力例です。
Verification passed: 65 files
Codex Desktop project paths repaired
C:\Users\<user>\.codex\state_5.sqlite: 48 rows imported
Session index repaired: 0 entries added
Session log paths repaired: 45 files
Import completed
作成したツール
今回使用したスクリプトはGitHubで公開しました。
主な機能は次のとおりです。
- Codex履歴のエクスポート
- ファイルサイズとSHA-256による検証
- 新PCへのインポート
- SQLiteメタデータの移行
- 複数プロジェクトのパスマッピング
- Codex DesktopのUIプロジェクト情報の変換
- JSONL内の通常パスとエスケープパスの変換
- セッションインデックスの補完
- インポート前の自動バックアップ
- 認証情報やキャッシュの除外
-
-WhatIfによるドライラン
移行時の注意事項
- インポート中はCodex Desktopを完全に終了する
-
auth.jsonは移行せず、新PCで再ログインする - 会話本文と添付ファイルを含む移行パッケージを公開しない
-
Size mismatchやHash mismatchを無視しない - 移行確認が終わるまで旧PCを消去しない
- WSLでCodexを動かしている場合は、実際に参照されている
.codexを確認する
今回の教訓
SQLiteだけコピーしても不十分
Codex Desktopのタスク履歴は、複数のデータが連携して表示されています。
SQLite
+ session_index.jsonl
+ sessions/*.jsonl
+ .codex-global-state.json
+ 実際のプロジェクトフォルダ
フォルダ構成を変える場合は3箇所を揃える
特に重要だったのは次の3箇所です。
- SQLiteの
cwd - Codex Desktopのプロジェクト登録情報
- JSONL内の
session_metaに記録されたcwd
「表示された」は成功ではない
最低限、次を確認する必要があります。
- Codex Desktopを再起動する
- 移行したスレッドを開く
- 別のスレッドへ移動する
- 元のスレッドが一覧に残っているか確認する
- 複数プロジェクトで同じ確認を行う
おわりに
最初は「SQLiteとsessionsをコピーすれば終わる」と考えていました。
しかし実際には、プロジェクト登録、インデックス、JSONL内部のエスケープパスまで整合させる必要がありました。
特に厄介だったのは、「一度は表示されるため、成功したように見える」ことです。
同じようにWindows PCを入れ替え、Codex Desktopの履歴移行で困っている方の参考になれば幸いです。