Codex-Dream-Skin Documentation

File: README.md Copy Chapter

Codex Dream Skin

🤝 独家赞助 Copy Chapter

| | 感谢 Passion8 独家赞助本项目！Passion8 是一家面向开发者的 AI API 中转服务商，为个人开发者与团队提供稳定、低成本的主流大模型接入。
满血 AI · 触手可及：OpenAI、Claude 全系列原版模型，无降智、无套壳；使用前沿 AI 模型仅需官方价格的一小部分，充值 1:1，1$ = 1¥。保留原有官方 SDK，只把 Base URL 换成 Passion8，Claude Code、Codex、Grok 以及任意 OpenAI 兼容客户端都能直接跑——一行配置，代码不用改。
全球节点加速：Cloudflare 全球边缘 + 多线路 BBR 加速，低延迟、高可用、稳定如一；7×24 稳定中转，99.9% SLA，首 Token 目标 1 秒内。
安全可靠：独立 API Key、密钥加密存储、全链路 HTTPS，隐私优先。

Passion8 为本项目用户准备了专属福利：通过此链接注册，首次充值自动赠送 10% 额度，无需申请，30 分钟内到账。有问题联系 [email protected]。 |
| --- | --- |

_{换肤与 API 配置互相独立，本项目不会自动改写你的模型供应商设置。}

直接安装 Copy Chapter

普通用户只需先安装并退出一次官方 Codex / ChatGPT，然后从
GitHub Releases 下载：

• macOS：打开 CodexDreamSkin-vX.Y.Z.dmg，把 App 拖进 Applications。
• Windows：双击 CodexDreamSkin-Setup-vX.Y.Z.exe，按安装向导完成。

不需要 clone 源码、安装 Node.js 或手动运行 .sh / .ps1。首次未签名放行、更新和卸载步骤见
macOS 安装说明 / Windows 安装说明。

主题库与社区 Copy Chapter

• 主题库 Gallery：浏览社区已审核的主题，支持最新 / 热门排序和创作者榜单。
  每套主题都能先在网页里的桌面模拟器中试穿，再决定装不装。

• 在线 Studio：在浏览器里换背景图、调主题色、写 Safe CSS，导出 .zip 主题包，
  也可以直接投稿到主题库（需登录，经人工审核后公开）。

macOS 菜单栏和 Windows 托盘都有「主题库 Gallery」和「在线 Studio」入口，可以直接打开。

一键换肤 Copy Section

在 DreamSkin.cc 上看到喜欢的主题，点「一键换肤」就能让本机客户端直接装上，不用先下载再手动导入。
需要 v1.5.0 或更新的客户端（建议 v1.5.5 及以上）。

流程与安全边界：

• 网页通过 dreamskin://apply?version=ver_... 唤起本机 App。链接只能携带一个主题版本 ID，不能携带
  任意 URL、文件路径或命令，也不存在静默应用参数。
• App 只向固定的官方 API 取包，并拒绝重定向。
• 换肤前弹出原生确认框，并核对该版本的审核状态、一键兼容标记、版本号、包大小、实际下载字节数和 SHA-256。
• 通过后复用与手动导入完全相同的 ZIP、manifest、图片与 Safe CSS 校验。
• 只有真实渲染进程确认新主题已生效才算成功。启动或渲染失败会自动尝试恢复换肤前的主题，恢复结果
  同样要经过可见性验证；无法确认时会明确报告状态未确认，而不是假装已恢复。

只有完整满足当前主题包契约（背景图 + theme.json + 非空 theme.css + 声明 safe-css 能力）的主题
才会显示一键换肤按钮；不满足的走下面的手动导入。

实测精选预设 Copy Chapter

Gothic Void Crusade / 哥特虚空远征 Copy Section

特别感谢 @seansong-ideogram 为社区设计并贡献这套精美、极具氛围感的原创哥特科幻作品。 它是当前实测精选的第一套预设，也是 macOS 全新安装时默认启用的主题。

安装后可直接从 macOS 菜单栏的「已保存主题」切换。

桥本有菜 / Arina Hashimoto Copy Section

下面这套「桥本有菜 / Arina Hashimoto」已经在真实 Codex 首页分别验证浅色和暗色外观。用户提供的源 PNG 为 1672 × 941，主题包在保持源图近 16:9 构图的前提下派生导出 2560 × 1440 JPEG，并不代表增加了源图细节。截图中的侧栏、卡片、项目选择和输入框都是 Codex 原生控件。

这组人物素材留在源码仓库用于参考与权利核验，不进入公开 DMG / Setup.exe；公开安装包只预置已确认
可分发的 Gothic Void Crusade。普通用户仍可从菜单里的「更换背景图」导入自己有权使用的纯背景，
保存后继续一键切换。

可下载的用户源图是 docs/images/presets/arina-hashimoto-source.png（1672 × 941）；源码参考预设使用 macos/presets/preset-arina-hashimoto/background.jpg（规范化派生 2560 × 1440）。上面两个效果图包含真实 UI，只作预览，绝不能当背景导入。背景为用户提供的 AI 生成示例，不代表 OpenAI/Codex 官方视觉或背书；未确认人物与素材权利前不得把它打进公开安装包。

它能做什么 Copy Chapter

