CodexRelay
跨设备传递/备份 Codex CLI session（.jsonl）的桌面管理工具（macOS / Windows / Linux）。
目标：让你在不同电脑/不同系统上，也能通过 codex resume <session_id> 继续同一个会话（通过导出/导入 session 文件实现）。
注：本项目为社区工具，和 OpenAI 无官方从属关系。
技术栈：Tauri v2 + React + TypeScript + SQLite（后端 Rust）。
Why / 使用场景
- 多平台项目（Win / macOS / Linux）来回测试，需要把同一个 Codex 会话带到另一台机器继续解决兼容问题
- 两台电脑协同：用微信/网盘/邮件/AirDrop 传 zip 包即可迁移会话
- 备份：在本地建立“会话版本库”（vault + 历史记录），防止手滑覆盖/误删
How It Works / 工作方式
Codex CLI 会把会话写在本地 CODEX_HOME/sessions/**/rollout-*.jsonl（默认常见路径：~/.codex/）。
CodexRelay 负责：
- 扫描会话并展示列表
- 导出：把选中的会话打包为 zip（可合并为一个包或每会话单独包；默认导出到系统 Downloads）
- 导入：先解析/校验（manifest + size/sha256）并预览，再按冲突策略写入
CODEX_HOME - 在目标机执行：
codex resume <session_id>
Features (MVP)
- Sessions：扫描
CODEX_HOME/sessions/**/rollout-*.jsonl - Export：
- 生成可传输的
bundle.zip（manifest.json+rollout.jsonl） - 支持“合并为一个 zip”或“每会话单独 zip”，默认导出到 Downloads
- 生成可传输的
- Import：
- 导入前先解析/校验并预览最近消息，再决定是否写入
- 支持多选 zip
- 支持导入“合并导出包”（外层 zip 内含
bundles/*.zip，可选batch_manifest.json） - 冲突策略（recommended）：本机已存在同
session_id且指纹不同 -> “改 ID 导入”（保留两条分叉都可 resume）
- History / Vault：每次导入/导出/改ID/恢复都会存档 + 落库（SQLite）；支持收藏/标签；支持手动清理
- Restore：把任意历史版本恢复回
CODEX_HOME（会记录一次恢复动作） - Change ID：改写
session_meta.payload.id（默认不改forked_from_id） - Utilities：从 md/txt/“带噪声文本”中自动提取会话 ID（UUID）并去重
相关格式说明：docs/BUNDLE_FORMAT.md
Quick Start / 快速上手
- 在机器 A：勾选会话 -> 导出 zip（默认在 Downloads）
- 把 zip 传到机器 B（微信/网盘/邮件/AirDrop 均可）
- 在机器 B：导入 -> 预览/确认 -> 写入
- 在机器 B：
codex resume <session_id>
Download / 下载
- macOS：优先用 Homebrew（见下方 Install/Update），或从 GitHub Releases 下载 DMG
- Windows / Linux：从 GitHub Releases 下载安装包
Dev
pnpm install
pnpm tauri dev
Build (Desktop Bundles)
pnpm install
pnpm tauri build
产物目录（不同平台会生成不同格式）：
src-tauri/target/release/bundle/**- macOS:
bundle/dmg/*.dmg - Windows:
bundle/nsis/*-setup.exe（需要在 Windows 上构建；或用 GitHub Actions） - Linux(Ubuntu):
bundle/deb/*.deb
- macOS:
注：为避免 Linux 产物过大（AppImage 往往会打包大量依赖导致体积显著增大），当前默认只构建 deb；如需 AppImage / rpm，可在 src-tauri/tauri.conf.json 的 bundle.targets 里补回。
macOS “已损坏，无法打开”
结论：如果不做 Apple Developer ID 签名 + 公证（notarization），从浏览器下载的 DMG/App 很可能会被 macOS Gatekeeper 拦截并提示“已损坏，无法打开”（这是系统安全机制，并非一定是包真的坏了）。
免费分发场景下，通常只能给用户提供“放行”方式：
- 右键（或按住 Control 点击）App -> “打开”（会出现额外的允许打开选项）
如果你是自己使用（信任该来源），可以在把 App 拖到 /Applications 后执行：
sudo xattr -dr com.apple.quarantine /Applications/CodexRelay.app
GitHub Actions：见 .github/workflows/build-bundles.yml（支持手动触发 workflow_dispatch；打 tag v* 会自动构建并发布 GitHub Release，附带 SHA256SUMS.txt 校验文件）。
Install (macOS via Homebrew)
提供一个 Homebrew Tap（由另一个账号维护）：star-alp/homebrew-tap-CodexRelay
brew tap star-alp/tap-codexrelay
brew install --cask codexrelay
注：Homebrew 的 --no-quarantine 参数已 deprecated（未来可能移除）。如遇 Gatekeeper 拦截，请按上文右键“打开”或执行 xattr 放行即可。
Update (macOS)
- 推荐一条命令搞定（同时兼容“之前手动拖拽 DMG 安装 / Homebrew 没有接管 / 升级失败导致 cask 记录丢失”等情况）：
brew tap star-alp/tap-codexrelay && brew update && (brew upgrade --cask codexrelay || brew install --cask --force codexrelay)
- 如果你是通过 Homebrew 安装（
brew list --cask codexrelay能查到）：brew update && brew upgrade --cask codexrelay
- 如果你看到
Error: Cask 'codexrelay' is not installed.，说明你之前不是通过 Homebrew 安装（例如手动 DMG 拖拽）：- 继续用 DMG 更新：下载最新 Release 的
.dmg，将 App 拖到/Applications覆盖即可（如遇 Gatekeeper，按上文xattr放行）。 - 或让 Homebrew “接管”管理（会覆盖
/Applications/CodexRelay.app，不影响应用数据/存档库）：brew tap star-alp/tap-codexrelay && brew install --cask --force codexrelay
- 继续用 DMG 更新：下载最新 Release 的
- 应用内：
设置 -> 更新 -> 检查更新（会提示最新版本并提供打开 Release 的按钮）。
Recommended IDE Setup
Keywords
codex, codex-cli, session, resume, jsonl, backup, export, import, cross-device, cross-platform, tauri, rust, react, typescript, sqlite, homebrew, cask, macos, windows, linux