在 macOS 安装 Codex Dream Skin

支持与要求

• Apple Silicon 或 Intel Mac
• 已安装并至少启动过一次官方 Codex 桌面端
• 本机存在 ~/.codex/config.toml
• 不需要另外安装全局 Node.js

获取第三方工具

打开原始仓库的 macos 目录，检查源码，并按照上游当时列出的获取方式操作；不要使用来历不明的下载镜像。

安装 Dream Skin

在 Finder 双击 Install Codex Dream Skin.command。下面的源码命令可以只安装而不立即启动。

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

启动与定制

使用 Codex Dream Skin.command 启动或重新应用主题；使用 Codex Dream Skin - Customize.command 通过 Finder 选择图片。

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

验证结果

双击 Codex Dream Skin - Verify.command，并检查主页和普通任务页，确认原生侧栏、项目选择、输入框和任务内容仍可使用。

~/.codex/codex-dream-skin-studio/scripts/doctor-macos.sh

背景图片建议

• 支持 PNG、JPEG、HEIC、TIFF 和 WebP
• 源文件不超过 50 MB
• 处理后文件不超过 16 MB
• 建议使用宽度至少 2000px 的横图
• 左侧尽量简洁，为原生主页标题留出空间

恢复 Codex

双击 Codex Dream Skin - Restore.command。恢复流程只停止记录的主题辅助进程和匹配的主题 Codex 会话，然后重新打开官方应用。

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

可选菜单栏

使用 SwiftBar 时可以安装菜单栏命令，用于应用、暂停和更换图片。

./Install\ Menu\ Bar.command

编辑复核说明

本教程把仓库文件组织成可审查的操作路径，不提供签名软件包、下载镜像或长期兼容承诺。开始前先确认官方 Codex 应用能够独立打开，然后检查当前仓库内容与提交历史。.command 文件只是脚本的 Finder 入口，看到图标并不代表可信；应继续查看它实际调用的 shell 脚本、写入位置和恢复入口。

区分 Apple Silicon、Intel 与权限问题

Apple Silicon 与 Intel 使用不同处理器架构，从 Finder 和 Terminal 启动的 shell 也可能继承不同 PATH。请使用上游针对自身架构的当前流程，命令失败时不要随意换入陌生二进制。上游文档说明 macOS 流程不要求额外安装全局 Node.js，因此若另一个域名要求下载随机运行时，需要再次核验。安装辅助层前，应确认官方应用位置，并至少正常启动一次，使基础配置处于可预期状态。

浏览器下载的文件可能带有 quarantine 标记。先检查仓库所有者、源码和文件内容，再决定是否使用系统提供的仍要打开。优先采用针对单个已审查文件的最小授权，不要关闭 Gatekeeper，也不要授予不相关的完全磁盘、通讯录、照片、麦克风、辅助功能或管理员权限。视觉流程只应访问源码明确说明的路径和进程。

安装前阅读完整 macOS 生命周期

• 查看安装脚本将创建的用户级目录，再双击 Install Codex Dream Skin.command。
• 沿着 Codex Dream Skin.command 查看调用脚本，确认本机连接和目标选择符合仓库解释。
• 选择个人照片前，检查 Customize 启动器和图片处理脚本。
• 提前阅读 Verify、doctor-macos.sh 和 Restore，避免出错后才寻找恢复方法。
• 检查近期 Issue 中的架构、权限和当前 Codex 兼容报告，不要根据旧截图推断支持。

在验证启动与恢复前保留下载的源码目录，它是本次所用脚本的稳定参考。如果之后更新仓库，先审查差异，避免让新启动器读取旧安装状态。可复现环境应具有明确的源码提交、官方应用状态和脱敏诊断输出，而不是只有一次成功双击。

不要只看壁纸：验证完整 Mac 体验

应用主题后运行 doctor 或 Verify，再手动检查首页、项目选择、长任务、代码块、链接、菜单、底部输入框、窗口缩放和日常使用的基础明暗外观。空白窗口中好看的背景，可能让密集任务历史难以阅读。应根据构图指南保留低细节区域，避免把主体或关键图形放到底部输入框附近。

• 确认官方 Codex 身份和普通启动路径仍能在没有辅助层时工作。
• 确认键盘导航、选择、复制、滚动、链接和输入框控件保持原生可用。
• 同时检查 Finder 选择图片在超宽首页和任务页裁切中的结果。
• 保存 doctor 输出，但不要公开任务内容、用户名、主目录、令牌或账户信息。
• 执行 Codex Dream Skin - Restore.command，并在把安装视为完成前确认普通外观返回。

排查权限、更新与陈旧状态

启动器一闪而过时，可在 Terminal 运行已经审查过的对应脚本，以便阅读输出。应区分 shell 执行权限、Gatekeeper quarantine、官方应用缺失、图片格式或大小、本机端口冲突和渲染兼容变化；它们需要不同处理。不要用递归增加执行权限，或移除整个目录树的隔离属性来统一修复。

Codex 更新后先恢复，并确认官方应用健康；比较上游变更，只重新运行当前文档要求的安装或启动阶段。如果主题只在一个页面出现，记录页面、窗口尺寸和基础外观。图片处理失败时，先用一份尺寸适中的 PNG 或 JPEG 副本测试，避免修改原始照片，并借此把格式问题与运行时样式问题分开。

• 提交上游问题时提供 Mac 型号类别、处理器架构、macOS 版本、启动器、源码提交和脱敏 doctor 输出。
• 说明恢复后官方应用能否启动，以及问题是否出现在 Codex、macOS 或项目更新之后。
• 不要上传私人背景或包含任务内容的截图，除非必要并完成授权与脱敏。
• 文档问题反馈给 CodexSkin，运行行为反馈给上方链接的上游仓库。