给 Codex 换上全屏背景 | Windows 完整安装、换肤与主题制作教程

xintgong

120人浏览 · 2026-07-18 12:00:10

xintgong · 2026-07-18 12:00:10 发布

Codex Dream Skin：Windows 完整安装、换肤与主题制作教程

适用平台：Windows 10 / Windows 11
适用客户端：Microsoft Store 安装的官方 Codex 桌面端（包名 OpenAI.Codex）
项目地址：Fei-Away/Codex-Dream-Skin
本文以 Windows 版脚本为准，更新时间：2026-07-18
可以直接用的背景图：https://pan.quark.cn/s/3473afe15c71

效果预览

下面是 Dream Skin 在真实 Codex 首页中的浅色与暗色注入效果。侧栏、项目选择器、推荐卡片和输入框均为 Codex 原生控件。

在这里插入图片描述

浅色主题实机效果。

在这里插入图片描述

暗色主题实机效果。

这两张图片包含真实 Codex 界面，只用于效果预览，不能作为主题背景导入。制作主题时请使用不含按钮、侧栏、卡片、输入框或文字的纯背景图。

八种概念风格

以下图片展示 Dream Skin 可以实现的八种视觉方向。它们都包含概念界面，只适合参考效果，不能直接作为主题背景导入。

1. 粉系定制

在这里插入图片描述

2. 财神打工版

在这里插入图片描述

3. 红白科幻

在这里插入图片描述

4. 清透定制

在这里插入图片描述

5. 灵感小宇宙

在这里插入图片描述

6. 紫夜限定

在这里插入图片描述

7. 青蓝虚拟歌姬

在这里插入图片描述

8. 舞台黑金

在这里插入图片描述

想制作同类主题时，应重新准备或生成一张不含 Codex 界面、文字和按钮的纯背景图，再按照第 7 节的方法导入。

效果预览
八种概念风格
1. 项目原理与安全边界
2. 安装前准备
3. 获取 Codex Dream Skin
4. 首次安装
5. 启动和重新应用主题
6. 托盘菜单的使用方法
7. 制作自己的图片主题
8. 高级主题配置：theme.json
9. 验证主题是否真正生效
10. 文件、状态和日志位置
11. 更新 Codex 或 Dream Skin
12. 恢复官方外观与卸载
13. 常见问题与故障排除
14. 推荐的日常使用流程
15. 命令速查表

1. 项目原理与安全边界

Codex Dream Skin 不是修改官方安装包的“破解主题”。它通过 Chromium DevTools Protocol（CDP）连接本机正在运行的 Codex 渲染器，向真实 Codex 界面注入背景层、CSS 和辅助 DOM。

它的特点包括：

不修改 WindowsApps 中的官方文件。
不修改 app.asar、程序签名或官方可执行文件。
不替换真实按钮、侧栏、输入框和项目选择器。
背景装饰层使用 pointer-events: none，不会拦截真实控件点击。
支持页面切换、渲染器刷新后的自动重新注入。
支持暂停、换图、保存主题、切换主题以及恢复官方外观。
主题状态、图片和日志保存在当前 Windows 用户的本地数据目录中。

1.1 重要安全说明

主题模式会让 Codex 以本机调试端口启动。脚本只将调试端口绑定到：

127.0.0.1

因此局域网内其他设备不能直接访问，但 CDP 本身不验证同一 Windows 用户下的其他本地进程。使用主题期间：

不要运行来源不明的本地程序。
不要把调试端口转发到局域网或公网。
暂时不用主题时，可以执行 Restore，关闭 CDP 调试会话。
不要手动修改、接管权限或替换 C:\Program Files\WindowsApps 内的文件。

1.2 不会被修改的内容

正常安装和使用不会主动改写：

Codex 登录状态。
对话和任务记录。
项目列表。
Codex 插件。
桌面宠物。
API Key、Base URL 或模型供应商设置。
官方程序签名。

安装器可能对 %USERPROFILE%\.codex\config.toml 中 [desktop] 下的少量外观键进行安全、原子化调整。修改前会保存字节级备份，恢复时只处理对应外观键；也提供完整备份恢复功能。

2. 安装前准备

2.1 确认使用 Microsoft Store 版 Codex

打开“Windows PowerShell”，执行：

powershell.exe -NoProfile -Command "Get-AppxPackage -Name OpenAI.Codex | Select-Object Name, Version, PackageFullName, InstallLocation | Format-List"

正常情况下应看到：

Name            : OpenAI.Codex
Version         : ...
PackageFullName : OpenAI.Codex_...
InstallLocation : C:\Program Files\WindowsApps\OpenAI.Codex_...

如果没有输出：

确认 Codex 是从 Microsoft Store 安装的正式版本。
确认当前命令运行在安装 Codex 的同一个 Windows 用户下。
不要尝试把脚本强行用于来源不明的便携版或侧载版。

建议使用系统自带的 Windows PowerShell 5.1，即 powershell.exe。部分环境中的 PowerShell 7 无法正常加载 Appx 模块。

2.2 安装 Node.js 22 或更高版本

执行：

node --version

要求输出至少为：

v22.0.0

如果版本低于 22，先升级 Node.js；如果提示找不到 node，安装 Node.js 22 LTS 或更高版本，并重新打开终端。

2.3 建议准备的软件

Git：用于克隆和更新项目。
Windows PowerShell 5.1：用于运行安装、启动、托盘和恢复脚本。
图片编辑工具：用于裁剪自己的 16:9 背景图，可选。

2.4 安装前关闭 Codex

首次安装必须在 Codex 完全关闭时进行，因为安装器需要安全备份和检查 config.toml。

关闭前请：

发送或复制尚未发送的重要输入。
关闭所有 Codex 窗口。
等待数秒，让 Codex 后台进程正常退出。

可使用以下命令检查：

Get-Process -Name ChatGPT, Codex -ErrorAction SilentlyContinue

没有输出时，通常表示 Codex 已退出。

3. 获取 Codex Dream Skin

3.1 方案 A：使用已经安装到技能目录的版本

如果目录存在：

%USERPROFILE%\.agents\skills\codex-dream-skin

在 PowerShell 中设置路径：

$SkinRoot = Join-Path $env:USERPROFILE ".agents\skills\codex-dream-skin\windows"
Test-Path $SkinRoot

输出 True 即可继续。

3.2 方案 B：从 GitHub 克隆

在 PowerShell 中执行：

$InstallRoot = Join-Path $env:LOCALAPPDATA "CodexDreamSkinStudio"
git clone https://github.com/Fei-Away/Codex-Dream-Skin.git $InstallRoot
$SkinRoot = Join-Path $InstallRoot "windows"

如果目录已经存在，并且它是正常的 Git 仓库，可更新：

git -C $InstallRoot pull --ff-only

3.3 方案 C：下载 ZIP

打开项目 GitHub 页面。
选择 Code → Download ZIP。
解压到固定目录，不要放在随后会被清理的临时目录。
找到解压目录中的 windows 文件夹。
将 $SkinRoot 设置为该 windows 文件夹的绝对路径。

示例：

$SkinRoot = "D:\Tools\Codex-Dream-Skin\windows"

检查关键脚本：

