macOS GUI 使用说明

July 31, 2026 · View on GitHub

中文 · English

CodexProviderSync.app 是 macOS 桌面版 GUI，使用 Avalonia 构建，复用 desktop/CodexProviderSync.Core 的状态、同步、切换、恢复和清理逻辑。

构建

需要 .NET 10 SDK。

./scripts/publish-gui-macos.sh

构建 Intel (x86_64) 版本：

./scripts/publish-gui-macos.sh --runtime osx-x64 --output artifacts/osx-x64

默认产物：

artifacts/osx-arm64/CodexProviderSync.app

如需指定 SDK：

DOTNET=/path/to/dotnet ./scripts/publish-gui-macos.sh

功能

  • 选择或输入 Codex Home，默认 ~/.codex
  • 为每个 Codex Home 单独指定 SQLite Home；留空时按配置自动解析
  • Refresh 查看当前 provider、rollout provider counts、SQLite provider counts、备份统计、project visibility 和 encrypted_content 风险提示
  • Provider 列表展示 config、rollout、SQLite、manual 来源
  • 手动添加或删除 provider
  • Sync Metadata Only
  • Switch config.toml and sync
  • Restore Backup，可选择恢复 config.toml、SQLite、rollout metadata
  • Clean Old Backups
  • Open Backup Folder
  • 执行日志和错误提示

安全边界

  • App 启动和 Refresh 不会修改 Codex Home 下的 session、SQLite 或 config.toml 元数据
  • 写操作前会弹出确认
  • metadata v2 备份恢复到不同 SQLite Home 时，会显示来源与目标并再次确认
  • sync 和 switch 由 Core 先创建 backup，再修改 metadata
  • encrypted_content 只提示风险，不承诺修复
  • 不处理 auth.json
  • 不登录、不认证
  • 不修改对话内容
  • 不修改 updated_at

操作建议

执行 Sync Metadata Only、Switch config.toml and sync、Restore Backup 或 Clean Old Backups 前，先关闭：

  • Codex CLI
  • Codex App
  • app-server
  • 仍在使用相关 Codex Home 的终端任务

如果看到 state_5.sqlite is currently in use，关闭上述进程后重试。

SQLite Home 的解析优先级为：GUI override → config.toml 根级 sqlite_home → CODEX_SQLITE_HOME → <Codex Home>/sqlite。GUI override 按 Codex Home 保存在 App settings 中，不会写入 config.toml。显式位置缺库时只允许刷新诊断，写操作不会回退到其它数据库；默认布局中的数据库被删除时，可以从有效备份恢复到原默认位置。恢复到不同 SQLite Home 时必须取消勾选配置恢复，并再次确认来源和目标。

如果日志显示跳过 locked rollout files，通常表示当前会话仍占用 rollout 文件。同步大多已完成；等会话结束后再运行一次 sync 可补齐这些文件。

发布说明

scripts/publish-gui-macos.sh 默认发布 osx-arm64 self-contained .app bundle，并在本机可用时执行 ad-hoc codesign。该脚本不修改 Windows GUI 发布脚本 scripts/publish-gui.ps1。

macOS 桌面项目当前使用 Avalonia 12.0.4。ad-hoc 签名不等同于 Apple Developer ID 签名或公证。

项目目前提供 macOS 构建脚本，GitHub Releases 中没有预构建的 macOS 产物，请使用上述命令在本地构建。