• 真·可交互：侧栏、建议卡、项目选择、输入框都是原生控件，不是整窗假截图贴上去
• 真背景层：一张 16:9 纯壁纸连续铺满整窗，首页突出氛围，任务页自动降低干扰
• 可换图：换一张喜欢的纯背景，自适应焦点、安全区和配色后变成你的主题
• 可存主题：macOS 菜单栏与 Windows 系统托盘都能保存/切换本地主题
• 一键换肤：在 DreamSkin.cc 上点一下，客户端核对来源与校验和后直接装上
• 可导入主题包：两端都可直接选择普通 .zip，安全校验后加入本地主题库
• 可恢复：一键还原官方外观
• 相对安全：本机回环 CDP 注入，不改官方二进制与签名

快速开始 Copy Chapter

普通用户：下载安装包 Copy Section

不需要 clone 仓库，也不需要安装 Node.js 或运行 .sh / .ps1。从
GitHub Releases 下载对应平台的最新安装包，
按平台文档完成一次图形界面安装：

安装后从菜单栏（macOS）或系统托盘（Windows）使用。更新时下载新安装包覆盖安装，主题和图片会保留；
未签名的新下载文件在个别系统上仍可能再次出现一次安全提示，文档列出了放行方法。

导入下载的主题 Copy Section

从 DreamSkin.cc 装主题优先用一键换肤。下面是手动导入 .zip 的兜底路径，也适用于任何
其他来源的主题包。

在 macOS 菜单栏选择“导入主题 ZIP…”，或在 Windows 托盘选择同名菜单。只支持普通 .zip，
不支持 .dreamskin 后缀，也不要仅改后缀伪装。正式 Studio 主题包包含 manifest.json、
theme.json、非空 theme.css 和恰好一张 background.webp|jpg|png；还可包含 LICENSE.txt 和预留的
manifest.sig。这些文件可以位于 ZIP 根目录或唯一一层主题目录。导入器会核对适用平台、最低客户端
版本，以及清单中每个负载文件的大小和 SHA-256。theme.css 必须通过本机 Safe CSS 校验，导入后只会
作用于 12 个注册部件；每次切换/应用仍会重新校验。manifest.sig 当前不参与签名验证。

本地简化 ZIP 也必须恰好包含非空 theme.json、非空 theme.css 和其引用图片；该格式没有正式清单的
完整性与兼容性声明，只应从可信来源使用。压缩包最大 32 MiB、最多 32 个条目、解压后最多 64 MiB。
导入成功后主题只会加入“已保存的主题”，不会自动替换当前主题；相同内容不会重复写入。同 ID 的新版本会在
确认旧目录身份后原地更新，并仅清理语义指纹完全一致、已确认属于同一主题的旧版 -2/-3 重复目录；无法
确认身份时会拒绝覆盖，也不会根据名称猜测并删除其他主题。

也可以先手动解压，再把包含 theme.json、theme.css 和背景图的完整主题目录移动到本机主题库：

• macOS：~/Library/Application Support/CodexDreamSkinStudio/themes/
• Windows：%LOCALAPPDATA%\CodexDreamSkin\themes\

菜单里有“打开主题文件夹”快捷入口。移动后重新打开菜单/托盘即可；不要再套一层目录，也不要放链接、
嵌套压缩包或缺少三件套的文件夹。手动目录不会经过 ZIP 导入器的归档校验，请只使用可信内容。升级前
已经保存且没有 CSS 的 legacy 主题仍可切换，但不会注入额外 CSS。

开发者：从源码运行 Copy Section

仓库内按平台放了现成脚本（实现细节不同，效果都是「主题化 Codex」）：

更细的说明：

• Mac：macos/README.md
• Windows：windows/README.md
• 路径对照：docs/platforms.md
• 可直接复制的参考生图模板：docs/reference-background-prompt-guide.md
• 八种概念方向详细提示词：docs/background-generation-prompts.md
• 项目记录：docs/PROJECT.md

反馈与贡献 Copy Chapter

• Issue： 请用 Issue 模板（Bug / 功能）；已关闭空白 Issue。提交前建议先跑 Verify / Restore 自检。
• PR： 请按 PR 模板 写清改动，并勾选对应自测（如 macos/tests/run-tests.sh、verify / restore）。

安全边界 Copy Chapter

• CDP 只绑 127.0.0.1，但没有身份认证；同一台电脑上的其他进程仍可能连接并读取或控制 renderer
• 暂停主题或只停止 injector 不会关闭已启动 Codex 的调试端口；使用完整 Restore/重启，或退出全部 Codex 后从官方普通入口重新打开，风险窗口才结束
• 不修改官方安装目录与代码签名
• 不会自动改写 API Key / Base URL；中转与换肤分开
• 完整威胁模型与操作建议见 SECURITY.md

许可与声明 Copy Chapter

• 见 macos/LICENSE（MIT）与 macos/NOTICE.md
• 非 OpenAI 官方产品；Codex 及相关权利归其权利人
• 随仓库预设及效果图中的人物 / IP 素材仅作主题示意；商用或公开再分发请自行确认肖像、素材与商标权利

Star 一下，然后挑一张图，把你的 Codex 变成今天想要的样子。

File: docs/platforms.md Copy Chapter

平台对照

运行模型（两边相同） Copy Chapter

用户本机主题工具
    │  启动官方 Codex + 本机 CDP
    ▼
官方 Codex Desktop（不改 asar / 签名）
    │  注入 CSS + 装饰 DOM
    ▼
仍用原生侧栏 / 输入框 / 建议卡

路径速查 Copy Chapter

macOS Copy Section

Windows Copy Section

