# Codex App Windows 离线安装与更新手册 Codex App Windows 离线安装、已有安装更新、验证与常见问题处理。 # Codex App Windows 离线安装与更新手册 本文档用于指导 Windows 环境下 Codex App 的离线安装、已有安装更新与安装验证。 ## 1. 适用范围 - 操作系统：Windows 10、Windows 11、Windows Server 2022（需要桌面体验） - 安装方式：离线安装 `.msix` 应用包 - 适用场景：首次安装、已有安装更新、安装后验证、命令行入口检查 ## 2. Codex App 简介 - Codex App 是 Codex 的桌面工作台，用于集中管理编码任务、对话、项目和执行结果。 - 界面围绕线程、项目和任务进展组织信息，便于同时跟进多个编码请求。 - 应用强调对修改结果的可见性，适合在提交前查看差异、理解改动、继续调整或撤销。 - 官方能力覆盖 Worktrees、Local Environments、Commands、Windows 等本地开发衔接场景。 官方介绍页：[https://developers.openai.com/codex/app](https://developers.openai.com/codex/app)
[![Codex App 官方界面截图](https://docs.20020519.xyz/uploads/images/gallery/2026-04/pixpin-2026-04-30-18-56-34.png)](https://docs.20020519.xyz/uploads/images/gallery/2026-04/pixpin-2026-04-30-18-56-34.png)
Codex App 官方界面截图
## 3. 核心亮点 ### 3.1 内置版本控制与变更审查 相较于以往在终端中运行的 AI 编程工具，这类工具往往需要用户自行配置并熟练掌握 Git 进行版本追踪，否则在多轮对话后代码很容易“越改越乱”且难以回退。Codex App 很好地解决了这一痛点。它内置了开箱即用的 Git 版本控制机制，让代码变更管理变得直观而安全。 Codex App 的核心使用方式是围绕变更审查与确认展开的。应用会将 AI 对文件的每一次改动以差异（Diff）形式可视化展示，确保在实际提交或保存前，用户能够完全掌控代码的走向： - **红色高亮：**表示被删除或修改的旧内容。 - **绿色高亮：**表示新增或替换的新内容。 - **修改确认：**在应用改动前，可以直观地阅读差异内容，确认代码逻辑是否符合预期。 - **安全试错与撤销：**如果 AI 生成的结果不符合要求，不仅可以继续对话让其调整，也可以依赖内置的版本追踪一键撤销（Revert）当前改动，避免复杂修改破坏原有程序。
[![Codex App 实际变更审查截图](https://docs.20020519.xyz/uploads/images/gallery/2026-04/pixpin-2026-04-30-19-08-41.png)](https://docs.20020519.xyz/uploads/images/gallery/2026-04/pixpin-2026-04-30-19-08-41.png)
Codex App 实际变更审查截图
### 3.2 应用内浏览器 Codex App 提供应用内浏览器能力，可在不离开当前任务线程的情况下预览网页或本地开发服务。应用内浏览器适合用于查看渲染后的网页、对页面视觉效果添加评论，以及检查本地开发服务器、文件预览或无需登录的公开网页。 对于前端页面、数据可视化、仿真结果预览等任务，应用内浏览器可以把“代码修改”和“效果检查”放在同一个工作流中：左侧继续与 Codex 讨论和调整代码，右侧直接查看页面运行结果，从而缩短验证反馈链路。 - **本地服务预览：**可打开本机开发服务地址，例如 `http://127.0.0.1:4178`。 - **视觉反馈：**可以围绕页面布局、渲染结果和交互状态继续向 Codex 反馈修改要求。 - **结果验证：**适合检查前端界面、图形化输出、报告页面和仿真可视化结果。 - **使用边界：**涉及个人浏览器资料、扩展插件或复杂登录状态时，应使用常规浏览器完成验证。
[![Codex App 应用内浏览器实际截图](https://docs.20020519.xyz/uploads/images/gallery/2026-04/pixpin-2026-04-30-19-10-36.png)](https://docs.20020519.xyz/uploads/images/gallery/2026-04/pixpin-2026-04-30-19-10-36.png)
Codex App 应用内浏览器实际截图
## 4. 下载 .msix 安装包 Codex App 的 Windows 离线安装包格式为 `.msix`。优先使用自动更新直链；直链不可用时，再使用 Microsoft Store + rg-adguard 备选方案。 ### 4.1 推荐方式：自动更新直链 自动更新直链：[https://files.20020519.xyz/share/qlqPaQQp](https://files.20020519.xyz/share/qlqPaQQp) - 直接下载最新 x64 版 `.msix`。 - 该链接用于获取最新版本。 - 日常安装和更新优先使用该方式。 - 下载完成后，保留 `.msix` 文件，后续安装或更新直接使用。 #### 如何判断是否需要更新 1. 先在 Windows PowerShell 中查看当前已安装版本。 2. 再打开自动更新直链，查看 Codex 文件夹中标注的最新版本或更新时间。 3. 如果文件夹中的版本号或更新时间更新，则下载新版 `.msix` 并按“已有安装更新”步骤执行。 ``` Get-AppxPackage -Name "*OpenAI.Codex*" | Select-Object Name, Version, PackageFullName ``` ### 4.2 备选方式：Microsoft Store + rg-adguard 仅当自动更新直链暂时不可用时使用。 - Microsoft Store 链接：[https://apps.microsoft.com/detail/9plm9xgg6vks?referrer=psi&hl=zh-CN&gl=JP](https://apps.microsoft.com/detail/9plm9xgg6vks?referrer=psi&hl=zh-CN&gl=JP) - rg-adguard 网址：[https://store.rg-adguard.net/](https://store.rg-adguard.net/) 1. 打开 rg-adguard 网站。 2. 左侧选择 **URL (link)**。 3. 粘贴 Microsoft Store 链接。 4. 右侧选择 **RP**。 5. 点击最右侧对勾按钮开始解析。 6. 在解析结果中下载以 `OpenAI.Codex_... .msix` 结尾的主程序包。 > **注意** > > `.BlockMap` 是校验/映射文件，普通离线安装通常不需要下载。 ## 5. 首次安装 ### 5.1 双击安装 1. 找到下载好的 `.msix` 文件。 2. 双击该文件。 3. Windows 弹出“应用安装程序”后，点击“安装”。 4. 安装完成后，按 **Win** 键搜索 **Codex**。 5. 能看到应用图标并成功打开，即表示桌面应用安装完成。 ### 5.2 管理员 PowerShell 安装 如果双击无反应，或者需要通过命令行安装，请使用系统自带 PowerShell，并以管理员身份运行。 #### 确定安装包路径 在资源管理器中找到下载好的 `.msix` 文件，按住 **Shift** 键右击，选择“复制为路径”，然后将完整路径放入下面命令的引号中。 ``` $pkg = "" ``` #### 执行安装 ``` Add-AppxPackage -Path $pkg ``` #### 强制关闭应用后安装 ``` Add-AppxPackage -Path $pkg -ForceApplicationShutdown ``` #### 路径示例 ``` $pkg = "C:\Users\Administrator\Downloads\OpenAI.Codex_26.422.9565.0_x64__2p2nqsd0c76g0.msix" ``` ## 6. 已有安装更新 如果电脑上已经安装过 Codex App，后续更新通常不需要卸载。按以下最小路径操作即可。 ### 6.1 更新前准备 **必须完全退出以下所有 Codex 相关进程：** 1. 关闭 Codex App 所有窗口，检查任务栏托盘区 Codex 图标也已退出 2. 关闭 VS Code / Cursor，或禁用其中的 Codex / ChatGPT 扩展 3. 如果终端中有正在运行的 `codex` CLI，按 `Ctrl+C` 终止 **强制清理残留进程（以管理员身份运行 PowerShell）：** ``` Get-Process -Name Codex,codex,node_repl -ErrorAction SilentlyContinue | Stop-Process -Force Start-Sleep -Seconds 3 # 确认已全部终止（应无输出） Get-Process -Name Codex,codex,node_repl -ErrorAction SilentlyContinue ``` **备份配置文件：** ``` $ts = Get-Date -Format 'yyyyMMdd-HHmmss' Copy-Item "$env:USERPROFILE\.codex\config.toml" ` "$env:USERPROFILE\.codex\config.toml.bak-$ts" ``` **下载最新 `.msix` 安装包**（优先使用 4.1 节自动更新直链）。 ### 6.2 一键更新命令 将命令中的安装包路径替换为实际下载的 `.msix` 文件路径。 ``` Get-Process -Name Codex,codex,node_repl -ErrorAction SilentlyContinue | Stop-Process -Force Start-Sleep -Seconds 2 Add-AppxPackage -Path "你的安装包路径.msix" -ForceApplicationShutdown ``` > **注意** > 更新后请务必执行 6.3 节清理旧 extracted runtime。 ### 6.3 清理旧 extracted runtime Codex App 在 Windows 上采用双 runtime 架构：
位置角色更新方式
`C:\Program Files\WindowsApps\OpenAI.Codex_*\`MSIX 包本体随 `Add-AppxPackage` 更新
`%LOCALAPPDATA%\OpenAI\Codex\bin\`per-user extracted runtime**不会自动更新**
**MSIX 更新不会覆盖 `AppData` 里的旧 runtime。** 如果旧 runtime 缺少 sandbox helper（`codex-windows-sandbox-setup.exe`、`codex-command-runner.exe`），更新后 sandbox 初始化将持续失败，反复提示 `Set up agent sandbox` 或 `Configure agent sandbox to continue`。 **解决办法：重命名旧 runtime 目录（不删除，可回退）：** ``` $oldBin = "$env:LOCALAPPDATA\OpenAI\Codex\bin" if (Test-Path $oldBin) { $ts = Get-Date -Format 'yyyyMMdd-HHmmss' Rename-Item $oldBin "bin.old-$ts" Write-Host "已重命名为 bin.old-$ts" } ``` 新版 App 启动后会自动提取完整 runtime 到该目录。如需回退，改回原名即可。 ### 6.4 验证版本（可选） ``` Get-AppxPackage -Name "*OpenAI.Codex*" | Select-Object PackageFullName ``` > **更新路径** > > 退出 Codex -> 清理残留进程 -> 备份配置 -> 重命名旧 runtime -> 执行 `Add-AppxPackage` -> 可选验证版本 ## 7. 安装验证 ### 7.1 验证桌面应用 - 按 **Win** 键搜索 **Codex** - 能看到应用图标并成功打开，即表示安装成功 ### 7.2 验证命令行入口 在 PowerShell 中执行： ``` Codex --version ``` 如果能输出版本号或帮助信息，说明命令行入口可用。 ### 7.3 验证 sandbox 正常初始化 1. 在 Codex App 中新建对话，选择一个干净的本地 NTFS 目录，例如 `C:\Users\<用户名>\code\Playground` 2. 确认不再出现 `Set up agent sandbox` 或 `Configure agent sandbox to continue` 提示 3. 尝试让 Codex 执行一个简单操作，例如读取文件，确认 sandbox 内命令可正常执行 ### 7.4 验证进程来源 ``` Get-Process -Name Codex,codex -ErrorAction SilentlyContinue | ForEach-Object { $_.Path } # 预期输出：所有路径包含 "WindowsApps\OpenAI.Codex_<新版本号>" # 异常信号：出现 "AppData\Local\OpenAI\Codex\bin\" 说明旧 runtime 仍在运行 ``` ## 8. Sandbox 故障排查 当 Codex App 反复提示 `Set up agent sandbox` 或 `Configure agent sandbox to continue`，且无法进入正常使用时，按以下步骤排查。 ### 8.1 查看 sandbox 日志 ``` %USERPROFILE%\.codex\.sandbox\sandbox.log ``` **关键错误模式**（如果出现则说明 helper 缺失）： ``` setup refresh: failed to spawn codex-windows-sandbox-setup.exe: program not found ``` ### 8.2 验证 helper 文件完整性 新版 MSIX 的 `app\resources\` 目录必须包含以下两个 helper 可执行文件：
文件作用
`codex-windows-sandbox-setup.exe`sandbox 初始化
`codex-command-runner.exe`沙箱内命令执行
``` $msixPath = (Get-AppxPackage -Name 'OpenAI.Codex').InstallLocation Get-ChildItem "$msixPath\app\resources\codex-*.exe" ``` ### 8.3 确认所有进程来自新版 MSIX ``` Get-Process -Name Codex,codex -ErrorAction SilentlyContinue | ForEach-Object { $_.Path } # 预期：所有路径包含 "WindowsApps\OpenAI.Codex_<版本号>" # 异常：出现 "AppData\Local\OpenAI\Codex\bin\" 则说明旧 runtime 仍在运行 ``` ### 8.4 切换 sandbox 模式 编辑 `%USERPROFILE%\.codex\config.toml`： ``` [windows] sandbox = "unelevated" # 从 "elevated" 改为 "unelevated" ``` 改完后完全退出并重启 Codex App。 ### 8.5 使用 npm Codex CLI 作为备用 runtime 如果 MSIX extracted runtime 持续异常，可临时指向 npm 安装的 Codex CLI： ``` # 确保 npm CLI 为最新版 npm install -g @openai/codex # 验证 npm 版本有完整 helpers $npmBase = "$env:APPDATA\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc" Test-Path "$npmBase\bin\codex.exe" Test-Path "$npmBase\codex-resources\codex-windows-sandbox-setup.exe" ``` 然后在 `%USERPROFILE%\.codex\config.toml` 中设置： ``` [mcp_servers.node_repl.env] CODEX_CLI_PATH = 'C:\Users\<用户名>\AppData\Roaming\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\bin\codex.exe' ``` ### 8.6 清理 stale sandbox 状态 ``` Remove-Item "$env:USERPROFILE\.codex\.sandbox\setup_marker.json" -Force -ErrorAction SilentlyContinue Remove-Item "$env:USERPROFILE\.codex\.sandbox-bin\*" -Force -ErrorAction SilentlyContinue ``` ## 9. 更新失败回退 如果新版 Codex App 出现无法解决的问题，可按以下步骤回退到旧版。 ### 9.1 恢复旧 extracted runtime ``` # 如果已按 6.3 节重命名为 bin.old-* Rename-Item "$env:LOCALAPPDATA\OpenAI\Codex\bin.old-*" "bin" ``` ### 9.2 恢复配置备份 ``` Copy-Item "$env:USERPROFILE\.codex\config.toml.bak-*" ` "$env:USERPROFILE\.codex\config.toml" -Force ``` ### 9.3 卸载新版 MSIX ``` Get-AppxPackage -Name 'OpenAI.Codex' | Remove-AppxPackage ``` ### 9.4 重新安装旧版 ``` Add-AppxPackage -Path "<旧版 msix 文件路径>" -ForceApplicationShutdown ``` --- 本文档允许非商业转载与分享，但需注明来源并保留作者署名。 ``` 来源：https://docs.20020519.xyz/books/codex-app-windows 作者：zhiangxu1093@gmail.com ```