macOS GUI 使用说明

June 10, 2026 · View on GitHub

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
  • 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 元数据
  • 写操作前会弹出确认
  • 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，关闭上述进程后重试。

如果日志显示跳过 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。

当前 Avalonia 11.3.x 构建可能显示 Tmds.DBus.Protocol 的 NuGet advisory warning。该依赖来自 Avalonia 桌面包的跨平台传递依赖；macOS 发布产物可构建运行，但发布前仍应按团队安全策略评估或升级 Avalonia。