Windows 普通启动、失败回滚与恢复重开均从已注册的 OpenAI.Codex 包清单解析 AppUserModelId，并通过系统应用包激活接口完成。若新版 owl runtime 明确把 CDP 参数转换成 codex:// 路径，调试启动会对同一个已验证 Store 包内的精确 app\ChatGPT.exe 做一次原始参数回退；ACL 拒绝或参数保留后仍无可信监听都会停止并回滚，不修改或接管 WindowsApps 权限。Issue #235 已在 26.715.10079.0 与 26.721.3404.0 分别实机确认这两种失败，因此该回退只作安全诊断，不代表受影响 owl 版本已恢复兼容。

能力矩阵 Copy Chapter

自适应图像主题契约 Copy Chapter

同一套主题配置在两个渲染器中使用相同的外观约定。只需要提供一张背景图，注入层就会在本机分析图像并生成协调的颜色、焦点和页面布局；不会上传图片，也不依赖外部 AI/API。

{
  "appearance": "auto",
  "art": {
    "focusX": 0.72,
    "focusY": 0.45,
    "safeArea": "auto",
    "taskMode": "auto"
  }
}

• appearance：auto | light | dark。auto 跟随 Codex/ChatGPT 与系统外观；light / dark 为显式覆盖。图像亮度只参与配色和构图，不会反向覆盖用户选择的外观。
• art.focusX / art.focusY：0..1 的归一化焦点坐标（左/上为 0，右/下为 1）。用于控制背景定位，超出范围的值会被拒绝或限制。
• art.safeArea：auto | left | right | center | none。auto 根据左右信息量推断适合放置原生首页内容的一侧；其余值显式指定安全区，none 表示不保留安全区。
• art.taskMode：auto | ambient | banner | full | off。auto 对超宽图使用横幅/纵向渐隐，对普通比例图使用低噪环境背景；full 保留完整画面并仅叠加基础可读性遮罩；off 在任务页关闭背景图。

显式的 appearance 优先于 Codex/ChatGPT 外观；焦点、安全区和任务模式的显式值优先于图像分析。首页保留更完整的主视觉和原生控件，任务页默认降低背景干扰以保证代码、消息和输入框可读。

平台差异 Copy Section

• macOS 的选图脚本会把这些字段写入主题库，可通过 --appearance、--focus-x、--focus-y、--safe-area、--task-mode 设置。
• Windows 安装会把运行所需的 assets/、presets/、scripts/ 与可选内置运行时原子复制到 %LOCALAPPDATA%\CodexDreamSkin\engine，所有快捷方式均指向该受管副本，因此安装后可移动或删除源码目录。源码安装会保留「桥本有菜」与 Gothic Void Crusade 两个本地参考主题；公开 Setup.exe 只使用已确认可分发的 Gothic Void Crusade 作为首次默认和可切换主题。系统托盘支持更换背景、保存当前主题、从「已保存主题」切换、暂停和恢复；图片与 theme.json 保存在主题仓库中，不写进 Codex 的 config.toml。安装会保留用户已有的 appearanceTheme；仅在识别到旧版精确托管的浅色三元组时按备份迁移。
• Windows 渲染器仍支持在注入前用 window.__CODEX_DREAM_SKIN_CONFIG__ 提供内存级可选覆盖（形状同上，颜色覆盖使用 palette.accent），但普通用户应优先使用持久化主题仓库与托盘。

主题 ZIP 与手动目录 Copy Section

• 两端只接受普通 .zip，明确不兼容 .dreamskin 后缀。新的正式 Studio 包必须包含 manifest.json、非空 theme.json、非空 theme.css、恰好一张 background.webp|jpg|png，并可选带 LICENSE.txt、manifest.sig；文件位于 ZIP 根目录或唯一一层顶级主题目录。仅供本机可信工作流使用的简化格式也必须恰好包含 theme.json、theme.css 与其引用图片。
• 导入前限制为 32 MiB 压缩文件、32 个条目和 64 MiB 解压总量，并拒绝路径穿越、链接/reparse、嵌套压缩包、未注册负载以及未通过主题/图片校验的内容。正式包还会核对平台、最低客户端版本及清单中每个负载文件的大小与 SHA-256。
• theme.css 必须通过同一份 Safe CSS allowlist，本机在导入和每次应用时都会复验；通过后只作用于 12 个注册 data-ds-part 部件。升级前已经保存且没有 CSS 的 legacy 主题仍可使用，但不会注入额外 CSS。manifest.sig 是预留文件，当前不验证签名也不写入主题库；LICENSE.txt 随主题保留。
• 导入目标始终是 saved themes；不会自动覆盖或应用 active / last-known-good。完全相同的内容返回重复结果。同 ID 的新版本会在确认旧目录身份后原地更新，并仅清理语义指纹完全一致、已确认属于同一主题的旧版 -2/-3 重复目录；无法确认身份时拒绝覆盖，名称不作为删除其他主题的依据。
• 手动解压时，把直接包含 theme.json、theme.css 与背景图的完整目录放到 macOS ~/Library/Application Support/CodexDreamSkinStudio/themes/ 或 Windows %LOCALAPPDATA%\CodexDreamSkin\themes\。两端控制菜单均提供“打开主题文件夹”；该路径绕过归档校验，只应用于可信内容。

预设与图片类型 Copy Chapter

