中文
Codex App Manager 是官方 OpenAI Codex 桌面应用的安装 / 更新 / 卸载管理器:在本机检测已安装的 Codex,规划并执行安装、增量更新与干净卸载,并提供一键启动。它消费上游 codex-app-mirror 的镜像与 Sparkle 更新源来管理 Codex 本体(payload),同时自身也通过一套国内可达的镜像完成自更新。Manager 不构建、不修改 Codex,只做"安装与更新"这层客户端体验。
能力一览
| 能力 | 说明 |
|---|
| 🧭 一站式管理 | 检测本机 Codex 安装状态,规划安装 / 更新 / 卸载,一键启动 Codex |
| 🔄 增量更新(macOS) | 消费 codex-app-mirror 的 Sparkle appcast,只下载版本间的 delta 差量,EdDSA 签名字节级校验,失败自动回滚 |
| 🪟 Windows | MSIX / 便携版安装与暂存更新,安装后做 MSIX 健康检查并对被裁剪的系统给出提示 |
| 🆕 应用自更新 | Manager 自身经 R2(全球)+ IHEP S3(国内) 镜像更新,GitHub 兜底;更新签名签的是字节,镜像逐字节复制后依旧有效 |
| 🌏 国内可达 | 自更新与 payload 下载共用同一条镜像短链,按地域自动选路(国内 IHEP / 海外 R2),对用户透明 |
| 🎨 温润材质 UI | OKLCH 配色、材质质感、明暗双主题精雕,GSAP 编排的入场与转场动效 |
| 🌐 11 种语言 | 跟随系统语言自动选择,含阿拉伯语 RTL |
| 🍎 签名状态透明 | macOS 走 Developer ID 签名 + Apple 公证;Windows 安装器当前无 Authenticode 代码签名,自更新包有 Tauri updater 签名 |
下载与安装
macOS —— Homebrew(推荐)
brew install --cask wangnov/tap/codex-app-manager
直接下载
到 最新 GitHub Release 下载(全球),或用 agentsmirror 镜像直链(国内免梯子,Cloudflare Worker 按地域选路:中国大陆走 IHEP、海外走 R2):
| 平台 | 文件 | 镜像直链 |
|---|
| Apple Silicon Mac | CodexAppManager_aarch64.dmg | ⤓ 镜像下载 |
| Intel Mac | CodexAppManager_x86_64.dmg | ⤓ 镜像下载 |
| Windows x64 | CodexAppManager_x64-setup.exe | ⤓ 镜像下载 |
| Windows ARM64 | CodexAppManager_arm64-setup.exe | ⤓ 镜像下载 |
macOS 版本经 Developer ID 签名 + Apple 公证,首次打开不会被 Gatekeeper 拦截。Windows 安装器(CodexAppManager_x64-setup.exe / CodexAppManager_arm64-setup.exe)当前没有 Authenticode 代码签名,首次运行可能出现 SmartScreen 提示;应用内自更新使用的 Tauri updater 签名只校验下载字节,不代表 Windows 发行者信任。SignPath Foundation 申请已不再推进,项目已改为规划付费云 HSM 证书方案,在证书真正配置并验证前,当前下载不得被描述为已签名。详情见 代码签名政策与 Windows signing and verification。
下载后建议用同一 GitHub Release 的 SHA256SUMS 核验文件。Windows 可用 PowerShell,macOS 可用 shasum:
Get-FileHash .\CodexAppManager_x64-setup.exe -Algorithm SHA256
# 或 ARM64:
Get-FileHash .\CodexAppManager_arm64-setup.exe -Algorithm SHA256
shasum -a 256 CodexAppManager_aarch64.dmg
镜像直链恒指向最新版——/manager/latest/ 由 Cloudflare Worker 自动解析到当前发布,无需随版本更新;装好后 Manager 还会通过应用内自更新保持最新(见下)。
安装 Manager 后,真正的 Codex 桌面应用由 Manager 负责安装与更新——你不需要单独去下载 Codex 本体。
应用自更新(Manager 自身)
Manager 内置 Tauri updater,按以下顺序检查自身新版本:
https://codexapp.agentsmirror.com/manager/latest.json —— 自有镜像,全球走 R2、中国大陆自动分流到 IHEP S3https://github.com/Wangnov/Codex-App-Manager/releases/latest/download/latest.json —— GitHub 兜底
latest.json 里的签名签的是安装包字节而非 URL,镜像只是逐字节复制并改写下载地址,所以签名始终有效。每次正式发版,CI 会自动把产物与改写后的 latest.json 同步到两套镜像(安装包置于 …/manager/<版本>/… 的版本化路径,长缓存安全;latest.json 在固定根路径短缓存),因此无需依赖 GitHub 也能自更新——这对国内网络尤其重要。
管理与更新 Codex 本体
Manager 通过上游镜像管理 Codex 桌面应用本体:
- macOS:读取镜像的 Sparkle appcast(arm64 / x64),对照本机已装版本规划更新,优先下载 delta 差量包,校验 Sparkle 签名后原地替换,失败回滚;无匹配 delta 时回退完整包。
- Windows:从镜像获取 MSIX / 便携版并暂存更新,支持自定义安装目录,安装后做健康检查。
Codex 主题皮肤(素材化 UI)
Manager 内置 awesome-codex-skins(.codexskin 标准、工具链与画廊)的官方运行时:
- 在线皮肤库:主题页直连 skins.agentsmirror.com,一键安装(下载后 sha256 校验);
- 试穿:对运行中的 Codex 秒级热切换,不落盘、随时还原;应用:持久生效,含 Codex 原生 accent/字体配置;还原:一键回到原生外观;
- 导入:
.codexskin 文件选择或直接拖入主题页;
- 皮肤经 CDP 注入,不修改任何应用文件、签名完好;每张预览都是质量门下的真机截图。想自己做一款?生产线(Claude Code / Codex 通用的 Agent Skill)就在 awesome-codex-skins。
工作原理
检测 → 规划 → 执行
应用先在本机探测 Codex 的安装状态与平台能力,生成安装 / 更新 / 卸载计划,确认后再执行破坏性操作(更新前做版本与签名校验,规避 TOCTOU)。
双后端镜像 + 按地域分流
自更新与 payload 下载共用 codexapp.agentsmirror.com 这条短链,由 Cloudflare Worker 路由:全球从 R2 直供,中国大陆按 CF-IPCountry 分流到 IHEP S3 的预签名地址——同一条链接,自动选最优节点。
发布流水线
打 v* tag 触发 release.yml:四平台构建(瞬时下载失败自动重试)→ macOS inside-out Developer ID 签名 + 公证 + 重打 updater 包 → Windows updater 产物签名 → 发布 GitHub Release → 自动同步到 R2 + IHEP 镜像。
生态:codex-app-mirror
Manager 是 codex-app-mirror 的下游客户端。镜像负责把官方 Codex 安装包原样、可校验、国内可达地分发,并提供 Sparkle 增量更新源;Manager 负责把这些能力变成本地的安装与更新体验。两者职责清晰、各自窄而稳。
技术栈与本地开发
- 前端:React 19 · TypeScript · Vite · GSAP
- 外壳:Tauri v2(无边框弹层窗口)
- 后端:Rust 命令层 + 应用服务 / 端口 / 平台适配;
codex-mac-engine(Sparkle)与 codex-win-engine(MSIX/便携)两个独立 crate
npm install
npm run tauri:dev # 本地开发
npm run check # 类型检查
npm run tauri:build # 本地构建(未签名)
边界
- 不修改、不重打包 Codex 安装包
- 不绕过 OpenAI / Microsoft 的授权或本机安装策略
- 不伪造或重算 Sparkle 签名(只字节级复制官方签名)
- 不替代 OpenAI、Microsoft Store 的官方分发渠道
政策与隐私
- 代码签名政策:签名供应商方案(SignPath Foundation 已不再推进)、项目角色、逐次人工审批、可签工件边界与生产签名启用前的验证要求。
- 隐私政策:Manager 更新检查、下载源/代理网络行为、官网本地存储、本地诊断与第三方连接元数据。
致谢
- LINUX DO 社区 —— 安装体验、更新链路、问题反馈的讨论都汇聚于此。
- 中国科学院高能物理研究所(IHEP) —— 提供国内 S3 镜像存储,让中国大陆的自更新与下载低延迟直达。
Star History
许可
MIT。本项目与 OpenAI、Microsoft 无隶属或背书关系。
English
Codex App Manager is an install / update / uninstall manager for the official OpenAI Codex desktop app: it detects the locally installed Codex, plans and performs install, incremental update, and clean uninstall, and offers one-click launch. It consumes the upstream codex-app-mirror (mirror + Sparkle update feed) to manage the Codex payload, and also self-updates through its own China-reachable mirror. The Manager does not build or modify Codex — it owns only the client-side "install & update" experience.
At a glance
| Capability | Detail |
|---|
| 🧭 One-stop management | Detects the local Codex install, plans install / update / uninstall, launches Codex in one click |
| 🔄 Incremental update (macOS) | Consumes codex-app-mirror's Sparkle appcast, downloads only the delta between versions, verifies EdDSA signatures byte-for-byte, rolls back on failure |
| 🪟 Windows | MSIX / portable install and staged updates; MSIX health check after install, with a warning on stripped systems |
| 🆕 Self-update | The Manager updates itself via R2 (global) + IHEP S3 (China), with GitHub fallback; signatures sign the bytes, so a byte-identical mirror stays valid |
| 🌏 Reachable in China | Self-update and payload downloads share one mirror link, auto-routed by region (IHEP in China, R2 elsewhere) — transparent to users |
| 🎨 Warm material UI | OKLCH palette, material depth, polished dark + light themes, GSAP-orchestrated entrances and transitions |
| 🌐 11 languages | Auto-selected from the system locale, including Arabic RTL |
| 🍎 Transparent signing status | macOS Developer ID signing + Apple notarization; the Windows installer is not Authenticode-signed yet, while self-update artifacts carry the Tauri updater signature |
Download & install
macOS — Homebrew (recommended)
brew install --cask wangnov/tap/codex-app-manager
Direct download
Grab your platform's file from the latest GitHub Release (global), or use the agentsmirror mirror (no VPN needed in China; a Cloudflare Worker routes by region — IHEP for mainland China, R2 elsewhere):
| Platform | File | Mirror link |
|---|
| Apple Silicon Mac | CodexAppManager_aarch64.dmg | ⤓ mirror |
| Intel Mac | CodexAppManager_x86_64.dmg | ⤓ mirror |
| Windows x64 | CodexAppManager_x64-setup.exe | ⤓ mirror |
| Windows ARM64 | CodexAppManager_arm64-setup.exe | ⤓ mirror |
The macOS builds are Developer ID signed + Apple notarized, so Gatekeeper won't block first launch. The Windows installers (CodexAppManager_x64-setup.exe / CodexAppManager_arm64-setup.exe) are not Authenticode-signed yet, so SmartScreen may warn on first run; the Tauri updater signature used for in-app updates verifies bytes only and is not Windows publisher trust. The SignPath Foundation application is no longer being pursued; the project is instead planning a paid cloud-HSM certificate, and current downloads must not be described as signed until one is actually configured and verified. See the code signing policy and Windows signing and verification.
After downloading, compare the file with SHA256SUMS from the same GitHub Release. Use PowerShell on Windows or shasum on macOS:
Get-FileHash .\CodexAppManager_x64-setup.exe -Algorithm SHA256
# Or ARM64:
Get-FileHash .\CodexAppManager_arm64-setup.exe -Algorithm SHA256
shasum -a 256 CodexAppManager_aarch64.dmg
The mirror links always resolve to the latest release — /manager/latest/ is auto-resolved to the current version by the Cloudflare Worker, with no per-release edits; after install, the Manager also keeps itself up to date via in-app self-update (below).
Once the Manager is installed, it installs and updates the actual Codex desktop app for you — you don't need to download Codex separately.
Self-update (the Manager itself)
The Manager ships the Tauri updater and checks for new versions of itself in this order:
https://codexapp.agentsmirror.com/manager/latest.json — its own mirror: R2 globally, auto-failover to IHEP S3 for mainland Chinahttps://github.com/Wangnov/Codex-App-Manager/releases/latest/download/latest.json — GitHub fallback
The signatures in latest.json sign the installer bytes, not the URL, so the mirror only re-hosts the bytes verbatim and rewrites the download URL — the signature stays valid. On every stable release, CI syncs the artifacts and a rewritten latest.json to both mirrors (installers under a versioned path …/manager/<version>/… so long caching is safe; latest.json at the fixed root with a short cache), so self-update never depends on GitHub — which matters most inside China.
Managing & updating Codex itself
The Manager manages the Codex desktop payload through the upstream mirror:
- macOS: reads the mirror's Sparkle appcast (arm64 / x64), plans against the installed build, prefers the delta enclosure, verifies the Sparkle signature, then swaps in place with rollback on failure; falls back to the full archive when no delta matches.
- Windows: fetches the MSIX / portable build from the mirror and stages the update, with a configurable install directory and a post-install health check.
Codex skins (asset-based UI themes)
The Manager is the official runtime for awesome-codex-skins — the .codexskin standard, toolchain & gallery:
- Online skin library: the theme page pulls skins.agentsmirror.com for one-click installs (sha256-verified downloads);
- Try-on: live hot-swap on a running Codex, nothing persisted, instantly revertible; Apply: persistent, incl. native accent/font config; Restore: one click back to stock;
- Import: pick or drag a
.codexskin straight onto the theme page;
- Skins inject over CDP — no app file is modified, the signature stays intact; every preview is a real screenshot taken under an automated quality gate. Want to make your own? The production line (an agent skill for both Claude Code and Codex) lives in awesome-codex-skins.
How it works
Detect → plan → execute
The app first probes the local Codex install state and platform capabilities, produces an install / update / uninstall plan, and only then performs destructive operations (with a version + signature check before the swap to guard against TOCTOU).
Two-tier mirror + geo routing
Self-update and payload downloads share the codexapp.agentsmirror.com link, fronted by a Cloudflare Worker: global traffic is served straight from R2, mainland-China traffic is routed by CF-IPCountry to a presigned IHEP S3 URL — one link, auto-routed to the fastest node.
Release pipeline
Pushing a v* tag triggers release.yml: four-platform build (with automatic retry on transient download hiccups) → macOS inside-out Developer ID signing + notarization + updater repackage → Windows updater artifact signing → publish the GitHub Release → auto-sync to the R2 + IHEP mirror.
Ecosystem: codex-app-mirror
The Manager is the downstream client of codex-app-mirror. The mirror distributes the official Codex installers verbatim, verifiably, and reachably inside China, and serves the Sparkle incremental-update feed; the Manager turns those into a local install-and-update experience. Both stay narrow and stable, with clear responsibilities.
Tech stack & local development
- Frontend: React 19 · TypeScript · Vite · GSAP
- Shell: Tauri v2 (frameless popover window)
- Backend: Rust command layer with app services / ports / platform adapters; two standalone crates
codex-mac-engine (Sparkle) and codex-win-engine (MSIX/portable)
npm install
npm run tauri:dev # local development
npm run check # type-check
npm run tauri:build # local (unsigned) build
Non-goals
- Does not modify or repackage Codex installers
- Does not bypass OpenAI / Microsoft authorization or local install policies
- Does not forge or recompute Sparkle signatures (official signatures are copied verbatim)
- Is not a replacement for official OpenAI / Microsoft Store distribution
Policy and privacy
- Code signing policy: signing provider plan (SignPath Foundation is no longer being pursued), project roles, per-request human approval, artifact scope, and the verification required before production signing can go live.
- Privacy policy: Manager update checks, download-source and proxy behavior, website local storage, local diagnostics, and third-party connection metadata.
Acknowledgements
- LINUX DO community — the home for feedback on install experience, update links, and bug reports.
- Institute of High Energy Physics, Chinese Academy of Sciences (IHEP) — provides the S3 mirror storage that keeps self-update and downloads fast and reachable inside mainland China.
Star History
License
MIT. Not affiliated with or endorsed by OpenAI or Microsoft.
