🌏 中文 ｜ English
一个轻量的 macOS 图形化工具，用来管理和转换本机 Codex 聊天记录。
核心目标很简单：把 Codex 会话在 不同 API（第三方 provider） 和 官方 之间一键转换。应用默认只读取会话列表，不展开完整聊天内容，避免会话很多时卡顿。
Codex 桌面端会按「模型来源」把历史会话分桶显示——每个 API（provider id）各是一个桶，官方也是一个桶。切到 API A 就只看得到 A 的会话，切到 API B 或官方时，其他桶里的历史像「丢了」一样找不到。Codex 对话管家能显示每个 API 各有多少会话、标出 Codex 当前正在用哪个 API，并把会话安全迁移到任意一个 API 或官方，让你换了来源也能找回自己的对话。
- 原生 macOS SwiftUI 应用，可直接双击打开。
- 自动识别本机 Codex 记录目录（
~/.codex）。 - 启动时快速读取会话列表（只读列表，不加载完整正文）。
- 中文固定三栏界面，不使用会跳动的系统侧栏。
- 侧栏按 provider 逐个列出（官方 + 每个第三方 API），显示各自会话数，并给 Codex 当前激活的 API 打上「当前」标记。
- 每条会话的徽章显示真实 provider id；绿点表示 Codex 现在就能看到这条会话。
- 会话详情里显示「Codex 可见性」：当前 API 下可见还是要转换归属后才可见，并可一键把这条会话转到当前 API。
- 按「全部 / 各 provider / 未标注 / 异常会话」筛选。
- 区分桌面会话和 CLI 会话。
- 按项目目录分组，显示标题和相对时间。
- 单击勾选多条会话后批量转换。
- 未勾选时，默认转换当前筛选范围内全部可转换的会话。
- 勾选后只转换已勾选的会话（1 条、2 条或更多）。
- 转换目标不限于两个：快捷按钮支持「转到官方」「转到当前 API」，「更多目标」菜单支持转到 config.toml 里定义过或历史上用过的任何 provider（API↔API 互转也可以）。
- 勾选后可批量删除；点开详情后可删除单条会话。
- 转换前自动创建本地备份。
- 删除前自动创建本地备份，并从本机列表和记录中移除。
- Codex 正在运行时拒绝写入，避免影响进行中的任务。
- 可一键恢复最近一次备份。
需要 macOS 14 及以上。不需要安装 Xcode 或 Xcode 命令行工具。
打开「终端」，粘贴运行这一行：
curl -fsSL https://raw.githubusercontent.com/daYangjiao/codex-vault/main/scripts/quick-install.sh | bash它会下载预编译好的「Codex 对话管家」，安装到 /Applications/Codex 对话管家.app，并自动打开。之后随时在启动台 / 应用程序里点开即可，不用再敲命令。
安装脚本只使用 macOS 自带工具（curl、ditto、open），适合交给 AI 代理在任意符合系统要求的 Mac 上自动安装。
开发者：本地运行 / 调试
需要 Xcode 命令行工具（xcode-select --install）：
git clone https://github.com/daYangjiao/codex-vault.git
cd codex-vault
swift run CodexVaultSmokeTests # 自检：验证扫描与迁移核心逻辑
swift run CodexVault # 前台运行一个开发版（不安装到「应用程序」）
./scripts/package-macos.sh # 生成 dist/Codex-Vault.app.zip 和 dist/Codex-Vault.dmg发布者：生成一键安装包
发布新版本时，在 macOS 上运行：
./scripts/package-macos.sh然后把 dist/Codex-Vault.app.zip 上传到 GitHub 最新 Release。README 里的安装命令会下载这个 Release asset 并安装；如果没有上传这个文件，一键安装会提示下载失败。
- 执行转换、删除或恢复前，会检查 Codex 是否完全退出，并建议先结束正在运行的任务。
- 转换后需重新打开 Codex，会话列表才会刷新。
- 图片多的会话不会展开或重写完整聊天内容，迁移时尽量保持原始内容不变。
- 所有写操作前都会先创建本地备份。
备份目录：
~/Library/Application Support/Codex Vault/Backups
安装命令卡住或下载失败（curl: (xx) / 连不上 github）
多半是网络访问 GitHub 不稳。挂上代理后重试，或换个网络。脚本只是下载 + 解压，重跑一次没有副作用。
提示「已损坏，无法打开，应该移到废纸篓」 这是 macOS 的安全提示。在终端执行下面这条命令，然后重新打开应用：
xattr -cr "/Applications/Codex 对话管家.app"提示「无法验证开发者 / 来自身份不明的开发者」 打开「系统设置 → 隐私与安全性」，往下找到被拦的提示，点「仍要打开」；或对着应用图标右键选「打开」。
应用打不开 / 闪退 应用支持 Apple 芯片和 Intel 芯片的 Mac，但需要 macOS 14 及以上。系统版本过低时请先升级 macOS。
应用里看不到任何会话 / 提示找不到 Codex 记录
说明没找到 ~/.codex 目录。请先确认本机装过并至少打开运行过一次 Codex；如果你的记录目录在别处，用左上角「选择文件夹」手动指定。
转换/删除按钮点了没反应，提示 Codex 正在运行 迁移会写入本机记录，必须先完全退出 Codex（包括菜单栏图标），并结束 VS Code 里 Codex 面板拉起的后台进程，再操作。
转换成功了，但 Codex 里还是看不到那些会话 Codex 按「来源」分桶显示。转换后需重新打开 Codex，并把 Codex 切到目标 API（或官方），列表才会刷新出来。应用侧栏带「当前」标记的就是 Codex 现在正在显示的桶。
装错地方 / 想卸载
直接把「应用程序」里的「Codex 对话管家.app」拖到废纸篓即可。备份仍保留在 ~/Library/Application Support/Codex Vault/Backups，可手动删除。
🌏 中文 ｜ English
A lightweight macOS GUI tool for managing and migrating your local Codex chat history.
The goal is simple: move Codex conversations between any API provider and Official buckets with one click. By default the app only reads the conversation list — it never expands the full chat body, so it stays fast even with a large history.
Codex Desktop groups your history by model source: every API provider id is its own bucket, and Official is another. Switch to provider A and you only see A's conversations; everything else feels "lost". Codex Vault shows how many conversations live under each provider, marks which provider Codex is currently using, and safely migrates conversations to any provider (or Official) so your history follows you across sources.
- Native macOS SwiftUI app — double-click to launch.
- Auto-detects the local Codex directory (
~/.codex). - Fast list scan on launch (list only, no full message bodies).
- Fixed three-pane Chinese UI — no jittery system sidebar.
- Sidebar lists every provider (Official + each third-party API) with its conversation count, and marks the one Codex is currently using.
- Each conversation badge shows the real provider id; a green dot means Codex can see it right now.
- Detail view explains visibility (visible under the current API, or needs migration) and offers a one-click "move to current API".
- Filter by All / per-provider / untagged / Problem conversations.
- Distinguishes desktop sessions from CLI sessions.
- Groups by project directory, with titles and relative timestamps.
- Click to select multiple conversations and migrate in bulk.
- With nothing selected, migrates every eligible conversation in the current filter.
- With items selected, migrates only those (1, 2, or many).
- Migration targets are not limited to two buckets: quick buttons cover "to Official" and "to current API", and a "More targets" menu reaches any provider defined in config.toml or seen in history (API↔API works too).
- Bulk-delete selected conversations; delete a single one from its detail view.
- Creates a local backup before every migration.
- Creates a local backup before every deletion, then removes it from the list and store.
- Refuses to write while Codex is running, protecting in-progress tasks.
- Restore the most recent backup with one click.
Requires macOS 14+. Xcode and the Xcode Command Line Tools are not required.
Open Terminal and paste this single line:
curl -fsSL https://raw.githubusercontent.com/daYangjiao/codex-vault/main/scripts/quick-install.sh | bashIt downloads the prebuilt Codex 对话管家, installs it to /Applications/Codex 对话管家.app, and opens it automatically. After that, open it any time from Launchpad / Applications — no command needed again.
The installer only uses macOS built-in tools (curl, ditto, open), so it is suitable for AI agents to install automatically on any Mac that meets the system requirement.
Developers: run / debug locally
Requires the Xcode Command Line Tools (xcode-select --install):
git clone https://github.com/daYangjiao/codex-vault.git
cd codex-vault
swift run CodexVaultSmokeTests # self-check: scanning + migration core logic
swift run CodexVault # runs a dev build in the foreground (does NOT install to /Applications)
./scripts/package-macos.sh # creates dist/Codex-Vault.app.zip and dist/Codex-Vault.dmgPublishers: create the one-line installer asset
When publishing a new version, run this on macOS:
./scripts/package-macos.shThen upload dist/Codex-Vault.app.zip to the latest GitHub Release. The README install command downloads and installs that Release asset; if the asset is missing, the one-line installer reports a download failure.
- Before migrating, deleting, or restoring, it checks that Codex has fully quit and recommends ending any running tasks first.
- Reopen Codex after a migration for the list to refresh.
- Image-heavy conversations are not expanded or rewritten; original content is preserved as-is during migration.
- A local backup is created before every write.
Backups directory:
~/Library/Application Support/Codex Vault/Backups
Install command hangs or download fails (curl: (xx) / can't reach github)
Usually unstable access to GitHub. Retry behind a proxy or on a different network. The script only downloads + extracts, so re-running it is safe.
"App is damaged and can't be opened. You should move it to the Trash." A macOS security prompt. Run this command in Terminal, then open the app again:
xattr -cr "/Applications/Codex 对话管家.app""Cannot verify developer / unidentified developer" Open System Settings → Privacy & Security, scroll to the blocked-app prompt, and click Open Anyway — or right-click the app icon and choose Open.
App won't launch / crashes It runs on both Apple Silicon and Intel Macs but requires macOS 14+. Upgrade macOS if yours is older.
No conversations shown / "Codex directory not found"
It couldn't locate ~/.codex. Make sure Codex is installed and has been launched at least once. If your data lives elsewhere, use Choose Folder (top-left) to point at it.
Migrate/Delete does nothing — "Codex is running" Migration writes to the local store, so you must fully quit Codex (including the menu-bar icon) and end any background process spawned by the Codex panel in VS Code, then retry.
Migration succeeded, but the conversations still aren't visible in Codex Codex groups history by source. After migrating, reopen Codex and switch it to the target provider (API or Official) for the list to refresh. The provider marked "当前" (current) in the app's sidebar is the bucket Codex is showing right now.
Installed in the wrong place / want to uninstall
Drag Codex 对话管家.app from /Applications to the Trash. Backups remain in ~/Library/Application Support/Codex Vault/Backups and can be deleted manually.