• macos/presets/preset-arina-hashimoto/ 是「桥本有菜 / Arina Hashimoto」源码参考主题；公开安装包在人物与素材分发权确认前明确排除它。
• 该 preset pack 中只有 background.jpg（2560 × 1440、16:9、纯背景）和 theme.json 会被播种；它由用户提供的 1672 × 941 源 PNG 标准化导出，不代表增加了源图细节。Byte-identical 源图归档在 docs/images/presets/arina-hashimoto-source.png，不会随 preset 播种；arina-hashimoto-light.jpg 与 arina-hashimoto-dark.jpg 是 2308 × 1572 Retina 浅/暗真实首页截图，未发送输入仅在截图时用临时本地样式遮蔽，只作效果预览，绝不能当背景导入。
• macos/presets/preset-gothic-void-crusade/ 是社区作者贡献的原创哥特科幻主题；macOS 没有活动主题时默认启用它。升级只清理固定的旧内置预设 ID，不删除 custom-* 或当前活动主题副本。
• 源码树中的 windows/assets/dream-reference.jpg 与 macOS 人物参考素材 byte-identical，仅用于本地参考；Windows Release 构建会在打包前以经过固定哈希核验的 Gothic Void Crusade 替换它，确保 Setup.exe 不分发权利未确认的人物素材。README 实机截图仍只作预览，绝不能作为背景导入。
• Windows 导入和 macOS 快速加载入口会拒绝空文件或超过 10 MB 的输入；macOS 主定制入口可接收最高 50 MB 的源图，但转换后的主题文件必须不超过 10 MB。两端 payload 构建还会拒绝任一边超过 16384px 或总像素超过 50MP 的声明尺寸；Windows 在复制导入图前复用 Node 元数据解析器执行同一限制。Windows 注入器用图片、主题和 Safe CSS 内容的 SHA-256 修订值识别热更新，并在构建首帧 payload 前同步读取图片比例。
• 自定义生图优先使用 2560 × 1440（16:9）：左侧约 50%～58% 保持低信息、低对比，主体放在右侧约 58%～88%。输出必须是连续铺满画布的纯背景，禁止窗口、侧栏、卡片、输入框、文字、Logo 和水印。
• 可直接复制的无人物、右侧成年人物与参考图编辑模板见 docs/reference-background-prompt-guide.md；公共默认提示词不指定真人或名人。

不要放进这个目录的东西 Copy Chapter

• API Key、.codex/auth.json
• 中转站密钥、服务器私钥
• 含客户隐私的实机截图（若要公开）

File: docs/PROJECT.md Copy Chapter

Codex Dream Skin · 项目记录

本地归档说明。面向维护者，不是用户安装手册。
仓库首页：../README.md（中文）· ../README.en.md（English）
GitHub：https://github.com/Fei-Away/Codex-Dream-Skin

1. 它是什么 Copy Chapter

Codex Dream Skin 是给 OpenAI Codex 桌面端 用的外部主题 / 换肤方案：

• 本机 CDP 注入 CSS + 装饰 DOM
• 不修改官方 .app / app.asar / WindowsApps / 代码签名
• 侧栏、建议卡、项目选择、输入框仍是原生可点控件（不是整窗假截图）
• 可换图、可一键恢复
• 不会静默改写 API Key / Base URL（换肤与中转配置分开）

非 OpenAI 官方产品。

2. 来源与时间线（简） Copy Chapter

本地曾用过 8765 静态预览与临时 injector；发布后不要求常驻这两个进程。桌面快捷方式指向已安装引擎，不依赖本仓库路径。

3. 架构（两边相同） Copy Chapter

用户本机主题工具（本仓库脚本 / 已安装引擎）
    │  启动官方 Codex + 本机 CDP（127.0.0.1）
    ▼
官方 Codex Desktop（不改 asar / 签名）
    │  注入 CSS + 装饰 DOM
    ▼
原生侧栏 / 输入框 / 建议卡 + 主题外观

更细的平台路径见 platforms.md。

4. 仓库结构 Copy Chapter

Codex-Dream-Skin/
├── README.md              # 默认中文
├── README.en.md           # English
├── docs/
│   ├── PROJECT.md         # 本文件（项目记录）
│   ├── platforms.md       # Win/Mac 路径与能力矩阵
│   ├── promo-copy.md      # 宣传文案（朋友圈等，注意肖像/IP）
│   └── images/
│       ├── gallery/       # README 效果图 skin-01…08
│       └── sponsor-passion8.png
├── macos/                 # Mac 脚本、资源、LICENSE、SKILL
└── windows/               # Windows PowerShell / 注入脚本

安装后的运行位置（Mac，与仓库分离）：

Windows 状态目录见 platforms.md（%LOCALAPPDATA%\CodexDreamSkin）。

5. Git / 移动目录说明 Copy Chapter

• 远程：origin → https://github.com/Fei-Away/Codex-Dream-Skin.git
• 分支：main
• 整夹移动本地路径（例如从 中转站/New-api 挪到 Personal_Developer）：
  • 不影响 .git 历史、commit、remote
  • 不影响 GitHub 上的仓库
  • 只需用 mv 移动整个含 .git 的目录；之后在新路径里 git status 即可
  • 若 IDE / 终端仍开着旧路径工作区，需重新打开新路径

桌面 .command 与 ~/.codex/... 不依赖本仓库磁盘位置，移动开源目录后主题安装仍可用。

6. 安全与合规边界 Copy Chapter

1. CDP 仅 127.0.0.1，主题运行期勿跑来路不明的本机程序
2. 不改官方安装目录与签名
3. 禁止安装脚本静默写入第三方 Base URL / Key
4. 效果图含人物 / IP 时仅作主题示意；商用再分发需自行确认肖像与商标
5. 宣传文案见 promo-copy.md（避免未授权商业化表述）

7. 赞助（Passion8） Copy Chapter

• 注册链：https://passion8.cc/register?aff=TuPe
• README 调性：更智能的连接 / 满血 AI 中转 / 官方模型、无降智无套壳 / 一行接 Codex·Claude Code·Grok
• 固定声明：换肤与 API 配置互相独立

