Codex App Offline

English

本项目提供两种使用 Codex 的方式，共享同一套离线技能 seed：

| 模式 | 前端 | 后端 | 平台 | |------|------|------|------| | 桌面版 | Codex Electron 原生 UI | 内置 Codex CLI | Windows | | 浏览器版 | 浏览器打开 http://127.0.0.1:3737 | 本机 Codex CLI | Windows / Linux / macOS |

• 桌面版：OpenAI Codex Windows 应用的非官方离线便携重打包——解压即用，无需 Store、无需登录 Microsoft 账户。
• 浏览器版（Web Gateway）：提供一个本地 Web 服务，在浏览器中使用 Codex 的全部功能。Gateway 负责渲染前端 UI 并将请求转发给本机安装的 @openai/codex CLI 执行。本质是 "Codex CLI 做后端，浏览器做前端" 的架构，因此跨平台通用。

[!TIP]

只想装官方原版、不需要离线重打包？ → 点击直接下载官方 MSIX（OpenAI 官方直链，始终为最新 Store 签名包，双击即可安装）。更多方式见 只要官方原版：MSIX 直链下载。

快速开始

Windows 完整包

从 Releases 下载 *-portable.zip，解压后：

portable ZIP 使用包根相对路径归档，以减少 Windows 解压时的路径长度；解压目录仍可自行命名。

1. 首次运行双击 Setup Codex.cmd，按提示完成引导
2. 日常使用桌面版：双击 Codex.cmd（无需 Node.js）
3. 使用浏览器版：先装 Node.js 18+，双击 Codex Web.cmd，浏览器打开 http://127.0.0.1:3737

完整包同时包含桌面版和浏览器版。桌面版开箱即用；浏览器版需要额外安装 Node.js。

也可以下载同版本的 *-setup.exe 直接安装。安装器里的“自定义 model 目录”默认不勾选；勾选后会安装包内目录并更新 config.toml。重新安装时取消勾选或卸载，只会清除安装器管理的目录和配置项，其他 Provider、API Key 与用户配置会保留。

浏览器版独立包（Web-Only / Windows / Linux / macOS）

# Linux 一键安装
wget https://raw.githubusercontent.com/lusipad/unofficial-codex-app-offline/main/scripts/setup-linux.sh
bash setup-linux.sh

安装后同一个脚本也可以做管理入口：

bash setup-linux.sh start
bash setup-linux.sh stop
bash setup-linux.sh status
bash setup-linux.sh restart
bash setup-linux.sh update

如果安装时选择了 systemd 服务，这些命令会优先调用 systemctl；否则回落到包内的 start.sh / stop.sh / status.sh。

手动安装：

1. 安装 Node.js 18+ 和 Codex CLI

npm install -g @openai/codex

1. 从 Releases 下载 *-web.zip 并解压
2. 首次安装依赖：Windows 双击 install.bat | Linux/macOS 执行 bash install.sh
3. 启动：Windows 双击 start.bat | Linux/macOS 执行 bash start.sh
4. 打开 http://127.0.0.1:3737

bash stop.sh
bash status.sh

公网部署：

# 端口 80 需要 root 或 setcap
sudo setcap 'cap_net_bind_service=+ep' $(which node)
写入 .env 持久化配置
cat > .env << EOF
HOST=0.0.0.0
PORT=80
CODEX_WEB_PASSWORD=你的强密码
EOF
bash install.sh
bash start.sh

LAN / 公网模式务必设密码。浏览器 UI 控制的是 gateway 所在机器的文件和进程，不要暴露到不受信网络。

只要官方原版：MSIX 直链下载

官方 Codex 的 MSIX 现在可以直接安装。如果不需要本项目的离线重打包，只想装官方版本：

一键直链（推荐）：下载官方 ChatGPT-x64.msix —— 这是 OpenAI 在企业部署文档中公布的直链，始终指向最新的 Store 签名包，文件未做任何修改。下载后双击安装，或用 PowerShell：

