桌宠目录结构全解剖：~/.codex/pets 里到底有什么

.codex pets 目录在哪

每只装上的桌宠最后都落在同一个地方。macOS 和 Linux 是 ~/.codex/pets，Windows 是 %USERPROFILE%\.codex\pets。Codex 启动时读一次这个 .codex pets 目录，把它下面每一层子目录当成一只桌宠，磁盘上别处的文件它一概不看。

这一条规则能解释大部分「装上了却不显示」。Codex 不递归扫描，放在 ~/.codex/pets/cats/mochi 里的桌宠永远加载不出来，同样这个目录挪到 ~/.codex/pets/mochi 就正常了。

pets 目录布局一览

pets 目录布局是刻意做成平的：只有一层子目录，每个子目录里两三个文件，父目录里除这些子目录之外不放别的。

• ~/.codex/pets/：父目录，只放桌宠子目录
• <pet-id>/：一只桌宠，目录名就是 Codex 内部用的 id
• spritesheet.webp：1536×1872，九个动画状态各八帧
• pet.json：显示名、帧数、时序，不含图像数据也不含颜色
• 多出来的东西（比如你上传的原图）Codex 会跳过，留着也不会出事

一个 codex 桌宠子目录里有什么

打开任意一个子目录，里面永远是那一小套文件。生成器把它们打成一个包，这也是为什么下载完直接把目录挪到别处照样能用。

• spritesheet.webp：像素本体，九行对应九个状态，每行八帧
• pet.json：四十来行元数据，id、显示名、每个状态的时序
• 预览图或 readme：有些生成器会带，Codex 直接忽略
• 别把这俩拆开：精灵图没有对应的 pet.json 就渲染不出任何东西

pet.json 是唯一值得打开的文件

它短到能一口气读完，实际用得上的只有两个字段。

id 必须和目录名一致。两者对不上时 Codex 照样加载，但选择器里显示的名字不是你设的那个。displayName 是选择器里的标签，也是唯一能随手改而不会出事的字段。

• id：必须等于目录名，查表时用它
• displayName：选择器里显示的名字，可以改
• states：九个条目，各自带帧数和毫秒级时长
• 一个颜色字段都没有：改 pet.json 永远改不动桌宠的颜色

哪些能手改，哪些不能

手改这件事，只有很短的一份清单是安全的，清单之外的都别碰。

• 可以：改 displayName、删掉整个子目录卸载、把子目录拷到另一台机器
• 可以：备份压缩包放在父目录里，但别塞进桌宠子目录
• 不可以：改 spritesheet.webp 的尺寸，尺寸是约定好的一部分，见 /blog/spritesheet-dimensions
• 不可以：改帧数，除非你连帧一起重画
• 不可以：在这里改颜色。颜色在像素里，换配色得去 codexpetgenerator.com 重新生成

把目录收拾干净

目录越朴素，意外越少。一只桌宠一个子目录，不嵌套，id 不重复，备份放在目录外面。

下一只桌宠去 codexpetgenerator.com 生成，把目录拖进 ~/.codex/pets 就完事。终端安装步骤在 /blog/install-codex-pet-terminal，备份做法在 /blog/backup-codex-pets-guide，套餐次数看 /pricing。