Codex Dream Skin for Windows

July 23, 2026 · View on GitHub

中文 · English

Codex Dream Skin 通过本机回环 CDP 给官方 Codex Windows 桌面应用加载外部主题。它保留原生侧栏、项目选择、任务内容和输入框，不修改 WindowsApps、app.asar 或应用签名。

运行要求

  • 从 Microsoft Store 安装且已注册到当前用户的官方 OpenAI.Codex 应用。
  • Node.js 22 或更高版本，node.exe 可从 PATH 找到。
  • Windows PowerShell 5.1 或更高版本。

安装脚本需要在 Codex 完全退出后运行。普通使用不需要管理员权限，也不需要接管 WindowsApps 目录。

本工具只检查和使用已经存在的受支持环境；不会安装、下载、登录或配置 Codex，也不会修改 Node.js、PATH 或 PowerShell 执行策略。

首次预检

在安装前，先从仓库的 windows 目录运行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\doctor-dream-skin.ps1

预检只读取本机状态，检查官方 Codex 包、Node.js、配置文件、端口、执行策略和已有 Dream Skin 状态。看到 PASS 后可继续安装；ACTION REQUIRED 会说明需要处理的本机条件；UNSUPPORTED 表示工具无法安全支持当前环境。它不会关闭 Codex、创建文件、修改配置或变更执行策略。

若提示配置文件不存在或无法安全读取，请先完成已有 Codex 的正常初始化后再运行预检；本工具不会创建或猜测 %USERPROFILE%\.codex\config.toml。

维护者测试

在 windows 目录运行以下命令。它覆盖运行时安装、config.toml 恢复、进程/CDP 边界、公文结构化渲染、流式落款状态、圈阅识别和早期注入。

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\run-tests.ps1

安装

在 PowerShell 中进入仓库的 windows 目录，然后运行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-dream-skin.ps1

安装器会校验官方 Codex Store 包和 Node.js，保存可恢复的外观配置，并初始化本地主题仓库。默认还会创建这些快捷方式：

  • Codex Dream Skin：启动或重新应用皮肤。
  • Codex Dream Skin - Tray：打开系统托盘主题控制。
  • Codex Dream Skin - Restore：恢复官方外观并关闭已保存的 CDP 会话。

安装器会在写入配置、复制运行时或创建快捷方式之前再次运行关键预检。预检未通过时不会修改文件或启动托盘。

安装命令中的 Bypass 只作用于这一次由用户明确发起的安装进程。安装器会先校验运行时副本的 SHA-256，再仅对 %LOCALAPPDATA%\CodexDreamSkin\engine 中受管的 PowerShell 副本清除下载区标记。日常快捷方式使用 RemoteSigned，不会绕过系统或企业组策略。

如需使用自定义端口，可以在安装时传入 -Port。端口范围必须是 1024 到 65535。

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-dream-skin.ps1 -Port 9444

更新

先退出 Dream Skin 托盘并关闭 Codex，再更新仓库（git pull，或重新下载最新源码），然后重新运行上面的安装命令。安装器会原子替换受管运行时并重建快捷方式；当前主题、已保存主题和导入图片不会被删除。

不要只复制 assets、renderer-inject.js 或单个预设到已安装目录。注入器和渲染脚本必须来自同一次安装；混用版本可能导致启动验证失败，例如日志同时出现 expectedVersion 与实际版本不一致，或 __DREAM_PROSE_GUIDE__ is not defined。遇到这类错误时，退出托盘和 Codex 后，重新运行安装命令，再从新建的 Codex Dream Skin 快捷方式启动。

从浏览器下载 ZIP 后，Windows 可能给源码中的 .ps1 添加下载来源标记。若手动以 RemoteSigned 执行安装器并收到“未签名”错误，请使用 README 中的用户明确安装命令（其中的 Bypass 仅作用于该次安装），不要修改全局执行策略，也不要混用旧的受管运行时。

启动与验证

推荐从 Codex Dream Skin 快捷方式启动。它发现 Codex 已经运行时会先询问是否重启。

命令行启动：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-dream-skin.ps1 -PromptRestart

启动后运行验证脚本：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-dream-skin.ps1 `
  -ScreenshotPath "$env:TEMP\codex-dream-skin.png"

验证脚本会自动确认：

  • CDP 端点只绑定本机回环地址，并且属于当前官方 Codex 包。
  • 当前渲染页已经加载预期版本的皮肤。
  • 原生侧栏和输入框仍然存在。
  • 皮肤装饰层不会拦截鼠标事件。
  • 当前为首页时，首页主题结构已经正确加载。

随后用生成的截图检查横向溢出和文字对比度，再分别在首页与普通任务页手动检查项目菜单和输入框交互。完整视觉检查项见 references/qa-inventory.md。

若启动或验证失败，先重新运行 doctor-dream-skin.ps1。它不会替代启动或验证，也不会打开调试会话。

更换和保存主题

打开 Codex Dream Skin - Tray 后可以：

  • 更换 PNG、JPEG 或 WebP 背景图。
  • 保存当前主题并从「已保存主题」切换。
  • 暂停或继续显示皮肤。
  • 重新应用主题，或完整恢复 Codex。

导入图片必须是纯背景，不要使用包含窗口、侧栏、输入框、文字或按钮的效果截图。图片上限为 16 MB；宽或高不能超过 16384 像素，总像素不能超过 5000 万。

恢复与卸载快捷方式

恢复官方外观；如果 Codex 正在运行，确认后关闭并重新打开：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore-dream-skin.ps1 `
  -RestoreBaseTheme -PromptRestart