Test-Path (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")
Test-Path (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")
Test-Path (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1")

三个命令都应返回 True。

4. 首次安装

4.1 标准安装

确保 Codex 已关闭，然后执行：

$SkinRoot = Join-Path $env:USERPROFILE ".agents\skills\codex-dream-skin\windows"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")

安装器会：

检查 Node.js 版本。
动态查找当前 Microsoft Store 版 Codex。
检查 Codex 是否仍在运行。
在 %LOCALAPPDATA%\CodexDreamSkin 初始化主题仓库。
保存安装前的 Codex 外观配置。
初始化活动主题和内置主题。
创建启动、托盘和恢复快捷方式。
启动托盘控制器。

4.2 不创建快捷方式

如果只想使用命令行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1") -NoShortcuts

4.3 使用自定义端口

默认首选端口为 9335。一般不需要手动指定；默认端口被占用时，启动器会在后续端口中寻找可用端口。

如确实要固定端口，例如 9444：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1") -Port 9444

之后启动、托盘、验证和恢复命令也应使用相同端口。

4.4 安装后首次启动

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")

成功后应看到类似：

Codex Dream Skin is active on verified loopback port 9335.

5. 启动和重新应用主题

5.1 推荐启动方式

主题不是永久写入官方应用。每次完全退出 Codex 后，应通过以下方式之一重新启动：

桌面的 Codex Dream Skin 快捷方式。
开始菜单中的 Codex Dream Skin。
start-dream-skin.ps1 命令。

如果直接点击官方 Codex 图标，Codex 会以普通模式启动，没有 CDP 端口，主题无法注入。

5.2 Codex 已经普通启动时

如果出现：

Codex is open without a verified Dream Skin CDP endpoint.
Close it first or explicitly use -RestartExisting.

有两种解决方法。

安全方式：

保存尚未发送的内容。
手动关闭 Codex。
再运行启动脚本。

明确授权自动重启：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

需要弹窗确认：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -PromptRestart

-RestartExisting 会关闭当前 Codex。执行前确认输入框中没有尚未保存的重要内容。

5.3 主题突然消失

常见原因是：

Codex 被完全关闭后，从官方图标普通启动。
Codex 更新后旧的 Browser ID 已失效。
注入 watcher 已随原 Codex 进程退出。
托盘中选择了“暂停皮肤”。

通常重新执行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

即可恢复。

6. 托盘菜单的使用方法

6.1 启动托盘控制器

安装器通常会自动创建并启动托盘程序。若找不到图标，先展开任务栏右下角的 ^ 隐藏图标区域。

也可以手动启动：

$TrayScript = Join-Path $SkinRoot "scripts\tray-dream-skin.ps1"
Start-Process powershell.exe `
  -ArgumentList @("-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", "`"$TrayScript`"") `
  -WindowStyle Hidden

6.2 托盘菜单功能

右键 Dream Skin 托盘图标后可看到：

状态：运行中/未运行/已暂停：显示当前状态和活动主题名称。
应用或重新应用：启动或重新注入主题；需要重启时会询问。
暂停皮肤：临时隐藏主题，但保留会话和主题数据。
继续显示皮肤：取消暂停。
更换背景图：导入 PNG、JPG、JPEG 或 WebP。
保存当前主题：把活动主题保存到主题库。
已保存主题：列出并切换已保存主题。
打开图片文件夹：打开 Dream Skin 管理的图片目录。
完全恢复 Codex：停止主题、关闭 CDP 并恢复官方模式。
退出托盘：只退出托盘控制器。

6.3 切换主题

右键托盘图标 → 已保存主题 → 选择主题名称

切换通常会热更新，不需要重新启动 Codex。

7. 制作自己的图片主题

7.1 图片要求

支持格式：

.png
.jpg
.jpeg
.webp

安全限制：

文件不能为空。
文件大小不能超过 16 MB。
任意一边不能超过 16384 像素。
总像素不能超过 5000 万像素。

推荐规格：

尺寸：2560 × 1440
比例：16:9
色彩：RGB / sRGB
格式：高质量 JPG 或 PNG

7.2 构图建议

Codex 左侧通常是侧栏，中间和右侧是首页、消息区和输入框。推荐：

人物或主体放在画面右侧约 60%～80% 的位置。
左侧保留低细节、低对比度区域，方便侧栏文字阅读。
画面中央下方不要堆积过多高亮细节，以免干扰输入框。
避免在图片中直接写文字，因为窗口缩放和裁切可能导致文字缺失。
不要把带 Codex 按钮、侧栏、卡片或输入框的效果截图当作背景。
使用纯背景素材，让真实 Codex UI 叠加在背景上。

7.3 导入并保存主题

右键托盘图标。
选择 更换背景图。
选择准备好的图片。
等待背景热更新。
检查首页、任务页、侧栏和输入框可读性。
右键托盘图标，选择 保存当前主题。
输入主题名称。
以后可在 已保存主题 中切换。

导入新图时，Windows 版会将以下项目重置为自动模式：

外观模式：auto
焦点：自动分析
文字安全区：auto
任务页显示模式：auto

图像分析在本地渲染器完成，不会上传图片。

7.4 主题设计检查清单

导入后检查：

左侧导航文字是否清晰。
首页标题是否有足够对比度。
项目选择器是否仍可点击。
输入框边界、文字和光标是否清晰。
普通任务页背景是否比首页安静。
窄窗口下主体是否仍在画面内。
没有横向滚动条。
图片中没有伪造 UI。
所有原生按钮都能正常点击。

8. 高级主题配置：theme.json

8.1 活动主题位置

%LOCALAPPDATA%\CodexDreamSkin\active-theme\theme.json

活动主题的图片也位于同一目录。最安全的操作顺序是：

先通过托盘导入图片。
再编辑自动生成的 theme.json。
保持 JSON 语法正确。
保存后等待 watcher 热更新。

8.2 基础示例

{
  "schemaVersion": 1,
  "id": "my-custom-theme",
  "name": "我的自定义主题",
  "brandSubtitle": "CODEX DREAM SKIN",
  "tagline": "让今天的工作台更有氛围。",
  "projectPrefix": "选择项目 · ",
  "projectLabel": "◉  选择项目",
  "statusText": "DREAM SKIN ONLINE",
  "quote": "MAKE SOMETHING WONDERFUL",
  "image": "art.jpg",
  "appearance": "auto",
  "art": {
    "focusX": 0.75,
    "focusY": 0.42,
    "safeArea": "left",
    "taskMode": "ambient"
  }
}

image 必须指向主题目录内真实存在的图片文件，不能使用目录外路径。

8.3 appearance

可选值：

值	说明
`auto`	优先跟随 Codex 原生计算出的浅色/深色模式，缺失时跟随系统
`light`	明确使用浅色可读层
`dark`	明确使用深色可读层

建议优先使用 auto。图片明暗分析只影响构图和可读层，不应强行反转用户明确选择的 Codex 外观模式。

8.4 focusX 与 focusY

焦点坐标范围为 0～1：

focusX = 0：最左侧。
focusX = 0.5：水平中央。
focusX = 1：最右侧。
focusY = 0：最上方。
focusY = 0.5：垂直中央。
focusY = 1：最下方。

人物位于右侧时，可以从下面的值开始调整：

"focusX": 0.72,
"focusY": 0.45

如果不想手动指定，可以设置为 null，由渲染器自动分析：

"focusX": null,
"focusY": null

8.5 safeArea

文字安全区表示哪个区域更适合放置 Codex UI：

值	适用情况
`auto`	自动分析
`left`	左侧适合放文字，主体通常在右侧
`right`	右侧适合放文字，主体通常在左侧
`center`	中央区域较干净
`none`	不指定安全区

多数“人物在右侧”的桌面主题适合：

"safeArea": "left"

8.6 taskMode

控制普通任务页中的背景表现：

值	说明
`auto`	根据图片宽高比和分析结果自动选择
`ambient`	整窗环境背景，任务页使用更强的安静遮罩
`banner`	在任务页更偏向横幅式表现，适合超宽图
`off`	普通任务页关闭图片，只在适合的页面展示主题

一般 16:9 图片推荐：

"taskMode": "ambient"

8.7 保存高级配置为主题

调整活动主题满意后：

右键托盘图标 → 保存当前主题 → 输入名称

保存后会在 %LOCALAPPDATA%\CodexDreamSkin\themes 创建独立目录，图片和配置会一起复制，不依赖活动主题目录。

9. 验证主题是否真正生效

9.1 自动验证

$Screenshot = Join-Path $env:TEMP "codex-dream-skin-verify.png"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\verify-dream-skin.ps1") `
  -ScreenshotPath $Screenshot

打开截图：

Start-Process $Screenshot

验证结果通常会包含：

shell: true
sidebar: true
composer: true
main: true
installed: true
stylePresent: true
pass: true

首页推荐卡片数量会根据窗口宽度和当前 Codex 版本变化，可能为 2～4 个，也可能在较窄窗口中减少或不显示；不能只用推荐卡数量判断主题失败。

9.2 手动验收

至少检查两个页面。

首页：

壁纸连续覆盖侧栏和主区。
标题、项目选择器和输入框是真实 Codex 控件。
侧栏与输入框具有协调的可读层。
没有伪造的界面截图。

普通任务页：

背景比首页更安静。
消息文字保持高对比度。
输入框不遮挡消息内容。
页面滚动正常。

交互检查：

点击真实项目选择器，确认项目菜单打开。
在输入框中输入文字，确认光标和文字清晰。
打开任务，再返回新任务页面。
确认按钮、侧栏和菜单均可正常点击。

10. 文件、状态和日志位置

10.1 运行数据根目录

%LOCALAPPDATA%\CodexDreamSkin

常见内容：

路径	用途
`active-theme\`	当前活动主题及图片
`themes\`	已保存主题库
`images\`	导入图片归档
`state.json`	当前端口、Browser ID、Codex 包身份、injector PID 等
`injector.log`	正常注入日志
`injector-error.log`	注入器警告和错误
`verify.log`	最近一次启动验证结果
`paused`	存在时表示主题暂停
`config.before-dream-skin.toml`	安装前配置备份

10.2 Codex 用户配置

%USERPROFILE%\.codex\config.toml

不要使用会改变编码的编辑器保存该文件。脚本要求严格 UTF-8，并以同目录原子替换方式写回。

10.3 不要手动删除 state.json 解决问题

state.json 包含用于安全识别 injector 和 Codex 包的关键信息。脚本发现 PID、路径、端口、Browser ID 或包身份不匹配时会停止操作并保留状态，这是安全保护。

优先使用：

启动脚本重新应用。
验证脚本诊断。
恢复脚本清理。

不要在不理解进程状态的情况下手动结束未知 Node 进程或删除状态文件。

11. 更新 Codex 或 Dream Skin

11.1 Codex 更新后

脚本每次启动都会动态查询当前 OpenAI.Codex 商店包，因此不依赖写死的版本目录。

Codex 更新后建议：

关闭所有 Codex 窗口。
重新运行安装脚本。
重新运行启动脚本。
执行验证脚本。

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")

11.2 Git 仓库版本更新

git -C $InstallRoot status --short
git -C $InstallRoot pull --ff-only

如果 status --short 显示本地修改，先确认这些修改是否需要保留，不要直接重置。

更新后运行测试：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "tests\run-tests.ps1")

node --check (Join-Path $SkinRoot "scripts\injector.mjs")
node --check (Join-Path $SkinRoot "assets\renderer-inject.js")

最后关闭 Codex，重新安装并启动。

12. 恢复官方外观与卸载

12.1 只结束主题会话并正常重开 Codex

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") -PromptRestart

它会停止主题 injector、关闭 CDP 会话，并以普通模式重新打开官方 Codex。

12.2 同时恢复安装前的外观键

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -PromptRestart

12.3 强制授权关闭当前 Codex

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -ForceRestart

执行前确认没有尚未发送的输入。

12.4 恢复安装前 config.toml 的完整字节备份

仅在配置确实损坏、选择性恢复无法解决时使用：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RecoverConfigBackup -PromptRestart

该操作会：

保存当前配置到带时间戳的恢复前备份。
恢复安装前的完整配置字节。
归档本次安装备份。

-RecoverConfigBackup 与 -RestoreBaseTheme 不能同时使用。

12.5 删除快捷方式

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -Uninstall -PromptRestart

-Uninstall 删除 Dream Skin 创建的桌面和开始菜单快捷方式，不会自动删除你的主题图片仓库或项目源代码。

12.6 恢复后不重新打开 Codex

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -ForceRestart -NoRelaunch

13. 常见问题与故障排除

13.1 `Codex is open without a verified Dream Skin CDP endpoint`

原因：Codex 已通过官方图标以普通模式启动，没有可信的 Dream Skin CDP 会话。

解决：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

或手动关闭 Codex 后重新运行启动脚本。

13.2 找不到托盘图标

点击任务栏右下角 ^。
检查隐藏图标。
手动启动托盘脚本：

$TrayScript = Join-Path $SkinRoot "scripts\tray-dream-skin.ps1"
Start-Process powershell.exe `
  -ArgumentList @("-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", "`"$TrayScript`"") `
  -WindowStyle Hidden

如果启动后立刻退出，检查脚本版本和 %LOCALAPPDATA%\CodexDreamSkin 中的日志。

13.3 托盘右键提示 `Items` 为空集合

旧版本托盘脚本可能没有允许首次打开时的空 WinForms 菜单集合，错误类似：

无法将参数绑定到参数“Items”，因为该参数为空集合。

首选解决方案：更新到包含修复的新版本。

如果必须修复旧的本地副本，在 scripts\tray-dream-skin.ps1 中找到：

[Parameter(Mandatory = $true)][System.Windows.Forms.ToolStripItemCollection]$Items

改为：

[Parameter(Mandatory = $true)][AllowEmptyCollection()][System.Windows.Forms.ToolStripItemCollection]$Items

保存后关闭旧托盘 PowerShell 进程，再重新启动托盘脚本。

13.4 `Another Codex Dream Skin ... operation is already running`

安装、启动、恢复和验证通过同一用户互斥锁串行执行。该错误表示另一个操作尚未完成。

处理方法：

等待正在进行的启动或恢复完成。
不要连续双击多个快捷方式。
检查是否有安装脚本正在等待 Codex 关闭。
不要通过删除锁文件解决；该锁是 Windows 命名互斥量，并不是普通文件。

13.5 找不到 Node.js 或版本过低

node --version
Get-Command node.exe

要求 Node.js 22 或更高版本。升级后重新打开终端再启动 Dream Skin。

13.6 找不到官方 Codex Store 包

执行：

powershell.exe -NoProfile -Command "Get-AppxPackage -Name OpenAI.Codex | Format-List Name, Version, PackageFullName, InstallLocation"

如果仍无输出，重新从 Microsoft Store 安装官方 Codex。不要修改脚本来绕过 Store 包身份和签名校验。

13.7 端口 9335 被占用

如果没有显式传 -Port，启动器会尝试寻找后续空闲端口。

如果需要固定其他端口，应在所有入口统一使用，例如：

$Port = 9444
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -Port $Port -RestartExisting

不要把端口绑定到 0.0.0.0 或局域网地址。

13.8 配置提示不支持的 TOML 结构

为了避免破坏配置，安装器会拒绝自动修改以下复杂结构：

[desktop.*] 嵌套子表。
desktop.key = ... dotted key。
重复的 [desktop]。
重复的目标外观键。
多行字符串或多行数组。
转义后等价于目标键的复杂写法。

不要绕过错误强制写入。先备份：

Copy-Item "$env:USERPROFILE\.codex\config.toml" `
  "$env:USERPROFILE\.codex\config.manual-backup.toml"

然后将需要的外观设置整理为普通单一表，例如：

[desktop]
appearanceTheme = "system"

保留所有与 Dream Skin 无关的配置。若不熟悉 TOML，停止操作并让熟悉配置格式的人协助检查。

13.9 图片导入被拒绝

检查：

扩展名是否为 PNG、JPG、JPEG 或 WebP。
文件是否为空。
是否超过 16 MB。
任意一边是否超过 16384px。
总像素是否超过 50MP。
文件是否损坏或扩展名与真实格式不符。
文件或主题目录是否位于符号链接、junction 等 reparse point 中。

13.10 主题切换了但画面没有立即变化

确认托盘状态不是“已暂停”。
等待 watcher 检测主题文件变化。
切换一次页面或新建任务。
选择“应用或重新应用”。
执行验证脚本查看 verify.log。

13.11 injector 日志显示 Browser identity closed

类似：

original CDP browser identity closed; watcher is stopping instead of reconnecting

这通常表示原 Codex 窗口已经关闭。watcher 拒绝连接到端口上后来出现的其他进程，这是正常的安全行为。通过 Dream Skin 启动脚本重新打开 Codex 即可。

13.12 Codex 更新后出现新旧版本同时运行

关闭所有 Codex 窗口，等待后台进程退出，然后重新运行安装和启动脚本。脚本不会在无法验证旧路径身份时强行结束未知进程。

13.13 验证失败后 Codex 自动恢复普通模式

这是启动回滚机制。启动器在验证失败时会尽量：

停止新 injector。
清理失败的状态记录。
关闭本次调试会话。
以无调试端口的普通模式重开 Codex。

检查 injector-error.log 和 verify.log 后再重试。

14. 推荐的日常使用流程

首次安装

检查 Store 版 Codex。
检查 Node.js 22+。
关闭 Codex。
运行 install-dream-skin.ps1。
运行 start-dream-skin.ps1。
运行验证脚本并检查截图。

每天启动

使用 Codex Dream Skin 快捷方式。
不要从官方图标普通启动；若已普通启动，使用 -RestartExisting。

制作新主题

准备 2560×1440 的纯背景图。
托盘选择“更换背景图”。
检查首页和任务页。
必要时调整 theme.json 的焦点、安全区和任务模式。
托盘选择“保存当前主题”。

暂时不用主题

短期隐藏：托盘选择“暂停皮肤”。
完全关闭调试会话：运行 Restore。

15. 命令速查表

先定义路径：

$SkinRoot = Join-Path $env:USERPROFILE ".agents\skills\codex-dream-skin\windows"

安装：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")

启动：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")

重启已打开的普通 Codex 并应用主题：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

启动托盘：

$TrayScript = Join-Path $SkinRoot "scripts\tray-dream-skin.ps1"
Start-Process powershell.exe `
  -ArgumentList @("-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", "`"$TrayScript`"") `
  -WindowStyle Hidden

验证并截图：

$Screenshot = Join-Path $env:TEMP "codex-dream-skin-verify.png"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\verify-dream-skin.ps1") `
  -ScreenshotPath $Screenshot

恢复官方模式：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") -PromptRestart

恢复安装前外观：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -PromptRestart

完整恢复并删除快捷方式：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -Uninstall -PromptRestart

运行自动测试：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "tests\run-tests.ps1")

node --check (Join-Path $SkinRoot "scripts\injector.mjs")
node --check (Join-Path $SkinRoot "assets\renderer-inject.js")

结语

Codex Dream Skin 的核心原则是：主题只存在于可恢复的本机渲染会话中，不修改官方安装包。日常使用时记住三点即可：

首次安装和 Codex 更新后，关闭 Codex 再运行安装脚本。
日常通过 Dream Skin 快捷方式或启动脚本打开 Codex。
不用主题时执行 Restore，安全关闭 CDP 会话并恢复官方模式。

浅色主题实机效果。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

暗色主题实机效果。

这两张图片包含真实 Codex 界面，只用于效果预览，不能作为主题背景导入。制作主题时请使用不含按钮、侧栏、卡片、输入框或文字的纯背景图。

八种概念风格

以下图片展示 Dream Skin 可以实现的八种视觉方向。它们都包含概念界面，只适合参考效果，不能直接作为主题背景导入。

1. 粉系定制

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

2. 财神打工版

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

3. 红白科幻

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

4. 清透定制

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

5. 灵感小宇宙

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

6. 紫夜限定

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

7. 青蓝虚拟歌姬

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

8. 舞台黑金

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

想制作同类主题时，应重新准备或生成一张不含 Codex 界面、文字和按钮的纯背景图，再按照第 7 节的方法导入。

效果预览
八种概念风格
1. 项目原理与安全边界
2. 安装前准备
3. 获取 Codex Dream Skin
4. 首次安装
5. 启动和重新应用主题
6. 托盘菜单的使用方法
7. 制作自己的图片主题
8. 高级主题配置：theme.json
9. 验证主题是否真正生效
10. 文件、状态和日志位置
11. 更新 Codex 或 Dream Skin
12. 恢复官方外观与卸载
13. 常见问题与故障排除
14. 推荐的日常使用流程
15. 命令速查表

1. 项目原理与安全边界

它的特点包括：

不修改 WindowsApps 中的官方文件。
不修改 app.asar、程序签名或官方可执行文件。
不替换真实按钮、侧栏、输入框和项目选择器。
背景装饰层使用 pointer-events: none，不会拦截真实控件点击。
支持页面切换、渲染器刷新后的自动重新注入。
支持暂停、换图、保存主题、切换主题以及恢复官方外观。
主题状态、图片和日志保存在当前 Windows 用户的本地数据目录中。

1.1 重要安全说明

主题模式会让 Codex 以本机调试端口启动。脚本只将调试端口绑定到：

127.0.0.1

因此局域网内其他设备不能直接访问，但 CDP 本身不验证同一 Windows 用户下的其他本地进程。使用主题期间：

不要运行来源不明的本地程序。
不要把调试端口转发到局域网或公网。
暂时不用主题时，可以执行 Restore，关闭 CDP 调试会话。
不要手动修改、接管权限或替换 C:\Program Files\WindowsApps 内的文件。

1.2 不会被修改的内容

正常安装和使用不会主动改写：

Codex 登录状态。
对话和任务记录。
项目列表。
Codex 插件。
桌面宠物。
API Key、Base URL 或模型供应商设置。
官方程序签名。

2. 安装前准备

2.1 确认使用 Microsoft Store 版 Codex

打开“Windows PowerShell”，执行：

powershell.exe -NoProfile -Command "Get-AppxPackage -Name OpenAI.Codex | Select-Object Name, Version, PackageFullName, InstallLocation | Format-List"

正常情况下应看到：

Name            : OpenAI.Codex
Version         : ...
PackageFullName : OpenAI.Codex_...
InstallLocation : C:\Program Files\WindowsApps\OpenAI.Codex_...

如果没有输出：

确认 Codex 是从 Microsoft Store 安装的正式版本。
确认当前命令运行在安装 Codex 的同一个 Windows 用户下。
不要尝试把脚本强行用于来源不明的便携版或侧载版。

建议使用系统自带的 Windows PowerShell 5.1，即 powershell.exe。部分环境中的 PowerShell 7 无法正常加载 Appx 模块。

2.2 安装 Node.js 22 或更高版本

执行：

node --version

要求输出至少为：

v22.0.0

如果版本低于 22，先升级 Node.js；如果提示找不到 node，安装 Node.js 22 LTS 或更高版本，并重新打开终端。

2.3 建议准备的软件

Git：用于克隆和更新项目。
Windows PowerShell 5.1：用于运行安装、启动、托盘和恢复脚本。
图片编辑工具：用于裁剪自己的 16:9 背景图，可选。

2.4 安装前关闭 Codex

首次安装必须在 Codex 完全关闭时进行，因为安装器需要安全备份和检查 config.toml。

关闭前请：

发送或复制尚未发送的重要输入。
关闭所有 Codex 窗口。
等待数秒，让 Codex 后台进程正常退出。

可使用以下命令检查：

Get-Process -Name ChatGPT, Codex -ErrorAction SilentlyContinue

没有输出时，通常表示 Codex 已退出。

3. 获取 Codex Dream Skin

3.1 方案 A：使用已经安装到技能目录的版本

如果目录存在：

%USERPROFILE%\.agents\skills\codex-dream-skin

在 PowerShell 中设置路径：

$SkinRoot = Join-Path $env:USERPROFILE ".agents\skills\codex-dream-skin\windows"
Test-Path $SkinRoot

输出 True 即可继续。

3.2 方案 B：从 GitHub 克隆

在 PowerShell 中执行：

$InstallRoot = Join-Path $env:LOCALAPPDATA "CodexDreamSkinStudio"
git clone https://github.com/Fei-Away/Codex-Dream-Skin.git $InstallRoot
$SkinRoot = Join-Path $InstallRoot "windows"

如果目录已经存在，并且它是正常的 Git 仓库，可更新：

git -C $InstallRoot pull --ff-only

3.3 方案 C：下载 ZIP

打开项目 GitHub 页面。
选择 Code → Download ZIP。
解压到固定目录，不要放在随后会被清理的临时目录。
找到解压目录中的 windows 文件夹。
将 $SkinRoot 设置为该 windows 文件夹的绝对路径。

示例：

$SkinRoot = "D:\Tools\Codex-Dream-Skin\windows"

检查关键脚本：

Test-Path (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")
Test-Path (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")
Test-Path (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1")

三个命令都应返回 True。

4. 首次安装

4.1 标准安装

确保 Codex 已关闭，然后执行：

$SkinRoot = Join-Path $env:USERPROFILE ".agents\skills\codex-dream-skin\windows"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")

安装器会：

检查 Node.js 版本。
动态查找当前 Microsoft Store 版 Codex。
检查 Codex 是否仍在运行。
在 %LOCALAPPDATA%\CodexDreamSkin 初始化主题仓库。
保存安装前的 Codex 外观配置。
初始化活动主题和内置主题。
创建启动、托盘和恢复快捷方式。
启动托盘控制器。

4.2 不创建快捷方式

如果只想使用命令行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1") -NoShortcuts

4.3 使用自定义端口

默认首选端口为 9335。一般不需要手动指定；默认端口被占用时，启动器会在后续端口中寻找可用端口。

如确实要固定端口，例如 9444：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1") -Port 9444

之后启动、托盘、验证和恢复命令也应使用相同端口。

4.4 安装后首次启动

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")

成功后应看到类似：

Codex Dream Skin is active on verified loopback port 9335.

5. 启动和重新应用主题

5.1 推荐启动方式

主题不是永久写入官方应用。每次完全退出 Codex 后，应通过以下方式之一重新启动：

桌面的 Codex Dream Skin 快捷方式。
开始菜单中的 Codex Dream Skin。
start-dream-skin.ps1 命令。

如果直接点击官方 Codex 图标，Codex 会以普通模式启动，没有 CDP 端口，主题无法注入。

5.2 Codex 已经普通启动时

如果出现：

Codex is open without a verified Dream Skin CDP endpoint.
Close it first or explicitly use -RestartExisting.

有两种解决方法。

安全方式：

保存尚未发送的内容。
手动关闭 Codex。
再运行启动脚本。

明确授权自动重启：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

需要弹窗确认：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -PromptRestart

-RestartExisting 会关闭当前 Codex。执行前确认输入框中没有尚未保存的重要内容。

5.3 主题突然消失

常见原因是：

Codex 被完全关闭后，从官方图标普通启动。
Codex 更新后旧的 Browser ID 已失效。
注入 watcher 已随原 Codex 进程退出。
托盘中选择了“暂停皮肤”。

通常重新执行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

即可恢复。

6. 托盘菜单的使用方法

6.1 启动托盘控制器

安装器通常会自动创建并启动托盘程序。若找不到图标，先展开任务栏右下角的 ^ 隐藏图标区域。

也可以手动启动：

$TrayScript = Join-Path $SkinRoot "scripts\tray-dream-skin.ps1"
Start-Process powershell.exe `
  -ArgumentList @("-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", "`"$TrayScript`"") `
  -WindowStyle Hidden

6.2 托盘菜单功能

右键 Dream Skin 托盘图标后可看到：

状态：运行中/未运行/已暂停：显示当前状态和活动主题名称。
应用或重新应用：启动或重新注入主题；需要重启时会询问。
暂停皮肤：临时隐藏主题，但保留会话和主题数据。
继续显示皮肤：取消暂停。
更换背景图：导入 PNG、JPG、JPEG 或 WebP。
保存当前主题：把活动主题保存到主题库。
已保存主题：列出并切换已保存主题。
打开图片文件夹：打开 Dream Skin 管理的图片目录。
完全恢复 Codex：停止主题、关闭 CDP 并恢复官方模式。
退出托盘：只退出托盘控制器。

6.3 切换主题

右键托盘图标 → 已保存主题 → 选择主题名称

切换通常会热更新，不需要重新启动 Codex。

7. 制作自己的图片主题

7.1 图片要求

支持格式：

.png
.jpg
.jpeg
.webp

安全限制：

文件不能为空。
文件大小不能超过 16 MB。
任意一边不能超过 16384 像素。
总像素不能超过 5000 万像素。

推荐规格：

尺寸：2560 × 1440
比例：16:9
色彩：RGB / sRGB
格式：高质量 JPG 或 PNG

7.2 构图建议

Codex 左侧通常是侧栏，中间和右侧是首页、消息区和输入框。推荐：

人物或主体放在画面右侧约 60%～80% 的位置。
左侧保留低细节、低对比度区域，方便侧栏文字阅读。
画面中央下方不要堆积过多高亮细节，以免干扰输入框。
避免在图片中直接写文字，因为窗口缩放和裁切可能导致文字缺失。
不要把带 Codex 按钮、侧栏、卡片或输入框的效果截图当作背景。
使用纯背景素材，让真实 Codex UI 叠加在背景上。

7.3 导入并保存主题

右键托盘图标。
选择 更换背景图。
选择准备好的图片。
等待背景热更新。
检查首页、任务页、侧栏和输入框可读性。
右键托盘图标，选择 保存当前主题。
输入主题名称。
以后可在 已保存主题 中切换。

导入新图时，Windows 版会将以下项目重置为自动模式：

外观模式：auto
焦点：自动分析
文字安全区：auto
任务页显示模式：auto

图像分析在本地渲染器完成，不会上传图片。

7.4 主题设计检查清单

导入后检查：

左侧导航文字是否清晰。
首页标题是否有足够对比度。
项目选择器是否仍可点击。
输入框边界、文字和光标是否清晰。
普通任务页背景是否比首页安静。
窄窗口下主体是否仍在画面内。
没有横向滚动条。
图片中没有伪造 UI。
所有原生按钮都能正常点击。

8. 高级主题配置：theme.json

8.1 活动主题位置

%LOCALAPPDATA%\CodexDreamSkin\active-theme\theme.json

活动主题的图片也位于同一目录。最安全的操作顺序是：

先通过托盘导入图片。
再编辑自动生成的 theme.json。
保持 JSON 语法正确。
保存后等待 watcher 热更新。

8.2 基础示例

{
  "schemaVersion": 1,
  "id": "my-custom-theme",
  "name": "我的自定义主题",
  "brandSubtitle": "CODEX DREAM SKIN",
  "tagline": "让今天的工作台更有氛围。",
  "projectPrefix": "选择项目 · ",
  "projectLabel": "◉  选择项目",
  "statusText": "DREAM SKIN ONLINE",
  "quote": "MAKE SOMETHING WONDERFUL",
  "image": "art.jpg",
  "appearance": "auto",
  "art": {
    "focusX": 0.75,
    "focusY": 0.42,
    "safeArea": "left",
    "taskMode": "ambient"
  }
}

image 必须指向主题目录内真实存在的图片文件，不能使用目录外路径。

8.3 appearance

可选值：

值	说明
`auto`	优先跟随 Codex 原生计算出的浅色/深色模式，缺失时跟随系统
`light`	明确使用浅色可读层
`dark`	明确使用深色可读层

建议优先使用 auto。图片明暗分析只影响构图和可读层，不应强行反转用户明确选择的 Codex 外观模式。

8.4 focusX 与 focusY

焦点坐标范围为 0～1：

focusX = 0：最左侧。
focusX = 0.5：水平中央。
focusX = 1：最右侧。
focusY = 0：最上方。
focusY = 0.5：垂直中央。
focusY = 1：最下方。

人物位于右侧时，可以从下面的值开始调整：

"focusX": 0.72,
"focusY": 0.45

如果不想手动指定，可以设置为 null，由渲染器自动分析：

"focusX": null,
"focusY": null

8.5 safeArea

文字安全区表示哪个区域更适合放置 Codex UI：

值	适用情况
`auto`	自动分析
`left`	左侧适合放文字，主体通常在右侧
`right`	右侧适合放文字，主体通常在左侧
`center`	中央区域较干净
`none`	不指定安全区

多数“人物在右侧”的桌面主题适合：

"safeArea": "left"

8.6 taskMode

控制普通任务页中的背景表现：

值	说明
`auto`	根据图片宽高比和分析结果自动选择
`ambient`	整窗环境背景，任务页使用更强的安静遮罩
`banner`	在任务页更偏向横幅式表现，适合超宽图
`off`	普通任务页关闭图片，只在适合的页面展示主题

一般 16:9 图片推荐：

"taskMode": "ambient"

8.7 保存高级配置为主题

调整活动主题满意后：

右键托盘图标 → 保存当前主题 → 输入名称

保存后会在 %LOCALAPPDATA%\CodexDreamSkin\themes 创建独立目录，图片和配置会一起复制，不依赖活动主题目录。

9. 验证主题是否真正生效

9.1 自动验证

$Screenshot = Join-Path $env:TEMP "codex-dream-skin-verify.png"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\verify-dream-skin.ps1") `
  -ScreenshotPath $Screenshot

打开截图：

Start-Process $Screenshot

验证结果通常会包含：

shell: true
sidebar: true
composer: true
main: true
installed: true
stylePresent: true
pass: true

首页推荐卡片数量会根据窗口宽度和当前 Codex 版本变化，可能为 2～4 个，也可能在较窄窗口中减少或不显示；不能只用推荐卡数量判断主题失败。

9.2 手动验收

至少检查两个页面。

首页：

壁纸连续覆盖侧栏和主区。
标题、项目选择器和输入框是真实 Codex 控件。
侧栏与输入框具有协调的可读层。
没有伪造的界面截图。

普通任务页：

背景比首页更安静。
消息文字保持高对比度。
输入框不遮挡消息内容。
页面滚动正常。

交互检查：

点击真实项目选择器，确认项目菜单打开。
在输入框中输入文字，确认光标和文字清晰。
打开任务，再返回新任务页面。
确认按钮、侧栏和菜单均可正常点击。

10. 文件、状态和日志位置

10.1 运行数据根目录

%LOCALAPPDATA%\CodexDreamSkin

常见内容：

路径	用途
`active-theme\`	当前活动主题及图片
`themes\`	已保存主题库
`images\`	导入图片归档
`state.json`	当前端口、Browser ID、Codex 包身份、injector PID 等
`injector.log`	正常注入日志
`injector-error.log`	注入器警告和错误
`verify.log`	最近一次启动验证结果
`paused`	存在时表示主题暂停
`config.before-dream-skin.toml`	安装前配置备份

10.2 Codex 用户配置

%USERPROFILE%\.codex\config.toml

不要使用会改变编码的编辑器保存该文件。脚本要求严格 UTF-8，并以同目录原子替换方式写回。

10.3 不要手动删除 state.json 解决问题

优先使用：

启动脚本重新应用。
验证脚本诊断。
恢复脚本清理。

不要在不理解进程状态的情况下手动结束未知 Node 进程或删除状态文件。

11. 更新 Codex 或 Dream Skin

11.1 Codex 更新后

脚本每次启动都会动态查询当前 OpenAI.Codex 商店包，因此不依赖写死的版本目录。

Codex 更新后建议：

关闭所有 Codex 窗口。
重新运行安装脚本。
重新运行启动脚本。
执行验证脚本。

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")

11.2 Git 仓库版本更新

git -C $InstallRoot status --short
git -C $InstallRoot pull --ff-only

如果 status --short 显示本地修改，先确认这些修改是否需要保留，不要直接重置。

更新后运行测试：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "tests\run-tests.ps1")

node --check (Join-Path $SkinRoot "scripts\injector.mjs")
node --check (Join-Path $SkinRoot "assets\renderer-inject.js")

最后关闭 Codex，重新安装并启动。

12. 恢复官方外观与卸载

12.1 只结束主题会话并正常重开 Codex

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") -PromptRestart

它会停止主题 injector、关闭 CDP 会话，并以普通模式重新打开官方 Codex。

12.2 同时恢复安装前的外观键

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -PromptRestart

12.3 强制授权关闭当前 Codex

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -ForceRestart

执行前确认没有尚未发送的输入。

12.4 恢复安装前 config.toml 的完整字节备份

仅在配置确实损坏、选择性恢复无法解决时使用：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RecoverConfigBackup -PromptRestart

该操作会：

保存当前配置到带时间戳的恢复前备份。
恢复安装前的完整配置字节。
归档本次安装备份。

-RecoverConfigBackup 与 -RestoreBaseTheme 不能同时使用。

12.5 删除快捷方式

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -Uninstall -PromptRestart

-Uninstall 删除 Dream Skin 创建的桌面和开始菜单快捷方式，不会自动删除你的主题图片仓库或项目源代码。

12.6 恢复后不重新打开 Codex

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -ForceRestart -NoRelaunch

13. 常见问题与故障排除

13.1 `Codex is open without a verified Dream Skin CDP endpoint`

原因：Codex 已通过官方图标以普通模式启动，没有可信的 Dream Skin CDP 会话。

解决：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

或手动关闭 Codex 后重新运行启动脚本。

13.2 找不到托盘图标

点击任务栏右下角 ^。
检查隐藏图标。
手动启动托盘脚本：

$TrayScript = Join-Path $SkinRoot "scripts\tray-dream-skin.ps1"
Start-Process powershell.exe `
  -ArgumentList @("-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", "`"$TrayScript`"") `
  -WindowStyle Hidden

如果启动后立刻退出，检查脚本版本和 %LOCALAPPDATA%\CodexDreamSkin 中的日志。

13.3 托盘右键提示 `Items` 为空集合

旧版本托盘脚本可能没有允许首次打开时的空 WinForms 菜单集合，错误类似：

无法将参数绑定到参数“Items”，因为该参数为空集合。

首选解决方案：更新到包含修复的新版本。

如果必须修复旧的本地副本，在 scripts\tray-dream-skin.ps1 中找到：

[Parameter(Mandatory = $true)][System.Windows.Forms.ToolStripItemCollection]$Items

改为：

[Parameter(Mandatory = $true)][AllowEmptyCollection()][System.Windows.Forms.ToolStripItemCollection]$Items

保存后关闭旧托盘 PowerShell 进程，再重新启动托盘脚本。

13.4 `Another Codex Dream Skin ... operation is already running`

安装、启动、恢复和验证通过同一用户互斥锁串行执行。该错误表示另一个操作尚未完成。

处理方法：

等待正在进行的启动或恢复完成。
不要连续双击多个快捷方式。
检查是否有安装脚本正在等待 Codex 关闭。
不要通过删除锁文件解决；该锁是 Windows 命名互斥量，并不是普通文件。

13.5 找不到 Node.js 或版本过低

node --version
Get-Command node.exe

要求 Node.js 22 或更高版本。升级后重新打开终端再启动 Dream Skin。

13.6 找不到官方 Codex Store 包

执行：

powershell.exe -NoProfile -Command "Get-AppxPackage -Name OpenAI.Codex | Format-List Name, Version, PackageFullName, InstallLocation"

如果仍无输出，重新从 Microsoft Store 安装官方 Codex。不要修改脚本来绕过 Store 包身份和签名校验。

13.7 端口 9335 被占用

如果没有显式传 -Port，启动器会尝试寻找后续空闲端口。

如果需要固定其他端口，应在所有入口统一使用，例如：

$Port = 9444
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -Port $Port -RestartExisting

不要把端口绑定到 0.0.0.0 或局域网地址。

13.8 配置提示不支持的 TOML 结构

为了避免破坏配置，安装器会拒绝自动修改以下复杂结构：

[desktop.*] 嵌套子表。
desktop.key = ... dotted key。
重复的 [desktop]。
重复的目标外观键。
多行字符串或多行数组。
转义后等价于目标键的复杂写法。

不要绕过错误强制写入。先备份：

Copy-Item "$env:USERPROFILE\.codex\config.toml" `
  "$env:USERPROFILE\.codex\config.manual-backup.toml"

然后将需要的外观设置整理为普通单一表，例如：

[desktop]
appearanceTheme = "system"

保留所有与 Dream Skin 无关的配置。若不熟悉 TOML，停止操作并让熟悉配置格式的人协助检查。

13.9 图片导入被拒绝

检查：

扩展名是否为 PNG、JPG、JPEG 或 WebP。
文件是否为空。
是否超过 16 MB。
任意一边是否超过 16384px。
总像素是否超过 50MP。
文件是否损坏或扩展名与真实格式不符。
文件或主题目录是否位于符号链接、junction 等 reparse point 中。

13.10 主题切换了但画面没有立即变化

确认托盘状态不是“已暂停”。
等待 watcher 检测主题文件变化。
切换一次页面或新建任务。
选择“应用或重新应用”。
执行验证脚本查看 verify.log。

13.11 injector 日志显示 Browser identity closed

类似：

original CDP browser identity closed; watcher is stopping instead of reconnecting

这通常表示原 Codex 窗口已经关闭。watcher 拒绝连接到端口上后来出现的其他进程，这是正常的安全行为。通过 Dream Skin 启动脚本重新打开 Codex 即可。

13.12 Codex 更新后出现新旧版本同时运行

关闭所有 Codex 窗口，等待后台进程退出，然后重新运行安装和启动脚本。脚本不会在无法验证旧路径身份时强行结束未知进程。

13.13 验证失败后 Codex 自动恢复普通模式

这是启动回滚机制。启动器在验证失败时会尽量：

停止新 injector。
清理失败的状态记录。
关闭本次调试会话。
以无调试端口的普通模式重开 Codex。

检查 injector-error.log 和 verify.log 后再重试。

14. 推荐的日常使用流程

首次安装

检查 Store 版 Codex。
检查 Node.js 22+。
关闭 Codex。
运行 install-dream-skin.ps1。
运行 start-dream-skin.ps1。
运行验证脚本并检查截图。

每天启动

使用 Codex Dream Skin 快捷方式。
不要从官方图标普通启动；若已普通启动，使用 -RestartExisting。

制作新主题

准备 2560×1440 的纯背景图。
托盘选择“更换背景图”。
检查首页和任务页。
必要时调整 theme.json 的焦点、安全区和任务模式。
托盘选择“保存当前主题”。

暂时不用主题

短期隐藏：托盘选择“暂停皮肤”。
完全关闭调试会话：运行 Restore。

15. 命令速查表

先定义路径：

$SkinRoot = Join-Path $env:USERPROFILE ".agents\skills\codex-dream-skin\windows"

安装：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\install-dream-skin.ps1")

启动：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1")

重启已打开的普通 Codex 并应用主题：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\start-dream-skin.ps1") -RestartExisting

启动托盘：

$TrayScript = Join-Path $SkinRoot "scripts\tray-dream-skin.ps1"
Start-Process powershell.exe `
  -ArgumentList @("-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", "`"$TrayScript`"") `
  -WindowStyle Hidden

验证并截图：

$Screenshot = Join-Path $env:TEMP "codex-dream-skin-verify.png"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\verify-dream-skin.ps1") `
  -ScreenshotPath $Screenshot

恢复官方模式：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") -PromptRestart

恢复安装前外观：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -PromptRestart

完整恢复并删除快捷方式：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "scripts\restore-dream-skin.ps1") `
  -RestoreBaseTheme -Uninstall -PromptRestart

运行自动测试：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkinRoot "tests\run-tests.ps1")

node --check (Join-Path $SkinRoot "scripts\injector.mjs")
node --check (Join-Path $SkinRoot "assets\renderer-inject.js")

结语

Codex Dream Skin 的核心原则是：主题只存在于可恢复的本机渲染会话中，不修改官方安装包。日常使用时记住三点即可：

首次安装和 Codex 更新后，关闭 Codex 再运行安装脚本。
日常通过 Dream Skin 快捷方式或启动脚本打开 Codex。
不用主题时执行 Restore，安全关闭 CDP 会话并恢复官方模式。

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

2026年7月更新：ChatGPT、Codex、Pro、Plus 背后的 AI Observability（GPT-5.6 工程化技术分享）

过去的软件工程：关注代码执行。未来的 AI 工程：关注智能决策。当 ChatGPT、Codex、Pro、Plus 进入真实生产环境，最大的挑战不是：“AI 能不能完成任务。为什么这样完成？依据是什么？过程是否合理？结果是否可信？失败如何定位？AI Observability 会成为 LLM-Native 软件工程的重要基础设施。未来优秀开发者，不只是会调用 AI。还需要知道：如何观察 AI。如何理

AI编程社区

2026年7月18日更新：ChatGPT Plus / Pro 与 Codex——AI Agent 的上下文工程：为什么未来程序员竞争的是“信息组织能力”（GPT-5.6 最新技术分享）

ChatGPT、Codex 和 AI Agent 正在改变软件开发方式。但真正重要的变化，不只是：AI 可以写代码。而是：AI 开始参与理解复杂系统。如何写代码如何组织信息如何建立上下文如何让 AI 理解系统如何控制 AI 修改边界代码生成只是表层。上下文工程才是 AI 编程时代真正的基础设施。模型决定 AI 的智力上限。上下文决定 AI 能发挥多少能力。未来优秀开发者，不一定是写代码最快的人。而

AI编程社区

2026年7月更新：ChatGPT Pro、Plus 与 Codex 如何重构软件供应链安全体系（GPT-5.6与AI Agent技术分享）

ChatGPT Plus、ChatGPT Pro 与 Codex 正在改变软件生产方式。人写代码工具检查代码AI 参与生成代码系统验证 AI 行为人类控制关键决策软件供应链安全的核心，也会发生变化。代码有没有漏洞代码为什么产生？谁允许它产生？它经过什么验证？它是否符合组织规则？×××未来真正成熟的 AI 开发环境，不是让 Codex 拥有无限能力。而是在严格边界内，让 ChatGPT Pro、Pl

AI编程社区

所有评论(0)

查看更多评论

xintgong

@xintgong

已为社区贡献3条内容

给 Codex 换上全屏背景 | Windows 完整安装、换肤与主题制作教程

xintgong

Codex Dream Skin：Windows 完整安装、换肤与主题制作教程

效果预览

八种概念风格

1. 粉系定制

2. 财神打工版

3. 红白科幻

4. 清透定制

5. 灵感小宇宙

6. 紫夜限定

7. 青蓝虚拟歌姬

8. 舞台黑金

目录

1. 项目原理与安全边界

1.1 重要安全说明

1.2 不会被修改的内容

2. 安装前准备

2.1 确认使用 Microsoft Store 版 Codex

2.2 安装 Node.js 22 或更高版本

2.3 建议准备的软件

2.4 安装前关闭 Codex

3. 获取 Codex Dream Skin

3.1 方案 A：使用已经安装到技能目录的版本

3.2 方案 B：从 GitHub 克隆

3.3 方案 C：下载 ZIP

4. 首次安装

4.1 标准安装

4.2 不创建快捷方式

4.3 使用自定义端口

4.4 安装后首次启动

5. 启动和重新应用主题

5.1 推荐启动方式

5.2 Codex 已经普通启动时

5.3 主题突然消失

6. 托盘菜单的使用方法

6.1 启动托盘控制器

6.2 托盘菜单功能

6.3 切换主题

7. 制作自己的图片主题

7.1 图片要求

7.2 构图建议

7.3 导入并保存主题

7.4 主题设计检查清单

8. 高级主题配置：theme.json

8.1 活动主题位置

8.2 基础示例

8.3 appearance

8.4 focusX 与 focusY

8.5 safeArea

8.6 taskMode

8.7 保存高级配置为主题

9. 验证主题是否真正生效

9.1 自动验证

9.2 手动验收

10. 文件、状态和日志位置

10.1 运行数据根目录

10.2 Codex 用户配置

10.3 不要手动删除 state.json 解决问题

11. 更新 Codex 或 Dream Skin

11.1 Codex 更新后

11.2 Git 仓库版本更新

12. 恢复官方外观与卸载

12.1 只结束主题会话并正常重开 Codex

12.2 同时恢复安装前的外观键

12.3 强制授权关闭当前 Codex

12.4 恢复安装前 config.toml 的完整字节备份

12.5 删除快捷方式

12.6 恢复后不重新打开 Codex

13. 常见问题与故障排除

13.1 Codex is open without a verified Dream Skin CDP endpoint

13.2 找不到托盘图标

13.3 托盘右键提示 Items 为空集合

13.4 Another Codex Dream Skin ... operation is already running

13.5 找不到 Node.js 或版本过低

13.6 找不到官方 Codex Store 包

13.7 端口 9335 被占用

13.8 配置提示不支持的 TOML 结构

13.9 图片导入被拒绝

13.10 主题切换了但画面没有立即变化

13.1 `Codex is open without a verified Dream Skin CDP endpoint`

13.3 托盘右键提示 `Items` 为空集合

13.4 `Another Codex Dream Skin ... operation is already running`