Logo 资源：docs/images/sponsor-passion8.png（及 svg）。

8. 常用维护动作 Copy Chapter

9. 本地路径变迁 Copy Chapter

（若再次移动，在本表追加一行即可。）

10. 相关但不在本仓 Copy Chapter

最后更新：随仓库提交维护。有架构变更时优先改本文件与 platforms.md。

File: docs/promo-copy.md Copy Chapter

宣传文案（可直接发）

仓库：https://github.com/Fei-Away/Codex-Dream-Skin

短版（朋友圈 / 群公告） Copy Chapter

Codex 也能「换皮肤」了。

不是整窗假截图，侧栏、卡片、输入框都还是真控件。
一张图一套主题：千玺、热巴、Miku、KUN、ENFP……你想要的样子自己配。

本机注入，不改官方安装包，还能一键恢复。

开源地址：
https://github.com/Fei-Away/Codex-Dream-Skin

感谢 Passion8 赞助：https://passion8.cc/register?aff=TuPe

中版（公众号 / 即刻 / 小红书） Copy Chapter

标题可选：

1. 我给 Codex 做了个皮肤商店：从人民的 AI 到初音未来
2. 写代码也能有爱豆同款桌面
3. Codex Dream Skin：不拆包，也能把官方界面变成你的

正文：

还在用默认灰白 Codex？有点可惜。

Codex Dream Skin 是一套给 Codex 桌面端用的外部主题方案：
用本机 CDP 把样式和横幅「贴」上去，不修改官方 .app / app.asar，侧栏、建议卡、项目选择、输入框都是原生可点。

你看到的热巴紫夜、千玺清透、Miku 蓝粉、KUN 黑金、ENFP 小宇宙……都是同一套能力换图 + 换色的结果。

开源仓库（含效果图与安装脚本）：
https://github.com/Fei-Away/Codex-Dream-Skin

想稳定接模型的话，可以走赞助方 Passion8（与换肤分开配置）：
https://passion8.cc/register?aff=TuPe

长版钩子（发帖置顶） Copy Chapter

写代码的桌面，也可以有自己的皮肤。

• 真交互，不是 P 一张假 UI
• 可换图、可恢复
• Mac / Windows 脚本都在仓库里
• 效果图直接看 README Gallery

👉 https://github.com/Fei-Away/Codex-Dream-Skin

一句话 slogan Copy Chapter

• 给 Codex 换一张会呼吸的脸
• 一张图，一种心情
• 写代码，也要有氛围感
• 不拆包，也能全员爱豆版 Codex

注意（发的时候自己把关） Copy Chapter

效果图含公众人物 / IP 形象时，仅作主题示意。
二次商用或大规模传播前，请确认肖像与商标授权，避免纠纷。

File: macos/README.md Copy Chapter

Codex Dream Skin Studio

Unofficial macOS theme studio for the official Codex Desktop app.

Turn an image you like into one continuous full-window Codex theme. The same wallpaper runs beneath the native sidebar and main surface, while route-aware translucency keeps home, task, plugin, scheduled-task, and pull-request controls fully interactive and readable.

This project injects through local loopback CDP. It does not modify the official .app, app.asar, or code signature.

Not affiliated with OpenAI. Codex is a trademark of its respective owners.

Requirements Copy Chapter

• macOS 13 Ventura or newer (the native DMG app declares macOS 13 as its minimum)
• Official Codex Desktop installed and launched at least once (~/.codex/config.toml exists)
• No global Node.js install required (uses Codex’s signed bundled Node after validation)

Release install (recommended) Copy Chapter

普通用户请从 GitHub Releases 下载
CodexDreamSkin-vX.Y.Z.dmg，按 docs/install-macos.md 的图形界面步骤
拖入 Applications。首次运行可能需要在“系统设置 → 隐私与安全性 → 仍要打开”确认一次；不需要
运行 xattr 或安装源码。后续更新下载新的 DMG 覆盖安装即可，用户主题和图片会保留。

Advanced: run from source Copy Chapter

The Release DMG above is the normal user path. The commands below are for
contributors, diagnostics, and legacy deployments.

# 1) Optional checks (needs the installed Codex/ChatGPT.app bundled Node)
./tests/run-tests.sh

# 2) Install to the stable path and create Desktop launchers
./scripts/install-dream-skin-macos.sh --no-launch

# 3) Switch to the tested featured preset, or import your own pure background
~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh --id preset-arina-hashimoto
# ~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh

# 4) Start/re-apply, verify, or restore via Desktop:
#    Codex Dream Skin.command
#    Codex Dream Skin - Customize.command
#    Codex Dream Skin - Verify.command
#    Codex Dream Skin - Restore.command

# 5) Legacy only: install the old SwiftBar menu (do not enable it beside the native app)
./Install\ Menu\ Bar.command
# Look for 🎨 Skin in the top-right menu bar

Install location after step 2:

Legacy standalone ZIP (maintainer/offline packaging only) Copy Chapter

To build the “double-click install” folder layout for non-git users:

./scripts/build-client-release.sh "$HOME/Desktop/Codex 主题编辑器.zip"

That ZIP contains a visible installer plus a hidden .codex-dream-skin-studio
engine and is staged as a rights-clean package with only the redistributable
Gothic Void Crusade preset. It is retained for existing offline workflows;
prefer the DMG for ordinary users, and do not share a source checkout or an
archive containing the excluded Arina reference files. Do not ship only
CSS/images.

How it works (security boundary) Copy Chapter

