Codex 换肤教程

核心三步

1. 1

   第一步：安装换肤引擎（macOS）

   双击仓库 macos 目录里的 Install Codex Dream Skin.command（或终端运行下面的脚本）。引擎会部署到 ~/.codex/codex-dream-skin-studio/，并在桌面生成 Start / Customize / Verify / Restore 四个双击启动器。注意：macOS 不需要单独装 Node.js——它直接复用 Codex.app 里自带的、带签名的 Node 运行时，也不修改 Codex 官方安装包与代码签名。

   ./scripts/install-dream-skin-macos.sh

2. 2

   第二步：选一张图 + 配色，生成主题

   双击桌面的 Codex Dream Skin - Customize.command，在弹出的 Finder 里选一张横向、宽 2000px 以上的背景图（初音就用你喜欢的初音壁纸），再填名字和配色（初音葱绿 #39C5BB）。脚本会把图片转成 ≤16MB 的 JPEG、写出 theme.json 并自动套用。支持 PNG/JPEG/HEIC/TIFF/WebP，建议左侧留白方便原生标题显示。

   ~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh --image "/path/to/miku.png" --name "Hatsune Miku" --accent "#39C5BB" --secondary "#FF61C7" --highlight "#00B4DC"

3. 3

   第三步：应用、验证、一键还原

   生成后会自动应用。之后随时双击 Start Codex Dream Skin.command 重新套用；Verify 可截图验证效果；不满意就双击 Restore Codex Dream Skin.command 一键回到 Codex 默认界面，不影响后续官方更新。换肤通过本机 127.0.0.1:9341 的 CDP 注入实现，纯运行时叠层。

   ~/.codex/codex-dream-skin-studio/scripts/restore-dream-skin-macos.sh --restore-base-theme --restart-codex

主题包格式与安装

一套主题本质上就是一个文件夹：一份 theme.json（配色 + 文字配置）加一张背景图。开源项目本身没有主题商店、也没有「导入主题」命令，所以「下载一个主题」就是拿到这样一个文件夹，丢进主题库再用一条脚本切换。下面以一套名为 miku 的主题为例。

~/Library/Application Support/CodexDreamSkinStudio/
└── themes/
    └── miku/
        ├── theme.json   # 配色 + 文字配置
        └── miku.png      # theme.json 里 "image" 字段指向的文件名

把这个 miku 文件夹放进主题库后，运行下面这条命令即可切换并应用：

~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh --id miku

注意：theme.json 里的 "image" 字段必须与同目录的图片文件名完全一致；图片格式 png/jpg/jpeg/webp、≤16MB。Codex 已开着会热切换；没开就再双击 Start Codex Dream Skin.command。

Windows 上怎么用？

Windows 版和 macOS 不一样：它目前只内置一套固定的粉紫 Dream 皮肤（默认端口 9335），暂不支持选自己的图片或配色自定义——自定义主题是 macOS 专属。下面是 Windows 上安装、应用与还原的真实 PowerShell 命令。

1. 1

   1. 先装 Node.js 22+

   和 macOS 不同，Windows 不能复用 Codex 内置的 Node，必须先安装 Node.js 22 或更新版本（自带 WebSocket 客户端需要）。

2. 2

   2. 安装并应用固定皮肤

   在仓库根目录用 PowerShell 运行安装脚本，它会装好固定的 Dream 皮肤、关闭并重启 Codex，并在桌面和开始菜单创建快捷方式。

   powershell -File windows/scripts/install-dream-skin.ps1

3. 3

   3. 启动 / 一键还原

   之后用桌面快捷方式 'Codex Dream Skin.lnk' 或 start 脚本启动；想还原默认界面就跑 restore 脚本（支持 -RestoreBaseTheme / -RecoverConfigBackup / -Uninstall 等参数）。

   powershell -File windows/scripts/restore-dream-skin.ps1 -RestoreBaseTheme

如何一键还原

运行项目自带的 Restore 脚本即可清除注入、回到 Codex 默认界面，不影响后续正常更新。

常见故障排查