如需同时删除 Dream Skin 创建的快捷方式，再增加 -Uninstall：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore-dream-skin.ps1 `
  -RestoreBaseTheme -PromptRestart -Uninstall

-RecoverConfigBackup 用于明确恢复安装前的完整 config.toml 备份。它会先保存当前配置，只应在配置损坏且普通的 -RestoreBaseTheme 无法解决时使用。

文件与日志位置

用途路径
Dream Skin 状态根目录%LOCALAPPDATA%\CodexDreamSkin
当前主题%LOCALAPPDATA%\CodexDreamSkin\active-theme
已保存主题%LOCALAPPDATA%\CodexDreamSkin\themes
导入图片归档%LOCALAPPDATA%\CodexDreamSkin\images
会话状态%LOCALAPPDATA%\CodexDreamSkin\state.json
注入器日志%LOCALAPPDATA%\CodexDreamSkin\injector.log
注入器错误日志%LOCALAPPDATA%\CodexDreamSkin\injector-error.log
验证日志%LOCALAPPDATA%\CodexDreamSkin\verify.log
Codex 配置%USERPROFILE%\.codex\config.toml

更完整的平台路径说明见 ../docs/platforms.md。

常见问题

找不到 Node.js

运行 node --version，确认版本为 22 或更高，并重新打开 PowerShell 让新的 PATH 生效。

也可重新运行 doctor-dream-skin.ps1，查看具体检测结果。

找不到官方 Codex 包

运行：

Get-AppxPackage -Name OpenAI.Codex

脚本只接受已注册的官方 Store 包，不会从任意可执行文件路径启动 Codex。

本工具不提供 Codex 的安装或配置流程。

配置文件不存在或无法读取

运行 doctor-dream-skin.ps1 查看原因。若它报告 %USERPROFILE%\.codex\config.toml 不存在，请先完成已有 Codex 的正常初始化后再重试。若报告 UTF-8 或 TOML 结构不受支持，预检不会修改该文件；请保留原文件并按提示处理后再运行安装器。

日常快捷方式被执行策略阻止

预检会报告当前 PowerShell 执行策略。安装命令中的 Bypass 仅用于该次用户发起的安装，快捷方式仍遵守 RemoteSigned 和任何企业策略。本工具不会建议或执行绕过策略的操作。

安装器要求关闭 Codex

关闭所有 Codex 窗口后再运行安装器。安装期间必须保持配置和应用状态稳定。

杀毒软件报告旧版托盘快捷方式

旧版托盘快捷方式同时使用隐藏 PowerShell 和 ExecutionPolicy Bypass，可能触发基于行为特征的 LNK 告警。不要直接加入白名单；更新源码并重新运行安装器，让快捷方式改用 RemoteSigned。如果新版仍然报警，请保留隔离状态，并在 Issue 中附上杀毒软件名称、版本、告警名称和快捷方式属性，不要上传密钥或私人数据。

端口被占用

没有显式指定 -Port 时，启动脚本会从默认端口 9335 开始寻找空闲端口。显式端口被其他进程占用时，改用另一个端口，不要关闭身份不明的监听进程。

验证找不到 CDP 端点

通过 Codex Dream Skin 快捷方式启动 Codex，再运行验证脚本。普通 Codex 启动方式不会打开 Dream Skin 所需的调试会话。

Codex 更新后皮肤失效

重新运行安装器和启动快捷方式。脚本会重新发现当前注册的 Store 包，不依赖旧版本的可执行文件路径。

文档落款回退为旧默认值

新版默认落款为 山姆·奥特曼。安装器会迁移旧版 Codex小助手 预设，同时保留任何其他自定义署名；若仍显示旧值，请退出托盘和 Codex 后重新运行安装器。

提交问题时请从仓库的 Issue 提交页 选择 Bug 模板，附上系统版本、Codex 来源、复现步骤和相关日志片段。请删除密钥、auth.json、中转 token 和私人对话内容。

安全边界

  • CDP 只绑定 127.0.0.1。皮肤运行期间不要运行来路不明的本机程序。
  • 不修改官方 Codex 安装目录、WindowsApps、app.asar 或签名。
  • 不写入 API Key、Base URL 或模型供应商配置。
  • 恢复脚本只会控制经过包身份、进程路径和会话状态校验的 Codex 进程。

维护者和代理使用的实现约束见 SKILL.md，运行时排错细节见 references/runtime-notes.md。