# Codex 白名单测试版使用说明

## 适用范围

这套脚本为每台电脑生成独立的 Codex 测试副本，不修改 Microsoft Store 安装目录，也不共享账号或 API Key。

当前补丁已支持 Codex `26.803.10989.0` 和 `26.810.7004.0` 的前端资源。快捷方式会在启动前自动检查 Store 版本：如果版本仍使用已支持的白名单特征，会自动构建或复用对应测试副本；如果 Codex 更新后改动了内部特征，脚本会保留并启动上一次已验证的测试副本，同时提示等待公司发布兼容补丁，不会强行修改文件，也不会卡住日常使用。如果本机没有任何旧测试副本，才会提示先完成一次适配。

测试副本使用独立的 `CodexStudio.ico` 图标文件。若旧快捷方式曾显示白色通用图标，重新执行一次公司一键入口会刷新快捷方式；启动脚本也会在窗口创建后补设图标。该修复只影响测试副本和快捷方式，不修改 Microsoft Store 正式版。

## 前置条件

1. 本机已安装 Microsoft Store 版 Codex。
2. 本机已经可以正常使用 Codex，已有自己的 Provider 和授权信息。

授权信息不要写进脚本或压缩包，每个人使用自己的凭据。

## 给同事分发

可以直接分发同目录下的 `Codex白名单测试版-同事分发包.zip`。压缩包只包含脚本、说明和不含密钥的 `models.json`，不包含你的 `config.toml`、`auth.json` 或 API Key。

### 每台电脑必须配置模型目录

即使同事已经使用了一段时间的 Codex，也需要把统一的模型目录配置到本机。执行服务器提供的一键入口时，脚本会自动完成模型目录复制和 `config.toml` 更新，不需要手动编辑；下面的步骤仅适用于不使用一键入口、直接解压分发包的情况。每位同事在自己的电脑上：

1. 安装 Microsoft Store 版 Codex，并至少正常打开一次。
2. 解压分发包，在 PowerShell 中进入解压目录。
3. 将压缩包内的 `models.json` 复制到自己的 Codex 目录：

```powershell
$codexHome = Join-Path $env:USERPROFILE '.codex'
New-Item -ItemType Directory -Path $codexHome -Force | Out-Null
Copy-Item .\models.json (Join-Path $codexHome 'models.json') -Force
```

4. 在自己的 `config.toml` 中配置模型目录，指向本机的 `models.json`：

```toml
model_catalog_json = "~/.codex/models.json"
model = "dev-l-0.56x"
```

5. 执行构建和启动命令：

```powershell
powershell -ExecutionPolicy Bypass -File .\Build-CodexWhitelistTest.ps1
powershell -ExecutionPolicy Bypass -File .\Start-CodexWhitelistTest.ps1
```

如果该电脑之前已经构建过测试副本，仍需先确认 `models.json` 和 `model_catalog_json` 已更新，然后只运行启动命令即可。

首次自动安装完成后，脚本会在桌面和开始菜单创建“Codex Studio”快捷方式。日常直接点击这个快捷方式即可；它会先检查 Microsoft Store 版本，只有发现新版本时才自动构建新的白名单测试副本。

每台电脑都要单独执行构建，构建结果位于该电脑的 `%LOCALAPPDATA%\CodexWhitelistTest`，不会写入 Store 正式安装目录。

## 从服务器下载模型目录

公司服务器的编程智能体发布入口为 `https://gitlab.com/comluojian/agent-tools/-/raw/main/`。桌面版使用的模型目录位于 Codex 专用目录，例如：

```text
https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/catalog/latest/models.json
```

同事在自己的 PowerShell 中执行下面的命令，将文件下载到本机：

```powershell
$catalogUrl = 'https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/catalog/latest/models.json'
$codexHome = Join-Path $env:USERPROFILE '.codex'
$modelPath = Join-Path $codexHome 'models.json'
New-Item -ItemType Directory -Path $codexHome -Force | Out-Null
if (Test-Path -LiteralPath $modelPath) {
    Copy-Item -LiteralPath $modelPath -Destination "$modelPath.bak" -Force
}
Invoke-WebRequest -UseBasicParsing -Uri $catalogUrl -OutFile $modelPath
$catalog = Get-Content -Raw -Encoding UTF8 $modelPath | ConvertFrom-Json
$requiredSlugs = @('dev-s-0.56x', 'dev-t-0.56x', 'dev-l-0.56x', 'dev-0.55x', 'dev-0.54x', 'dev-m-0.54x')
if (@($requiredSlugs | Where-Object { @($catalog.models.slug) -notcontains $_ })) {
    throw '下载的模型目录缺少 dev-s/t/l-0.56 模型。'
}
```