1. Discover com.openai.codex and validate signature / Team ID / arch / bundled Node.
2. Start Codex via user launchd with CDP bound to 127.0.0.1 only.
3. Accept the debug port only when it belongs to Codex (or a legitimate child).
4. Inject only into expected app:// renderer targets.
5. Resolve the selected theme and image to real paths, then enforce 10 MB,
   16384px-per-side, and 50-megapixel limits before injection.
6. Keep a small injector alive across reloads and route changes.
7. Pause/Restore stops the injector only when PID, executable, script path, and
   start time match the recorded job; a stop failure preserves state and aborts.
8. Config backup/restore requires Codex to be closed, strict UTF-8, an operation
   lock, same-directory atomic replacement, and an unchanged-byte check.

CDP is powerful and unauthenticated on loopback. Another process on the same
computer may connect while the CDP-enabled Codex process is running. Removing
the CSS or stopping only the injector does not remove the debug-port launch
argument; use Restore with --restart-codex, or fully quit Codex and reopen it
normally, to end the exposure window. See ../SECURITY.md.

Bundled presets Copy Chapter

The public DMG seeds Gothic Void Crusade, contributed through PR #134, as
its redistributable default. A source checkout also contains the
桥本有菜 / Arina Hashimoto reference material, but the public app bundle
deliberately excludes it until independent likeness and redistribution rights
are confirmed.

The user-provided source PNG is 1672 × 941. Its pack contains a standardized
derived 2560 × 1440 JPEG plus theme metadata; the derived export does not add
source detail. The byte-identical source PNG is archived at
docs/images/presets/arina-hashimoto-source.png.
The light and
dark images are real injected
Codex screenshots for preview only — never import either screenshot as a
background. The artwork is a user-provided AI-generated example, not an
official OpenAI/Codex visual or endorsement; confirm likeness and asset rights
before redistributing it.

Seeding is idempotent. Upgrades remove only retired bundled preset IDs; your
own custom-* themes from “换一张图” and the currently active theme copy are
never touched. Existing locally saved reference themes are not deleted by an
upgrade, but they are not copied into newly downloaded public packages.

To contribute a preset, see presets/README.md.

Import a theme ZIP Copy Chapter

The native menu-bar app has 导入主题 ZIP…. It accepts ordinary .zip
files only; .dreamskin is deliberately unsupported. An official Studio pack
contains manifest.json, non-empty theme.json, non-empty theme.css, and exactly one
background.webp|jpg|png, with optional LICENSE.txt and the
reserved manifest.sig. Put them at archive root or inside one top-level theme
folder. A local simplified pack must contain exactly theme.json, theme.css, and its
referenced image; because it lacks manifest integrity and compatibility data,
use that format only for trusted local content.

The importer allows at most 32 MiB compressed, 32 entries, and 64 MiB expanded.
It rejects links, traversal, nested archives, unregistered payload files, and
anything that fails theme/image validation. Official packs also verify the
platform, minimum client version, and each manifest payload's byte length and
SHA-256. Safe CSS is locally revalidated on import and every apply, then runs
only against the 12 registered parts. manifest.sig is reserved and not used
for signature verification; LICENSE.txt is preserved. Previously saved legacy
themes without CSS remain switchable and inject no additional CSS.

An import only adds to 已保存的主题. It never replaces or applies the
active/last-known-good copy. Reimporting identical content reports a duplicate;
a newer pack with the same ID replaces the saved copy in place after its stored
identity is confirmed. Only a legacy suffix directory (-2, -3, and so on)
with an identical semantic fingerprint is consolidated; names alone never prove
that a directory is a duplicate, so ambiguous entries are preserved.

Manual fallback: choose 打开主题文件夹, or open
~/Library/Application Support/CodexDreamSkinStudio/themes/, then move in the
complete extracted directory whose immediate children are theme.json, theme.css, and the
referenced image. Reopen the menu afterward. Do not add another wrapper folder;
manual placement bypasses archive checks, so use trusted content only.

Image guidelines Copy Chapter

• PNG / JPEG / HEIC / TIFF / WebP (macOS readable)
• Source ≤ 50 MB; prepared file ≤ 10 MB, ≤ 16384 px per side, and ≤ 50 MP
• 2560 × 1440 (16:9) is the recommended master size; width ≥ 2000 px minimum
• Keep roughly the left 50%–58% calm and low-contrast for native home content;
  place the subject in the right 58%–88% without touching the edge
• Use pure edge-to-edge background art only: no window chrome, sidebar, cards,
  buttons, composer, readable text, logo, or watermark
• The prompt-ready composition template and negative prompt live in
  docs/reference-background-prompt-guide.md

Adaptive image themes Copy Chapter

The renderer treats every image as a theme input instead of assuming a fixed
character palette. It downsamples the image in a local Canvas to estimate
brightness, accent color, visual focus, left/right safe area, and aspect ratio.
The pixels stay in the Codex renderer; there is no upload or external API call.
If Canvas analysis is unavailable, the theme falls back to a safe default and
the detected Codex shell/OS appearance.

Theme metadata is optional. The defaults are deliberately adaptive:

{
  "appearance": "auto",
  "art": {
    "focusX": 0.72,
    "focusY": 0.45,
    "safeArea": "auto",
    "taskMode": "auto"
  }
}

• appearance: auto, light, or dark. auto follows the native
  Codex/ChatGPT or OS appearance; an explicit value wins. Image luminance
  still informs palette and composition, but never overrides the user's UI mode.
• art.focusX / art.focusY: normalized 0..1 coordinates used for
  background-position (left/top is 0, right/bottom is 1).
