给 Codex 桌面端一键换肤的工具（HeiGe Codex Skin Studio）

Codex Desktop 的界面默认只有一套浅色或深色外观。想把它换成自己喜欢的角色或配色，常见做法是改 app.asar、替换应用资源，或者重新打包签名。客户端每更新一次，改动就失效，装坏了还得从头再来。

HeiGe Codex Skin Studio 是一个用 JavaScript 写的 Codex 桌面端换肤工具，通过本机回环 CDP 把样式注入界面，输入一张图片或一套内置主题，输出换肤后的 Codex 窗口，支持 macOS 与 Windows。

它不修改 app.asar、应用二进制与签名资源，Codex 升级后不会留下坏掉的安装。日常换肤落在客户端顶部的「主题」菜单里，还原原生界面同样是一次点击。

支持范围覆盖 macOS 与 Windows，同一套引擎还能给腾讯 CodeBuddy 桌面端（WorkBuddy）换肤，走另一个回环端口。仓库主要语言 JavaScript 占 81.8%，其余是 PowerShell 15.9%、Swift 1.4%、Shell 0.7%、Batchfile 0.2%，采用 MIT 许可证。仓库地址：https://github.com/HeiGeAi/heige-codex-skin-studio。当前 479 star、67 fork、2 个开放 Issue，最近一次提交在 2026-10-08。

它解决的是什么问题

Codex Desktop 是 Electron 应用，界面样式打包在应用内部。想改配色或背景图，过去只有两条路：解包 app.asar 改完再压回去，或者从源码重新构建一个客户端。前者会破坏签名资源，客户端自动更新后改动全部丢失；后者要求你自己跟进上游每一次发布。

这个项目把改动放在运行时。它以调试端口连上已经启动的 Codex 进程，往渲染层里注入 CSS 与背景资源，应用文件保持原样。因此客户端升级不会留下半改状态，卸载也只是停掉注入、注销计划任务、清理状态目录。

代价是它依赖客户端的界面结构。上游换了启动参数或 DOM 结构，注入就可能失效，需要项目跟着适配。README 明确写了这一点：未来 Codex Desktop 改变启动参数或界面结构时，本项目仍可能需要适配。

典型使用场景

• 每天长时间对着 Codex 写代码的人，把界面换成 Miku、原神、鸣潮、火影忍者、恋与深空、龙珠或财神等内置主题，让长时间盯屏不那么单调。
• 手上有现成图片的人，想把它做成一套皮肤：菜单里上传，或者双击 customize.command 从文件生成一整套配色加背景底图。
• 不想自己配色的人，把仓库里的 skill 文件交给 Codex，让它先生成主图再直接做成皮肤，全程不需要额外的 API Key。
• 同时在用腾讯 CodeBuddy 桌面端（WorkBuddy）的人，用同一套引擎给这个客户端也换上主题，两个产品的皮肤入口互不干扰。

几个常见疑问

换肤会改动 Codex 的安装文件吗？

不会。注入走本机回环 CDP，地址是 127.0.0.1:9341，不修改 app.asar、应用二进制或签名资源。还原原生界面在菜单里点一次即可。这也意味着皮肤只在注入会话内存在，进程完全退出后会回到官方界面，需要常驻的话要在顶部菜单打开「皮肤常驻」。

Windows 商店版（Microsoft Store/MSIX）能用吗？

README 标注商店版需要真机验证，自动接管在端口不可达时无法完成。商店版若报回环隔离，可以先运行 scripts\windows\enable-loopback.bat（一次管理员权限）再重试 apply。Issue 区里两条与商店版相关的报错都已经关闭。

WorkBuddy 的皮肤为什么重启后要重新应用？

WorkBuddy 侧只做一次性皮肤，不创建常驻服务。项目的说明是：它的 renderer 是本地 file:// 页面，回调控制服务时带的来源是 Origin: null，放行会削弱控制服务的来源校验，所以这版不开控制通道。重启后皮肤消失属于预期行为，重跑一次 apply 即可。

主要功能

• 13 套内置预设：高精度定制的 Miku 488137 打底，加原神（星夜、破晓）、鸣潮、火影忍者、恋与深空、龙珠（筋斗云、超级赛亚人）、「财神 · 清爽可读」以及彩蛋预设「大佬 · 点烟」。预设会同步切换 Codex 自身的浅色或深色外观。安装包还带可选的 Miku Future 动画桌面宠物，不覆盖 Codex 内置宠物。
• 自定义图片取色：顶部「主题」菜单里选「＋ 自定义图片」，支持 PNG、JPG、JPEG、WebP，上传后自动取色、自动配深浅外观，并写入本机用户主题库，同名同图是幂等覆盖。
• 本地生成完整皮肤：双击 customize.command，任意上述格式的图片都能生成一套配色加背景底图的完整皮肤。
• 交给 AI 全包：把 output/heige-codex-skin-studio.skill 交给 Codex，直接说「先生成一张蓝紫色赛博城市主图，再做成皮肤」，从生成到应用全自动，不需要额外 API Key。
• macOS 皮肤启动器：安装后在 $HOME/Applications 生成「HeiGe 皮肤启动器.app」，原生面板显示 Codex 与 WorkBuddy 两张卡片，各自可以打开或关闭当前皮肤，底部有「一键修复」与「诊断与日志」。
• 皮肤常驻：顶部菜单的「皮肤常驻」是唯一受支持的常驻入口。Windows 为当前用户注册登录计划任务，macOS 写 LaunchAgent，重启后后台控制器恢复主题与顶部入口。开启成功时开关会在数秒内变绿，失败会立刻提示。
• 阅读增强与界面通透度：阅读增强默认开启，50 档时最终回复和过程回复都使用 90% 主题自适应半透明底色；通透度滑杆支持 0 至 100 档，50 档保持原有观感，遮罩不透明度不低于 60%，偏好本地保存并跨窗口同步。WorkBuddy 换肤不显示该滑杆。
• 入口隐藏与随机主题：顶部主题入口可以收起为小圆点，点击恢复，状态会保存；另有持久化的随机主题开关，随机选主题并尽量避免连续重复。