下载后仍要确认本机 `config.toml` 使用：

```toml
model_catalog_json = "~/.codex/models.json"
model = "dev-l-0.56x"
```

服务器只提供模型元数据，不要把 API Key、`auth.json` 或其他授权信息放到下载目录。不要使用未经核验的 `irm ... | iex` 直接执行服务器脚本。

## 一条命令完成配置

桌面版文件已经放在服务器的 `agent-tools/codex/windows/desktop/latest` 目录：

- `Run-CodexCompanySetup.ps1`：桌面版一键配置入口。
- `Setup-CodexCompany.ps1`：自动安装脚本。
- `Codex白名单测试版-同事分发包.zip`：依赖文件和模型目录。

同事可以直接执行下面的一条命令，不需要手动下载入口脚本。命令只将入口脚本临时保存到 `%TEMP%`，执行完成后删除：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command '$u="https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest/Run-CodexCompanySetup.ps1"; $p=Join-Path ([IO.Path]::GetTempPath()) ("CodexCompany-" + [guid]::NewGuid().ToString("N") + ".ps1"); try { Invoke-WebRequest -UseBasicParsing -Uri $u -OutFile $p; & $p -DownloadBaseUrl "https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest" } finally { if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Force } }'
```

入口脚本会自动下载其他文件、配置模型目录、备份并更新 `model_catalog_json` 和 `model`、构建测试副本和启动测试版。Provider、服务地址、授权信息和其他配置不会被脚本修改。已有配置时，默认模型会统一设置为 `dev-l-0.56x`。

入口脚本默认访问：

```text
https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest/Setup-CodexCompany.ps1
https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest/Codex白名单测试版-同事分发包.zip
```

如果服务器把文件放在子目录，例如 `/downloads/codex`，只需把命令中的两个地址替换为：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command '$u="https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest/Run-CodexCompanySetup.ps1"; $p=Join-Path ([IO.Path]::GetTempPath()) ("CodexCompany-" + [guid]::NewGuid().ToString("N") + ".ps1"); try { Invoke-WebRequest -UseBasicParsing -Uri $u -OutFile $p; & $p -DownloadBaseUrl "https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest" } finally { if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Force } }'
```

服务器当前使用 HTTP，若后续启用 HTTPS，应同步替换命令中的协议。入口脚本和 ZIP 不要包含任何密钥。

## 升级和失败回退

一键入口把一次升级当作一个完整事务处理，首次使用和重复升级都不需要用户手动清理：

1. 下载的新分发包先保存到临时目录，检查 ZIP、脚本和 `models.json` 是否完整，并确认公司模型 ID 存在；校验失败时不会替换本机内容。
2. 如果本机已经使用过公司测试版，脚本会先备份旧分发包、`config.toml`、`models.json` 和“Codex Studio”快捷方式，再切换到新分发包。首次使用没有旧分发包时，只备份本机已有的配置和快捷方式。
3. 脚本更新模型目录和默认模型，默认值为 `dev-l-0.56x`，然后从 Microsoft Store 正式安装目录复制出独立测试副本。Store 正式安装目录不会被修改。
4. 新版 Codex 的内部白名单特征已适配时，脚本完成构建、快捷方式更新和启动检查后才提交升级；提交成功后自动清理事务备份，并清理更早的测试程序文件，只保留当前测试程序和上一个可回退副本。测试副本的 `profile` 和共享任务记录不删除。
5. 如果下载、校验、配置、构建、快捷方式或启动任一步失败，脚本会自动恢复旧分发包、配置和快捷方式，并删除本次新建的测试程序文件。若 Codex 更新后尚未适配，只要本机有旧测试副本，就继续启动旧副本并提示等待兼容补丁；没有旧副本时才提示本次不能完成。
6. 如果电脑在升级中断电或进程被强制结束，下一次执行入口会先读取事务记录并恢复旧状态，再开始新的升级。用户不需要定位目录或手动删除缓存。