• art.safeArea: auto, left, right, center, or none. Automatic mode
  finds the lower-information side so native home content does not cover the
  subject. Use none when the artwork should fill the composition evenly.
• art.taskMode: auto, ambient, banner, full, or off. Ultra-wide art
  automatically uses a full-width task banner with a vertical fade; standard
  art uses a quieter ambient layer. full keeps the artwork at normal strength
  with only the baseline readability veil; off removes the task-page artwork
  while leaving the rest of the theme active.

The image-derived palette is used unless a theme explicitly supplies color
fields. Explicit art metadata (focusX, focusY, safeArea, taskMode) has
the same priority over automatic inference. The home route remains expressive;
task routes keep native content, cards, composer, and code readable above the
image layer.

CLI example:

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh \
  --image "/path/to/image.png" \
  --name "My theme" \
  --accent "#7cff46" \
  --secondary "#36d7e8" \
  --highlight "#642a8c"

To tune composition without changing the image, pass the adaptive fields to
the image loader:

~/.codex/codex-dream-skin-studio/scripts/load-image-theme-macos.sh \
  --file "/path/to/image.png" \
  --appearance auto \
  --focus-x 0.72 --focus-y 0.45 \
  --safe-area left --task-mode banner

Reset to the bundled abstract demo:

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh --reset-demo

License Copy Chapter

MIT — see LICENSE. Additional notices in NOTICE.md cover trademarks,
runtime Node, user-provided artwork, third-party rights, and assets that are not
licensed under the software license.

Sponsors Copy Chapter

Thanks to passion8.cc for sponsoring this project.

What this is not Copy Chapter

• Not an OpenAI product and not a fork of Codex source
• Not a way to patch or rebrand the official binary
• Not a Windows build (see ../windows/)
• Not an API proxy: theming does not change model providers or API keys

If you use a third-party API relay, configure it separately — keep theme install and API config as two explicit steps.

File: README.en.md Copy Chapter

Codex Dream Skin

🤝 Exclusive sponsor Copy Chapter

| | Thanks to Passion8 for being this project's exclusive sponsor! Passion8 is an AI API relay for developers, giving individuals and teams stable, low-cost access to mainstream large models.
Full-power AI, within reach: the full OpenAI and Claude lineups, original models, no silent downgrades and no wrapper shells; frontier models for a fraction of official pricing, with top-ups at 1:1 — $1 = ¥1. Keep your official SDK and point the base URL at Passion8: Claude Code, Codex, Grok, and any OpenAI-compatible client just work — one line of config, no code changes.
Global edge acceleration: Cloudflare's global edge plus multi-route BBR acceleration for low latency and high availability; 7×24 relay, 99.9% SLA, sub-second TTFT target.
Secure by default: isolated API keys, encrypted key storage, and HTTPS end to end — privacy first.

Passion8 has a benefit for this project's users: register through this link and your first top-up earns an automatic 10% bonus — no application needed, credited within 30 minutes. Questions go to [email protected]. |
| --- | --- |

_{Theme install and API config stay separate — this project never rewrites your provider settings.}

Install directly Copy Chapter

Ordinary users first install and quit the official Codex / ChatGPT app once,
then download from GitHub Releases:

• macOS: open CodexDreamSkin-vX.Y.Z.dmg and drag the app to Applications.
• Windows: run CodexDreamSkin-Setup-vX.Y.Z.exe and follow the wizard.

No source checkout, Node.js install, .sh, or .ps1 command is required. See
the macOS guide or
Windows guide for unsigned first-run approval,
updates, and uninstall steps.

Theme library & community Copy Chapter

• Gallery — browse reviewed community themes
  with recent/popular sorting and creator rankings. Every theme can be tried on
  in an in-page desktop simulator before you install it.

• Online Studio — swap the background, tune
  theme colors, and write Safe CSS in the browser, then export a .zip pack or
  submit it to the library (sign-in required; published after human review).

The macOS menu bar and Windows tray both link straight to Gallery and
Online Studio.

One-click apply Copy Section

Found a theme you like on DreamSkin.cc? Apply hands it to the local client
directly — no download-then-import step. Requires client v1.5.0 or newer
(v1.5.5+ recommended).

Flow and safety boundary:

• The page invokes the local app through dreamskin://apply?version=ver_....
  The link can carry exactly one theme version ID — never an arbitrary URL,
  file path, or command — and there is no silent-apply parameter.
• The app fetches the package only from the fixed official API, and refuses
  redirects.
• A native confirmation appears first, and the app checks the version's review
  status, apply-compatibility flag, version, package size, actually downloaded
  byte count, and SHA-256.
• It then reuses exactly the same ZIP, manifest, image, and Safe CSS validation
  as a manual import.
• Success requires the real renderer to report the new theme as rendered. On a
  launch or render failure the app tries to restore the previous theme, and the
  restore is itself visibility-verified; if it cannot confirm either state it
  reports the status as unconfirmed rather than claiming a rollback.

Only themes that fully satisfy the current pack contract (background image +
theme.json + non-empty theme.css + declared safe-css capability) show the
one-click button. Anything else goes through the manual import below.

Tested featured presets Copy Chapter

Gothic Void Crusade / 哥特虚空远征 Copy Section

Special thanks to @seansong-ideogram for designing and contributing this striking, atmospheric original gothic science-fiction work to the community. It leads the tested featured presets and is the default theme for fresh macOS installs.

After installing on macOS, switch directly from Saved Themes in the menu bar.

Arina Hashimoto / 桥本有菜 Copy Section