安装与最短示例

前置条件是已装好的 Codex Desktop。使用系统 Node 时要求 Node.js 22 或更新版本。

macOS 下载仓库后双击安装脚本：

open "<仓库路径>/scripts/install.command"

装完默认应用 Miku 预设，并在 $HOME/Applications 创建或升级「HeiGe 皮肤启动器」：

open "$HOME/Applications/HeiGe 皮肤启动器.app"

Windows 用 scripts\windows\install.bat 安装，日常入口是 scripts/windows/apply.ps1，另有兼容名 scripts/windows/enable-skin.bat、pause.ps1、resume.ps1、restore.ps1。彻底移除运行 scripts\windows\uninstall.bat，它会注销当前用户计划任务、移除开始菜单入口、清理 AppData 状态和稳定安装目录。

给 WorkBuddy 换肤用另一条命令，还原跑 scripts/workbuddy-restore.command：

"<仓库路径>/scripts/workbuddy-apply.command" --restart

关键参数

• 端口：Codex 固定用 127.0.0.1:9341，WorkBuddy 用 127.0.0.1:9342，两者互不干扰。
• --restart：先彻底退出目标客户端再拉起注入，用于整窗卡顿时的恢复；健康会话下直接重跑 apply 是幂等的，不会重启进程。
• 通透度滑杆：0 至 100 档，50 档为原有观感，越大越通透，遮罩不透明度下限 60%。
• 阅读增强：默认开启，默认 50 档对应 90% 半透明底色，可在主题中心随时关闭。
• enable-skin.command 是 session-only 兼容入口；enable-persist.command 是已弃用的非零退出入口。

结果在哪里看

注入成功后，目标客户端顶部会出现「主题」入口，点开是主题中心：当前主题、自定义图片、原生界面、内置主题预览、阅读增强和皮肤常驻开关都在一屏里，主题卡片即点即换。Windows 上入口同样在顶部，可以选择隐藏为小圆点。

macOS 的产品卡片与修复入口在「HeiGe 皮肤启动器.app」里，运行失败会在卡片内显示并允许重试，「诊断与日志」可以打开两个产品各自隔离的状态目录。仓库文档方面，docs/manual.md 是完整手册，docs/windows-compat.md 记录 Windows 各功能的验证状态与已知问题，docs/theme-prompts.md 提供 8 套现成的生图提示词。

实际使用中的坑

• 商店版报 AUMID relaunch drops CDP arguments and apply exits 1，表现为 AUMID 方式重启后 CDP 参数丢失、apply 退出码为 1。该 Issue 已解决（2 条评论），但 README 仍标注 MSIX 真机待验证。
• 商店版在 Codex/CDP 就绪后报 LOCK_STAGING_WRITE_FAILED。该 Issue 已解决（2 条评论）。
• Windows 上出现「未找到 Codex Desktop，请确认已安装官方客户端」并列出已探测路径。该 Issue 已解决（2 条评论）。
• 整窗突然变卡，表现为帧率骤降、输入与滚动全局迟滞。README 给出的处置是跑 scripts/apply.command --restart。
• 待解决的一条是贡献提议：有人希望贡献一套 Windows 皮肤管理器（Electron / React，简洁界面、主题跨页拖拽与窗口记忆），目前按 CONTRIBUTING.md 走范围讨论，尚未合并。

和同类的差别在哪

只想给 Codex 或 WorkBuddy 换主题，本项目的开箱成本最低，预设和菜单都现成。要在别的 Electron 应用上做类似注入、或者要写自己的 CDP 自动化，本项目帮不上忙，得直接基于 CDP 协议自己实现，jseval 那类工具解决的是同类技术问题但不是同一件事。本项目覆盖面窄是它的取舍，不是疏忽，选型时按目标客户端是否在支持列表里决定。

合规前提

这个工具的运作方式是往本机回环调试端口注入样式。CDP 即使只绑定本机回环也没有认证，本机同权限进程在威胁边界内，完整说明写在 SECURITY.md。使用范围应限于自有设备与已获授权的客户端，不要对他人设备、他人账号环境或未授权的目标使用注入手段，误用会触及平台条款与法律风险。

内置主题里的第三方角色素材，来源逐文件登记在 ASSET_PROVENANCE.md，醒目位置也提示投稿素材需为公开安全素材。拿角色形象做二次分发前，先确认原权利方的授权范围。

它适合经常使用 Codex Desktop、希望界面长期保持个人风格、又愿意接受「上游改结构就得等适配」的人；也适合已经在用 WorkBuddy、能接受皮肤一次性生效的人。它不适合需要给任意 Electron 应用换肤、或者要求主题在所有客户端版本上永久稳定的人，这类需求应当直接走 CDP 自研方案。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.1 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。