Add-AppxPackage .\ChatGPT-x64.msix

ARM 设备把链接中的 x64 换成 arm64（ChatGPT-arm64.msix）；离线批量部署还需要配套的 ChatGPT-License.xml（见 官方部署指南）。

备用方式一（本项目 Release）：下载 OpenAI.Codex-x64.msix —— 每次发布随包附带同一版本的未修改副本（SHA256 见同一 release 的 SHA256SUMS.txt），适合留档或官方直链不可达时使用。

备用方式二（网页）：打开 store.rg-adguard.net，左侧类型选 PackageFamilyName，输入 OpenAI.Codex_2p2nqsd0c76g0，通道选 Retail，点 ✔。在结果表格里下载最新的 OpenAI.Codex_<版本号>_x64__2p2nqsd0c76g0.msix（ARM 设备选 _arm64_ 那个；链接带时效，表格里同时给出 SHA1 可校验）。

备用方式三（脚本）：本仓库的解析脚本直接输出官方直链 JSON（含版本、ETag 与大小）：

node scripts/resolve-official-cdn-url.mjs --package-family-name OpenAI.Codex_2p2nqsd0c76g0

store.rg-adguard.net 是第三方解析服务，可能失效；rg_adguard 备用包源的解析脚本（resolve-store-bundle-url.mjs）在失效时会自动回退到 Playwright 浏览器流程。

包内结构

便携包（*-portable.zip）
├── Codex.cmd                 ← 桌面版启动器
├── Codex Web.cmd             ← 浏览器版 gateway 启动器
├── Setup Codex.cmd           ← 首次引导
├── _internal/
│   ├── app/                  ← Codex Desktop 应用（Electron）
│   ├── web/                  ← Node.js gateway 运行时
│   ├── chrome-extension/     ← 离线 Chrome 扩展
│   ├── seed/                 ← 离线技能种子
│   └── tools/                ← 修复/同步工具
浏览器版独立包（*-web.zip）     ← 三平台通用
├── install.bat / install.sh  ← 一次性安装 gateway 依赖
├── start.bat / start.sh      ← 启动 gateway，不安装依赖
├── stop.bat / stop.sh        ← 停止当前端口上的 gateway
├── status.bat / status.sh    ← 检查 /api/health
├── start-web.mjs             ← gateway 入口
├── gateway/dist/             ← 编译后的 gateway
├── cache/official-bundle/    ← 预提取 Codex 前端 UI
└── web-shell/                ← 登录页 + Electron polyfill

构建

npm ci
npx playwright install chromium
pwsh -NoProfile -File ./scripts/build-offline-package.ps1

产物输出到 dist/offline//。

构建需要一个能解压 .tar.xz 的工具来展开 primary runtime 插件包：tar --version 里带 liblzma 的 tar.exe（Windows 自带的 %SystemRoot%\System32\tar.exe 在部分 版本上只链接了 zlib），或者安装 7-Zip 作为回退。两者都没有时构建会直接失败并列出 检查过的路径。仓库路径过深或含非 ASCII 字符时，用 -WorkRoot C:\codex-build 指定 一个短的纯 ASCII 工作目录。

核心脚本

| 脚本 | 用途 | |------|------| | build-offline-package.ps1 | 主编排：拉取 Store 包 → 打补丁 → 打包 | | resolve-official-cdn-url.mjs | 解析 OpenAI 官方 CDN 直链（HEAD 读取包版本，默认包源） | | resolve-store-bundle-url.mjs | 解析 Microsoft Store CDN 下载链接（rg_adguard 备用包源） | | patch-app-asar.mjs | 给官方 app.asar 打兼容补丁 | | setup-linux.sh | Linux 安装与管理入口：install/start/stop/status/restart/update | | build-cross-platform.sh | 独立跨平台 Web 包构建 |

构建流程

