CodeDrobe Theme 是 CodeDrobe 项目在 2026 年推出的一个可安装 Agent Skill，主要用于给 Codex 这类基于 Chromium 或 Electron 的桌面应用进行界面美化与主题换肤。简单理解，如果你想让 Codex 的整体外观彻底焕新，例如自定义 CSS、设置背景图片、调整首页布局，甚至制作一套可以打包分发的主题包，那么它就是非常实用的工具。Codex 自带的“外观”设置，只能修改基础主题、强调色、背景色和字体，属于较基础的界面调整。而 codedrobe-theme 这个 Skill，会调用 @codedrobe/core 来执行 DOM 快照、兼容性预检、主题注入、截图验证以及事务式恢复。整个过程无需替换应用安装包，如果出现问题，也可以通过一条命令快速还原。
那么，给 Codex 换皮肤具体是什么意思？本质上就是修改桌面应用或终端界面的配色、字体、背景以及组件样式。如果你只是想简单调整颜色，使用原生外观功能通常就够了；但如果你需要完整的 CSS 主题和图片主题，就需要借助 CodeDrobe 来实现。
Codex 原生主题和 CodeDrobe 有什么区别
这两种方式解决的是不同层级的主题定制需求。正式选择之前，建议先明确自己的目标：你只是想改几个颜色，还是希望对 Codex 界面进行完整重构？
| 需求 | Codex 原生功能 | CodeDrobe Theme |
|---|---|---|
| 桌面端基础主题、强调色、前景色、背景色 | 支持 | 支持通过主题 baseTheme 管理 |
| UI 字体和代码字体 | 支持 | 可在 CSS 中进一步控制 |
| CLI 代码高亮 | /theme，支持 .tmTheme | 不是主要用途 |
| 背景图、纹理、首页 Hero | 不属于基础外观设置 | 支持命名图片和 CSS |
| DOM 兼容性预检 | 无需 | probe 检查适配器和主题节点 |
| 安装结果截图验证 | 手动观察 | verify --screenshot |
| 一键恢复 | 手动改回 | codedrobe restore |
如果你只是想给 Codex App 改个颜色，最便捷的方法就是打开 Settings > Appearance。如果使用的是 Codex CLI，可以在交互界面运行 /theme；把自定义高亮文件放到 $CODEX_HOME/themes 后，也可以在主题选择器中直接预览效果。
CodeDrobe 的运行结构与要求
codedrobe-theme 的作用，是告诉 Agent 应该如何安全、规范地完成 Codex 换肤；而真正负责执行检测、CDP 连接、打包、应用和恢复操作的，则是 @codedrobe/core 这个 CLI 工具。
截止 2026 年 7 月，官方仓库披露的关键信息如下：
| 数据点 | 官方来源 | 含义 |
|---|---|---|
Core 版本 0.3.0 | @codedrobe/core package.json，2026 年 | 教程按该公开结构核验 |
Node.js 最低 22.4 | Core engines 字段，2026 年 | 版本过低会影响 CLI 运行 |
Codex 默认 CDP 端口 9335 | CodeDrobe Codex reference，2026 年 | 显式 --port 会覆盖默认值 |
每个主题最多 32 张命名图片 | Theme authoring reference，2026 年 | 避免主题包无限膨胀 |
主题包最大 30 MB | Theme authoring reference，2026 年 | 图片需要压缩并随包内嵌 |
CodeDrobe 当前公开支持的目标应用包括 Codex 和 WorkBuddy。项目采用 Apache-2.0 许可证，不过它属于独立项目，并不是 OpenAI 官方出品的组件。
第一步：安装 codedrobe-theme Skill
安装命令使用的是复数形式 npx skills。它的职责只是把对应工作流安装给 Codex Agent，本身并不负责执行主题注入，这一点需要先区分清楚。
先查看仓库中有哪些可安装 Skill：
npx skills add CodeDrobe/skills --list然后把适用于普通用户换肤的 Skill 全局安装到 Codex：
npx skills add CodeDrobe/skills
--skill codedrobe-theme
--global
--agent codex
--yes这里的 --agent codex 表示“由哪个 Agent 接收 Skill”，并不是指定要换肤的桌面应用。真正的目标应用，需要在后续命令中通过 --app codex 来声明。
第二步：安装 Core 并检测 Codex
如果你准备长期使用 CodeDrobe，建议全局安装 Core；如果只是临时体验一次，也可以直接使用 npx --yes @codedrobe/core@latest 来代替 codedrobe 命令。
npm install --global @codedrobe/core
codedrobe --version
codedrobe apps --json
codedrobe detect --app codex --jsonapps --json 用于确认当前支持的应用、默认配置以及最近验证版本；detect 则用于查找实际安装路径。如果你的 Codex 安装位置比较特殊，也可以手动传入路径：
codedrobe detect
--app codex
--app-path "/ABSOLUTE/PATH/TO/Codex.app"
--json这里的路径必须替换成真实的绝对路径。需要特别注意的是：不要为了图省事去修改、替换或重新签名 app.asar、应用程序包或 WindowsApps 文件——那属于完全不同的操作路线。
第三步：让 Skill 创建主题
安装好 Skill 后，直接让 Codex 按照官方工作流创建主题即可，不需要手动猜测应用内部的 DOM 选择器。
一个适合复用的提示词如下：
使用 codedrobe-theme Skill，目标应用设为 codex。
从 assets/theme-starter 复制一份主题源码到当前工作区，
分别采集 Codex 首页和普通任务页面的 DOM 快照，
根据实时快照修正 CSS，打包、预检并生成验证截图。
应用主题前不要关闭或重启正在运行的 Codex；如必须重启，先向我确认。DOM 快照的作用，是帮助你定位真实的语义节点。根据官方说明，这类快照是只读的，并且会排除页面文本、表单值、可访问名称、链接和媒体源。首页与普通会话页面需要分别采集，因为两种页面的 DOM 结构并不相同。
主题源码通常会包含以下文件：
my-theme/
├── theme.json
├── codex.css
└── assets/
├── hero.png
└── texture.png主题 CSS 应尽量限制在 html.codedrobe-host-codex 作用域下，装饰图层则应使用 pointer-events: none，以免遮挡侧边栏、输入框、菜单以及原生导航组件。
第四步：预检、应用并验证主题
在把主题真正应用到 Codex 之前，必须先检查主题包结构以及实时 DOM 兼容性。静态 CSS 能够成功解析，并不代表它一定能兼容当前版本的应用，这恰恰是很多人给 Codex 换主题时最容易忽视的问题。
codedrobe theme inspect "/ABSOLUTE/PATH/my-theme.codedrobe-theme"
codedrobe probe
--app codex
--theme "/ABSOLUTE/PATH/my-theme.codedrobe-theme"
--timeout-ms 5000
codedrobe apply
--app codex
--theme "/ABSOLUTE/PATH/my-theme.codedrobe-theme"
codedrobe verify
--app codex
--theme "/ABSOLUTE/PATH/my-theme.codedrobe-theme"
--screenshot "/ABSOLUTE/PATH/codex-theme-preview.png"probe 只用于预检，不会真正安装主题；verify 会进一步检查主题 ID、版本、样式、命名图片、Renderer Profile、必需节点和横向溢出情况，同时还能导出 PNG 截图用于核验。
验证时至少应重点检查以下几点：
- 首页 Hero、建议卡片、项目选择器和输入框。
- 普通任务页面中的正文、代码块、工具输出、滚动和输入框。
- 页面没有横向溢出，装饰层也不会拦截点击操作。
- 主题 ID、版本号和图片资源与包内清单保持一致。
如果主题中的 baseTheme 修改了 Codex 宿主的外观设置，而应用此时已经在运行，Core 可能会要求加上 --restart-existing。这个参数会关闭并重新启动当前应用，因此只有在你明确接受重启时才应使用。
换肤会不会影响模型和 API 配置
CodeDrobe Core 只会管理 ~/.codex/config.toml 中受控的 [desktop] 外观相关键值，并在自己的状态目录中创建事务式备份，不会去修改模型 Provider 或 API Key 配置。
例如，如果你已经通过七牛云 API Key 配置了 OpenAI-compatible 编程接口，那么在应用主题之后，仍然建议再次检查原有的 model_provider 和鉴权环境变量是否存在。主题系统负责的是界面样式，模型连接与调用配置依旧由 Codex 自身独立管理。
如何恢复原来的 Codex 界面
如果要恢复默认界面，应该优先使用 Core 自带的恢复命令，而不要手动删除 Codex 数据目录或直接覆盖配置文件——这样做的风险明显更高。
codedrobe restore --app codex恢复完成后，建议确认主题样式、根节点 Host Class 和主题数据都已经被移除；如果在应用主题时修改过受管外观键，事务式备份也应已经同步恢复。
常见问题
Q：为什么 codedrobe 命令不存在？
这是因为 Skill 安装器和运行时属于两个不同的包。npx skills 只负责安装工作流，你还需要全局安装 @codedrobe/core，或者将命令改写成 npx --yes @codedrobe/core@latest 。同时还要确认当前 Node.js 版本不低于 22.4。
Q：为什么 probe 提示缺少节点？
如果是 adapter: 缺失，通常表示应用渲染器已经发生变化，或者你选错了 CDP 目标；如果是 theme: 缺失，则说明主题依赖的页面节点结构发生了变化。遇到这种情况，正确做法是重新采集真实 DOM 快照并修复 CSS，而不是静默删除验证要求，否则后续问题会更难定位。
Q：端口 9335 被占用怎么办？
不要直接终止来源不明的进程。更稳妥的方式是选择一个新的本地端口，并在 launch、probe、apply、verify 和 restore 中始终使用同一个 --port。同时，CDP 只应绑定在回环地址上。
Q：Codex 更新后主题失效怎么办？
建议先执行 codedrobe update --check，然后针对新版本重新进行 DOM 快照采集和 probe 检查。主题模板并不是永久有效的 DOM 合约；尤其是依赖首页结构的 CSS，应根据最新快照进行修复，再提升主题版本、重新打包并完成验证。
Q：主题包可以直接从网上下载后应用吗？
主题包应被视为不可信输入。应用之前必须先运行 theme inspect 和 probe；不要允许外部 CSS 资源、脚本或事件处理器，也不要使用伪造整窗截图的覆盖层。对于来源不明、无法审查内容的主题包，最安全的做法就是不要安装。
结论与参考资料
给 Codex 换皮肤，大致可以分为三种层级：桌面端基础外观使用 Settings，CLI 代码高亮使用 /theme，而完整的 CSS 主题与图片主题则需要借助 CodeDrobe。更规范的操作流程是：先安装 Skill 和 Core，再采集实时 DOM、执行预检、应用主题、完成双页面验证，最后保留可用的恢复命令。
根据 OpenAI Codex 官方设置文档以及 CodeDrobe 官方仓库说明，主题能力和页面结构都可能随着应用版本更新而变化。本文内容基于 2026 年 7 月 17 日公开资料整理，实际操作前建议重新运行 codedrobe apps --json，并再次核对当前支持信息。
参考资料：
- CodeDrobe Skills
- CodeDrobe Core
- OpenAI Codex App 设置
- OpenAI Codex CLI 主题