把一张喜欢的图片，变成可切换、可恢复、可验证的 Codex Desktop 皮肤。
Codex Dream Skin Studio 是一个面向 macOS 官方 Codex Desktop 的非官方开源换肤工具，同时也是一个可以被 Codex 直接调用的 Skill。
它不会修改官方应用包、app.asar 或代码签名，而是通过只监听本机回环地址的 Chromium DevTools Protocol（CDP），在 Codex 运行时注入主题样式。你可以安装主题、换图、切换预设、检查是否生效，并随时恢复官方界面。
本项目与 OpenAI 无隶属、授权或赞助关系。Codex、ChatGPT 及相关商标归各自权利人所有。
下面是公开版附带的「阿田阳光工作室」纯背景素材。真正运行时，Codex 的侧栏、任务内容和输入框仍然是原生可交互界面。
这套主题采用：
- 左侧明亮文件夹栏，保持一行一行的项目名称清晰可读。
- 主对话区使用宽幅暖白阅读面，避免大面积图片干扰正文。
- 右侧只保留一条柔和画景，作为工作台氛围装饰。
- 阿田卡通人物缩小到右下角，不压住任务文字。
- 首页比任务页更有画面感；进入长对话后自动优先保证阅读。
很多所谓的 Codex 皮肤，本质上只是把一张大图铺在窗口背后。图片好看，但进入真实任务后容易出现几个问题：
- 人物或高对比背景压住文字。
- 为了看清内容，只能给全屏加一层白色雾化遮罩。
- 首页好看，长对话、代码块、表格和设置页却不可读。
- 换肤脚本直接修改应用文件，升级后容易失效，也不好恢复。
这个项目把“图片氛围”和“工作界面可读性”分开处理：图片负责气质，原生界面负责工作。主题会根据首页、任务页、侧栏、输入框等不同区域采用不同的阅读层，同时保留所有原生交互。
- 一键安装到稳定目录。
- 双击启动、验证、换图和恢复。
- Codex Skill 调用：可以直接对 Codex 说“帮我安装/切换/修复皮肤”。
- 支持 PNG、JPEG、HEIC、TIFF、WebP。
- 自动读取图片亮度、主色、视觉焦点和安全区。
- 支持浅色、深色和自动跟随系统。
- 首页与任务页采用不同的图片呈现策略。
- 支持多主题保存和快速切换。
- 支持 SwiftBar 菜单栏入口。
- 使用官方应用自带的已签名 Node.js，不要求全局安装 Node。
- CDP 只绑定
127.0.0.1，并校验监听进程和渲染目标。 - 提供完整恢复机制，不修改官方应用文件。
- 带静态测试、主题验证、图片大小限制和路径越界防护。
- macOS 13 或更新版本。
- 已安装并至少启动过一次官方 Codex Desktop（当前应用名称可能显示为 ChatGPT）。
- 应用的 bundle id 为
com.openai.codex。 - 不要求单独安装 Node.js。
- Windows 和 Linux 暂未支持。
把这个仓库下载到本机后，在 Codex 中输入：
使用 $codex-dream-skin-studio 安装这个项目，启用“阿田阳光工作室”主题，并在完成后验证侧栏、任务页和输入框是否正常。
Skill 会按以下顺序工作：检查环境、安装引擎、选择主题、在需要时征得重启许可、启动注入器、验证界面、报告恢复方法。
- 下载仓库 ZIP 并解压。
- 双击
Install Codex Dream Skin.command。 - 如果 macOS 阻止打开，请在“系统设置 → 隐私与安全性”中允许，或右键选择“打开”。
- 安装后双击
Start Codex Dream Skin.command。 - 使用
Verify Codex Dream Skin.command检查结果。
git clone https://github.com/atian-create/codex-dream-skin-studio.git
cd codex-dream-skin-studio
# 先测试
./tests/run-tests.sh
# 安装，但暂不启动
./scripts/install-dream-skin-macos.sh --no-launch
# 切换到阿田主题
~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
--id atian-sunlit-studio
# 启动皮肤；如果 Codex 正在运行，需要明确允许重启
~/.codex/codex-dream-skin-studio/scripts/start-dream-skin-macos.sh \
--restart-existing详细步骤见 安装与卸载。
| 内容 | 默认位置 |
|---|---|
| 引擎 | ~/.codex/codex-dream-skin-studio |
| 当前主题、主题库、日志和状态 | ~/Library/Application Support/CodexDreamSkinStudio |
| 桌面启动入口 | 桌面上的 .command 文件 |
| 菜单栏入口（可选） | SwiftBar 插件目录 |
安装脚本不会把主题代码写入官方 .app。
查看当前主题库：
ls "$HOME/Library/Application Support/CodexDreamSkinStudio/themes"切换阿田主题：
~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
--id atian-sunlit-studio切换抽象主题：
~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
--id preset-midnight-aurora公开版包含：
atian-sunlit-studio：阿田阳光工作室。preset-midnight-aurora：午夜极光。preset-sakura-dawn：樱粉晨曦。preset-amber-dusk：琥珀黄昏。preset-forest-mist：森野薄雾。preset-cyber-neon：赛博霓虹。
抽象主题由仓库内的 Node 脚本程序化生成，不依赖第三方照片。
双击：
Customize Codex Dream Skin.command
或者执行：
~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh精确指定图片与主题信息：
~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh \
--image "/绝对路径/你的图片.png" \
--name "我的工作台" \
--accent "#F05A7E" \
--secondary "#9BAA42" \
--highlight "#F1A53C"只调整构图，不重新生成图片：
~/.codex/codex-dream-skin-studio/scripts/load-image-theme-macos.sh \
--file "/绝对路径/你的图片.png" \
--appearance light \
--focus-x 0.76 \
--focus-y 0.50 \
--safe-area left \
--task-mode ambient推荐尺寸：2560 × 1440，16:9。
一张适合工作界面的背景图，通常应满足：
- 图片中不要直接画入侧栏、输入框、按钮或任务卡片。
- 不要烘焙文字、Logo、水印和菜单。
- 左侧或中间至少保留 50% 的低细节区域。
- 人物、植物、灯具等高对比元素放到最右侧。
- 人物不要超过画布高度的 20%–30%，除非只用于首页。
- 长任务页比首页更需要留白。
- 与其给全屏加雾，不如把阅读区与画图区分开。
- 浅色主题避免纯白人物轮廓压在白色面板上。
- 深色主题避免霓虹高光出现在代码文字背后。
完整制作方法见 主题制作指南，可复制的生成提示词见 背景图提示词示例。
{
"schemaVersion": 1,
"id": "my-sunlit-studio",
"name": "我的阳光工作室",
"image": "background.png",
"appearance": "light",
"homeMode": "showcase",
"art": {
"focusX": 0.76,
"focusY": 0.5,
"safeArea": "left",
"taskMode": "ambient"
},
"colors": {
"background": "#FFF8EF",
"panel": "#FFFDF8",
"panelAlt": "#FFECE6",
"accent": "#F05A7E",
"accentAlt": "#FF8B63",
"secondary": "#9BAA42",
"highlight": "#F1A53C",
"text": "#3B231F",
"muted": "#806A63",
"line": "rgba(240, 90, 126, .24)"
}
}字段说明：
appearance：auto、light、dark。homeMode：showcase会让首页更突出图片，同时在任务页优先阅读。focusX/focusY：图片焦点，范围0..1。safeArea：auto、left、right、center、none。taskMode：auto、ambient、banner、off。colors：可选；不提供时会从图片估算配色。
~/.codex/codex-dream-skin-studio/scripts/verify-dream-skin-macos.sh验证器会检查：
- 是否连接到官方 Codex 渲染器。
- 样式和渲染脚本是否存在。
- 侧栏是否可见。
- 输入框是否可见。
- 装饰层是否不会拦截鼠标。
- 文档是否出现横向溢出。
- 首页建议卡片是否仍保持原生交互。
验证通过只说明注入与核心结构正常。发布自己的主题前，仍建议人工检查：新任务页、长对话、代码块、表格、插件、已安排任务、设置页、浅色/深色和窗口缩放。
暂停本次换肤：
~/.codex/codex-dream-skin-studio/scripts/pause-dream-skin-macos.sh完全恢复官方外观：
~/.codex/codex-dream-skin-studio/scripts/restore-dream-skin-macos.sh也可以双击 Restore Codex Dream Skin.command。
主题图片 + theme.json
│
▼
本地主题暂存与安全校验
│
▼
以 127.0.0.1 CDP 端口启动官方 Codex
│
▼
确认监听进程、官方签名与 app:// 渲染目标
│
▼
注入 CSS + 路由感知的渲染辅助脚本
│
▼
保留原生侧栏、任务内容、输入框与交互
更详细的技术说明见 架构与安全模型。
- CDP 只绑定本机回环地址，不监听局域网。
- 只接受由官方 Codex 可执行文件或合法子进程持有的端口。
- 只注入预期的
app://页面。 - 图片路径必须位于主题目录内，拒绝符号链接越界。
- 单张准备后图片不得超过 16 MB、单边 16384 像素或 50 MP。
- 主题文本拒绝换行和控制字符。
- 恢复时核对注入器 PID、启动时间、脚本路径和 Node 路径。
- 不修改官方应用包、签名或
app.asar。
CDP 本身是一个强大的本地调试接口。启用皮肤时，不要运行来源不明、会扫描本机端口的软件；不使用皮肤时建议执行恢复。
通常是 Codex 已经在没有调试端口的状态下运行。先保存当前任务，再允许安装器重启 Codex。详见 故障排查。
皮肤不是修改应用文件，因此普通方式重新启动 Codex 时不会自动带上 CDP。请使用桌面上的 Start 入口，或安装 SwiftBar 菜单栏入口。
优先使用 safeArea、focusX、taskMode 和低细节背景重新构图，不建议给全屏加高透明度白雾。任务页应把图片收窄到装饰区，阅读区保持接近实色。
官方界面的 DOM 结构可能变化。先运行验证器，再查看 Issue 中是否已有兼容修复。不要直接修改官方应用包。
软件代码采用 MIT License。你自己的背景图、人物形象、字体、Logo 和第三方素材仍需自行确认授权。
codex-dream-skin-studio/
├── SKILL.md # Codex Skill 入口
├── agents/openai.yaml # Skill 列表元数据
├── scripts/ # 安装、启动、切换、验证、恢复
├── assets/ # 注入样式与渲染脚本
├── presets/ # 可直接切换的主题包
├── tests/ # 静态与运行时测试
├── references/ # 按需读取的详细文档
├── examples/ # 主题配置与提示词示例
├── docs/images/ # README 公共图片
├── LICENSE
└── NOTICE.md
克隆仓库后，可将整个目录放入：
~/.codex/skills/codex-dream-skin-studio
或者建立符号链接：
ln -s "/你的仓库路径/codex-dream-skin-studio" \
"$HOME/.codex/skills/codex-dream-skin-studio"重新打开 Codex 后，可以这样调用：
使用 $codex-dream-skin-studio 帮我安装阿田阳光工作室皮肤。
使用 $codex-dream-skin-studio 把这张图片做成 Codex 主题，人物放右侧，任务页优先保证文字可读。
使用 $codex-dream-skin-studio 检查皮肤为什么没有生效，并在不修改官方 app 的前提下修复。
使用 $codex-dream-skin-studio 完全恢复 Codex 官方外观。
欢迎提交：
- 新的无版权风险主题预设。
- 新版 Codex DOM 兼容修复。
- 可读性、无障碍和窗口缩放优化。
- Intel Mac 与 Apple Silicon 兼容报告。
- 中文文档修订和英文翻译。
- 安全边界与恢复流程改进。
提交前请阅读 CONTRIBUTING.md，运行：
./tests/run-tests.sh公开预设不得包含未授权人物、明星肖像、品牌素材、客户数据、真实任务截图、API Key、Cookie 或私人文件路径。
软件代码使用 MIT License。素材与商标边界见 NOTICE.md。
Codex skin · Codex theme · Codex Desktop · Codex Skill · macOS theme · AI coding workspace · desktop customization · CDP theme injector · Codex 皮肤 · Codex 换肤 · Codex 主题 · Codex 美化
如果这个项目对你有帮助，欢迎 Star、提交 Issue，或者贡献一套有明确素材授权的主题。