1. 解析最新 Retail 版包源：默认 HEAD 请求 OpenAI 官方部署文档公布的直链（persistent.oaistatic.com/codex-app-prod/），也可用 rg_adguard 模式走 Store CDN
2. 下载 x64 .msix（旧列表为 .msixbundle 时先提取其中的 x64 应用载荷）
3. 给 app.asar 打补丁（脱离 MSIX、绕 feature gate、路径修复等）
4. 拉取官方 skills、下载 primary runtime 插件、Chrome 扩展
5. 编译 web-gateway TypeScript
6. 生成可选 API 模型目录，并打包：便携 ZIP + 跨平台 Web ZIP + 安装器 EXE

CI

每天 UTC 3:15 自动检查 Store 版本，有新版则构建发布。[force-rebuild] 提交标记可强制重建。

每个 Release 还会提供一个可选的 models-api.json，用于 API Key、CRS 和 DeepSeek 等 Responses API 场景。它不会默认启用；Windows 安装器可以按用户勾选安装包内副本，手动下载、配置、原生搜索验证和临时补丁退出条件见 API/custom provider 模型目录。

维护文档

架构决策、实施记录、版本故障排查和维护工具说明的完整清单（含每篇的现行/历史状态）见 docs/ 索引。

配置

标准离线使用无需配置。高级场景下创建包根目录的 skill-installer.env（模板在 _internal\skill-installer.env.example）：

| 变量 | 说明 | |------|------| | CODEX_HOME | Codex 主目录（默认 ~/.codex） | | GITHUB_TOKEN | 私有仓库或绕过速率限制 | | CODEX_SKILL_SOURCE_DIR | 本地技能目录（完全离线时使用） |

Web gateway 变量（start.sh 同级 .env 文件或环境变量）：

| 变量 | 默认值 | 说明 | |------|--------|------| | HOST | 127.0.0.1 | 监听地址 | | PORT | 3737 | 监听端口 | | CODEX_WEB_PASSWORD | — | 公网必备 | | CODEX_WEB_WORKSPACE_ROOTS | — | 允许 Web UI 访问的本地目录 |

风险与限制

• 离线版能用哪些官方功能、哪些不能用以及原因，见 离线功能清单。清单在离线包上实测生成；设置分区有变化时，Release 说明会单独列出。
• 默认包源是 OpenAI 官方部署文档公布的 CDN 直链（只提供最新 Retail 版）；备用的 store.rg-adguard.net 是第三方服务，可能失效
• Store 包内部结构变化后解包逻辑可能需调整
• Web gateway 需要 Node.js 18+ 和 @openai/codex CLI，当前包不捆绑这两者
• Chrome 扩展仍需用户手动加载一次
• 依赖第三方 OAuth 或在线 marketplace 的插件仍需网络

English

Two ways to use Codex, sharing the same offline skill seed:

| Mode | Frontend | Backend | Platform | |------|----------|---------|----------| | Desktop | Codex Electron native UI | Bundled Codex CLI | Windows | | Browser | Browser at http://127.0.0.1:3737 | Local Codex CLI | Windows / Linux / macOS |

• Desktop: Unofficial offline portable repack of the OpenAI Codex Windows app — extract and run, no Store or Microsoft account required.
• Browser (Web Gateway): A local web server that lets you use Codex from any browser. The gateway serves the frontend UI and proxies requests to a locally installed @openai/codex CLI. Architecture is "Codex CLI as backend, browser as frontend" — hence cross-platform.

[!TIP]

