Codex App Windows 离线安装与更新手册

Codex App Windows 离线安装、已有安装更新、验证与常见问题处理。

Codex App Windows 离线安装与更新手册

本文档用于指导 Windows 环境下 Codex App 的离线安装、已有安装更新与安装验证。

1. 适用范围

2. Codex App 简介

官方介绍页：https://developers.openai.com/codex/app

Codex App 官方界面截图
Codex App 官方界面截图

3. 核心亮点

3.1 内置版本控制与变更审查

相较于以往在终端中运行的 AI 编程工具，这类工具往往需要用户自行配置并熟练掌握 Git 进行版本追踪，否则在多轮对话后代码很容易“越改越乱”且难以回退。Codex App 很好地解决了这一痛点。它内置了开箱即用的 Git 版本控制机制，让代码变更管理变得直观而安全。

Codex App 的核心使用方式是围绕变更审查与确认展开的。应用会将 AI 对文件的每一次改动以差异（Diff）形式可视化展示，确保在实际提交或保存前，用户能够完全掌控代码的走向：

Codex App 实际变更审查截图
Codex App 实际变更审查截图

3.2 应用内浏览器

Codex App 提供应用内浏览器能力，可在不离开当前任务线程的情况下预览网页或本地开发服务。应用内浏览器适合用于查看渲染后的网页、对页面视觉效果添加评论，以及检查本地开发服务器、文件预览或无需登录的公开网页。

对于前端页面、数据可视化、仿真结果预览等任务，应用内浏览器可以把“代码修改”和“效果检查”放在同一个工作流中：左侧继续与 Codex 讨论和调整代码，右侧直接查看页面运行结果，从而缩短验证反馈链路。

Codex App 应用内浏览器实际截图
Codex App 应用内浏览器实际截图

4. 下载 .msix 安装包

Codex App 的 Windows 离线安装包格式为 .msix。优先使用自动更新直链；直链不可用时，再使用 Microsoft Store + rg-adguard 备选方案。

4.1 推荐方式：自动更新直链

自动更新直链：https://files.20020519.xyz/share/qlqPaQQp

如何判断是否需要更新

  1. 先在 Windows PowerShell 中查看当前已安装版本。
  2. 再打开自动更新直链，查看 Codex 文件夹中标注的最新版本或更新时间。
  3. 如果文件夹中的版本号或更新时间更新，则下载新版 .msix 并按“已有安装更新”步骤执行。
Get-AppxPackage -Name "*OpenAI.Codex*" | Select-Object Name, Version, PackageFullName

4.2 备选方式：Microsoft Store + rg-adguard

仅当自动更新直链暂时不可用时使用。

  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 = "<PASTE_FULL_MSIX_PATH_HERE>"

执行安装

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 验证桌面应用

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.exesandbox 初始化
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