“Arina Hashimoto / 桥本有菜” has been verified on the real Codex home screen in
both light and dark appearances. The user-provided source PNG is 1672 × 941;
the preset's 2560 × 1440 JPEG is a standardized derived export that preserves
the source's near-16:9 composition and does not add source detail. The sidebar,
cards, project picker, and composer
shown below are native Codex controls.

This portrait material remains in the source repository for reference and
rights review; it is excluded from public DMG and Setup.exe assets. Public
installers seed only the redistributable Gothic Void Crusade preset. Users can
still choose Change Background to import UI-free artwork they are entitled
to use and save it for one-click switching.

The downloadable user source is docs/images/presets/arina-hashimoto-source.png (1672 × 941); the source-only reference preset uses the normalized derived background.jpg (2560 × 1440). Do not import either screenshot above: they contain real UI and are previews only. The background is a user-provided AI-generated example, not an official OpenAI/Codex visual or endorsement; do not put it in a public installer without confirmed likeness and asset rights.

What it does Copy Chapter

• Real UI — Sidebar, cards, project picker, and input stay native. Not a fake full-window screenshot.
• Continuous wallpaper — One 16:9 image spans the full window; adaptive focus, safe-area, and route treatment keep native content readable.
• Swappable art — Drop in a UI-free image you like and it becomes your theme.
• Saved themes — Switch local themes from the macOS menu bar or Windows system tray.
• One-click apply — Hit apply on DreamSkin.cc; the client verifies origin and checksum, then installs it.
• Theme ZIP import — Pick an ordinary .zip on either platform and add a validated pack to the local library.
• Restorable — One-click restore to the stock look.
• Safer path — Local-loopback CDP inject only. No official binary or signature changes.

Quick start Copy Chapter

For users: download an installer Copy Section

You do not need to clone the repository, install Node.js, or run .sh / .ps1
files. Download the latest package for your platform from
GitHub Releases, then
follow the graphical first-run guide:

After installation, use the menu bar (macOS) or system tray (Windows). Updates
are manual: download the new package and install over the existing one; themes
and images are preserved. Because the public packages are unsigned, a new
download may show a one-time OS security warning; the guides explain the safe
GUI approval path.

Import a downloaded theme Copy Section

For themes from DreamSkin.cc, prefer one-click apply. The
manual .zip path below is the fallback, and covers packs from any other source.

Choose Import Theme ZIP… from the macOS menu bar app or Windows tray. Only
ordinary .zip files are accepted; the legacy .dreamskin extension is not
supported, and renaming the suffix is not a supported migration path. An
official Studio pack contains manifest.json, theme.json, and exactly one
background.webp|jpg|png, plus non-empty theme.css; LICENSE.txt and the
reserved manifest.sig. Put these files at ZIP root or inside exactly one
top-level theme folder. The importer verifies platform and minimum-client
compatibility plus every declared payload file's byte length and SHA-256.
theme.css must pass the local Safe CSS validator and can affect only the 12
registered parts. It is revalidated on every import and apply. manifest.sig
is not used for signature verification.

The local simplified ZIP must contain exactly non-empty theme.json, non-empty
theme.css, and its referenced image. That format has no official
manifest integrity or compatibility declaration and should come from a trusted
source. Limits are 32 MiB per archive, 32 entries, and 64 MiB expanded. Import
adds the pack to Saved Themes without changing the active theme. Identical
content is not duplicated. A newer pack with the same ID updates the saved theme
in place after the old directory identity is confirmed, and only legacy -2/-3
directories with an identical semantic fingerprint are cleaned up. If the
existing directory identity cannot be confirmed, import fails closed instead of
overwriting it; names alone are never used to delete another theme.

For a manual fallback, extract the archive and move the complete directory
containing theme.json, theme.css, and its image into the saved-theme folder:

• macOS: ~/Library/Application Support/CodexDreamSkinStudio/themes/
• Windows: %LOCALAPPDATA%\CodexDreamSkin\themes\

Both controls include Open Themes Folder. Reopen the menu/tray after moving
the directory. Do not add another wrapper level, links, nested archives, or an
image-only folder without theme.json. Manual placement bypasses the ZIP
importer's archive checks, so use trusted content only.

For developers: run from source Copy Section

Platform scripts are ready — different plumbing, same goal: theme Codex.

More detail:

• Mac: macos/README.md
• Windows: windows/README.md
• Paths: docs/platforms.md
• Copy-ready reference prompt guide: docs/reference-background-prompt-guide.en.md
• Eight concept prompt breakdowns: docs/background-generation-prompts.md
• Project notes: docs/PROJECT.md

Feedback & contributions Copy Chapter

• Issues: Use the issue templates (bug / feature). Blank issues are disabled. Please try Verify / Restore self-checks before filing bugs.
• PRs: Follow the PR template — describe the change and tick the self-checks you actually ran (e.g. macos/tests/run-tests.sh, verify / restore).

Safety Copy Chapter

• CDP binds 127.0.0.1 only, but it has no authentication; another process on the same computer may still connect and inspect or control the renderer.
• Pausing the theme or stopping only the injector does not close the debug port of an already running Codex process. Use a full Restore/restart, or quit every Codex process and reopen the official app normally, to end the exposure window.
• Does not touch the official install directory or code signature.
• Never rewrites API Key / Base URL; relay and theme stay separate.
• See SECURITY.md for the complete threat model and operating guidance.

License Copy Chapter

• See macos/LICENSE (MIT) and macos/NOTICE.md
• Unofficial; Codex and related rights belong to their owners.
• People / IP material in bundled presets and previews is illustrative only — clear likeness, asset, and trademark rights before commercial redistribution.

Star it, pick a look, and make Codex yours for today.