一键配置命令会先判断本机是否已经完成同一分发包的公司配置：模型目录、默认模型、有效测试副本、快捷方式和分发包 SHA256 都一致时，立即成功返回，不重新下载 ZIP、不重写配置、不重建测试副本、不重复启动。只有状态缺失、文件被改动或分发包版本变化时，才进入升级事务。恢复官方模型前仍需先完全关闭测试版窗口；恢复命令会先判断是否仍存在公司配置或测试资源，已经是官方状态时立即成功返回，不重复创建备份、不重复恢复或删除文件。因此误重复执行两类命令都不会产生额外改动。

## 构建测试版

在 PowerShell 中运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\Build-CodexWhitelistTest.ps1
```

脚本会自动寻找当前 Codex 安装，复制到：

```text
%LOCALAPPDATA%\CodexWhitelistTest\<Codex安装版本>
```

同时保留 `app.asar.original` 作为恢复备份。

## 启动测试版

推荐使用桌面或开始菜单中的“Codex Studio”快捷方式。快捷方式实际调用下面的启动脚本：

```powershell
powershell -ExecutionPolicy Bypass -File .\Start-CodexWhitelistTest.ps1
```

启动脚本会自动检查 Store 版是否升级：

- 没有升级：直接启动已有测试副本。
- 检测到新版本：自动运行构建脚本，完成后启动新测试副本。
- 新版本的过滤签名不匹配：停止并提示，不会强行修改。
- 启动检查会同时识别测试目录或独立 `profile` 下的后续进程；Codex 主进程完成启动交接并正常退出时，不再误判为启动失败。

启动参数默认关闭 GPU 硬件加速，以避免部分 Windows 显卡驱动导致 Codex 渲染进程持续占用 CPU。如果后续更新显卡驱动后需要恢复 GPU，可手动执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\Start-CodexWhitelistTest.ps1 -EnableGpu
```

关闭 GPU 只改变界面渲染路径，不影响模型调用、模型切换、对话、代码执行、终端和文件操作；动画、视频或复杂图形可能不如 GPU 流畅。

在测试版模型选择器中检查 `Dev S 0.56X`、`Dev T 0.56X`、`Dev L 0.56X`。测试版使用独立用户目录，正式 Codex 可以继续运行。

## 恢复测试版

先关闭测试版窗口，再运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\Restore-CodexWhitelistTest.ps1
```

恢复脚本只恢复测试副本，不会修改正式 Codex。

## 恢复官方模型

如果不再使用公司模型目录和白名单测试副本，执行下面的一条命令：

```powershell
irm 'https://gitlab.com/comluojian/agent-tools/-/raw/main/codex/windows/desktop/latest/Run-CodexOfficialRestore-Remote.ps1' | iex
```

命令会备份并移除 `config.toml` 中的 `model_catalog_json`，将默认模型设置为 `gpt-5.5`，恢复测试副本中的 `app.asar.original`，并在检测到 Microsoft Store 正式版后删除测试副本和“Codex Studio”快捷方式。Microsoft Store 正式安装目录不会被修改；测试副本的界面缓存、窗口状态和独立登录状态会被清理，但共享 `%USERPROFILE%\.codex` 中的任务记录不会被删除，正式 Codex 仍可看到这些任务。

## 维护边界

- 每台电脑都需要单独构建，不能只在服务器上配置一次。
- Codex 更新后由快捷方式自动检查并重新构建测试副本；如果新版本仍使用已支持的白名单特征，用户不需要人工处理。如果新版本改变内部特征，脚本会继续启动上一次已验证的测试副本并给出提示，我们更新服务器分发包后，用户重新执行入口命令即可。升级失败会自动回退，成功后自动清理旧测试程序文件。
- 该补丁只取消桌面模型选择器的动态白名单判断，仍遵守模型目录中的隐藏状态。
- `app.asar` 图标补丁始终等长原地写入，并保留 `app.asar.original`；不能手动用文本编辑器改写打包文件。
- 该补丁不改变服务器路由、权限、额度或上游模型调用逻辑。