Only want the official app, without this offline repack? → Download the official MSIX directly (OpenAI's official link, always the latest Store-signed package; double-click to install). More options in Official MSIX via direct link.

Quick Start

Windows full package: Download -portable.zip from Releases, extract, run Setup Codex.cmd once, then Codex.cmd for desktop mode. For browser mode: install Node.js 18+, then run Codex Web.cmd and open http://127.0.0.1:3737. You can also use the matching -setup.exe; its optional custom-model task is unchecked by default, and later unchecking or uninstalling removes only the installer-managed catalog while preserving providers, API keys, and other settings.

Browser mode (all platforms): Install Node.js 18+ and npm install -g @openai/codex, download *-web.zip, run install.bat / bash install.sh once, then run start.bat / bash start.sh. Open http://127.0.0.1:3737. Stop with stop.bat / bash stop.sh; check status with status.bat / bash status.sh.

Linux guided setup:

wget https://raw.githubusercontent.com/lusipad/unofficial-codex-app-offline/main/scripts/setup-linux.sh
bash setup-linux.sh
bash setup-linux.sh status
bash setup-linux.sh update

Official MSIX via direct link

The official Codex MSIX now installs directly. If you only want the official app without this offline repack:

One-click link (recommended): Download the official ChatGPT-x64.msix — the direct link published in OpenAI's enterprise deployment guide, always pointing at the latest Store-signed package, unmodified. Double-click to install, or via PowerShell:

Add-AppxPackage .\ChatGPT-x64.msix

On ARM devices swap x64 for arm64 (ChatGPT-arm64.msix); offline provisioning also needs the matching ChatGPT-License.xml (see the official deployment guide).

Fallback 1 (this project's Release): Download OpenAI.Codex-x64.msix — an unmodified copy of the same version ships with every release (SHA256 in SHA256SUMS.txt), handy for archiving or when the official link is unreachable.

Fallback 2 (web): open store.rg-adguard.net, pick PackageFamilyName on the left, enter OpenAI.Codex_2p2nqsd0c76g0, select the Retail ring, and click ✔. Download the latest OpenAI.Codex__x64__2p2nqsd0c76g0.msix from the results table (pick _arm64_ on ARM devices; links expire, and the table also lists the SHA1 for verification).

Fallback 3 (script): this repo's resolver prints the official link as JSON (version, ETag and size):

node scripts/resolve-official-cdn-url.mjs --package-family-name OpenAI.Codex_2p2nqsd0c76g0

store.rg-adguard.net is a third-party resolver and may go down; the rg_adguard fallback resolver (resolve-store-bundle-url.mjs) then falls back to a Playwright browser flow automatically.

Building from Source

Windows 10/11 x64, Node.js 18+, PowerShell 7+, optional Inno Setup 6.

Extracting the primary runtime plugin archive needs a .tar.xz reader: a tar.exe whose tar --version reports liblzma (some Windows builds ship %SystemRoot%\System32\tar.exe linked against zlib only), or 7-Zip as a fallback. Pass -WorkRoot C:\codex-build when the checkout path is deep or contains non-ASCII characters.

npm ci
npx playwright install chromium
pwsh -NoProfile -File ./scripts/build-offline-package.ps1

Artifacts: dist/offline// — portable zip, web zip, setup exe, optional models-api.json, and SHA256SUMS.

Config

See config/offline-package.json. Key fields:

| Field | Description | |-------|-------------| | appSource.ring | Retail / Preview / Insider | | appSource.mode | official_cdn (default, OpenAI CDN direct link), rg_adguard (Store download), or installed_store (local) | | appSource.cdnUrl | Official CDN package URL used by the official_cdn mode | | packaging.portableZip | Generate portable ZIP | | packaging.crossPlatformWeb | Generate cross-platform web ZIP | | packaging.setupExe | Generate Inno Setup installer |

CI runs daily at 3:15 UTC. Commits tagged [force-rebuild] trigger a rebuild even if the Store version hasn't changed.

Each Release also includes an optional, version-matched models-api.json for API-key, CRS, DeepSeek, and other Responses-compatible providers. It is not enabled by default; the Windows installer can install the bundled copy when selected. See the API/custom provider model catalog guide.

Risks

• Which official features work offline, which do not, and why: see the offline feature list (Chinese). It is measured on the offline package; when the Settings sections change, the release notes list the changes.
• The default package source is the official CDN direct link from OpenAI's deployment guide (latest Retail only); the fallback store.rg-adguard.net is a third-party service that may go down
• Store package structure changes may break extraction
• Web gateway requires Node.js 18+ and @openai/codex CLI (not bundled)
• Chrome extension still needs manual install step