Wangnov/Codex-App-Manager

跨平台桌面客户端 —— 一键安装、增量更新、干净卸载官方 Codex 桌面应用,自带国内可达的自更新。
A cross-platform desktop client to install, incrementally update, and cleanly uninstall the official Codex desktop app — with built-in, China-reachable self-update.

官网 · Official Website · 代码签名政策 · Code signing policy · 隐私政策 · Privacy policy · 中文 · English

本项目由 DuckCoding 赞助支持 为 Claude Code / Codex / Gemini CLI 提供按量计费的 API 中转服务。 Sponsored by DuckCoding — a pay-as-you-go API relay for Claude Code / Codex / Gemini CLI.

Codex App Manager 是官方 OpenAI Codex 桌面应用的安装 / 更新 / 卸载管理器:在本机检测已安装的 Codex,规划并执行安装、增量更新与干净卸载,并提供一键启动。它消费上游 codex-app-mirror 的镜像与 Sparkle 更新源来管理 Codex 本体(payload),同时自身也通过一套国内可达的镜像完成自更新。Manager 不构建、不修改 Codex,只做"安装与更新"这层客户端体验。

brew install --cask wangnov/tap/codex-app-manager

到 最新 GitHub Release 下载(全球),或用 agentsmirror 镜像直链(国内免梯子,Cloudflare Worker 按地域选路:中国大陆走 IHEP、海外走 R2):

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 内置 Tauri updater,按以下顺序检查自身新版本:

1. https://codexapp.agentsmirror.com/manager/latest.json —— 自有镜像,全球走 R2、中国大陆自动分流到 IHEP S3
2. https://github.com/Wangnov/Codex-App-Manager/releases/latest/download/latest.json —— GitHub 兜底

latest.json 里的签名签的是安装包字节而非 URL,镜像只是逐字节复制并改写下载地址,所以签名始终有效。每次正式发版,CI 会自动把产物与改写后的 latest.json 同步到两套镜像(安装包置于 …/manager/<版本>/… 的版本化路径,长缓存安全;latest.json 在固定根路径短缓存),因此无需依赖 GitHub 也能自更新——这对国内网络尤其重要。

Manager 通过上游镜像管理 Codex 桌面应用本体:

• macOS:读取镜像的 Sparkle appcast(arm64 / x64),对照本机已装版本规划更新,优先下载 delta 差量包,校验 Sparkle 签名后原地替换,失败回滚;无匹配 delta 时回退完整包。
• Windows:从镜像获取 MSIX / 便携版并暂存更新,支持自定义安装目录,安装后做健康检查。

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 镜像。

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 镜像存储,让中国大陆的自更新与下载低延迟直达。

MIT。本项目与 OpenAI、Microsoft 无隶属或背书关系。

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.

brew install --cask wangnov/tap/codex-app-manager

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):

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.

The Manager ships the Tauri updater and checks for new versions of itself in this order:

1. https://codexapp.agentsmirror.com/manager/latest.json — its own mirror: R2 globally, auto-failover to IHEP S3 for mainland China
2. https://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.

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.

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.

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).

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.

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.

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.

• 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

• 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

• 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.

• 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.

MIT. Not affiliated with or endorsed by OpenAI or Microsoft.