Codex 桌宠使用指南
它是什么
Pets 是 OpenAI Codex App（桌面版）里的一个功能：屏幕上有一个透明置顶的小窗口，里面住着一只像素宠物。它不是装饰——动画状态跟 Codex 的运行状态绑定：
- Codex 在生成代码时，宠物进入「工作中」动画，忙得原地发抖；
- Codex 停下来等你输入时，宠物切到「等你回复」，抬头盯着你；
- 任务成功，它起跳庆祝；任务失败，它当场蔫掉、冒冷汗。
不用切窗口，瞟一眼宠物就知道该不该回去看终端了。
怎么用上一只宠物
- 确认装的是 Codex App 桌面版（不是纯 CLI），并在设置里开启 Pets；
- 从图鉴下载任意一只宠物的
.pet.zip； - 解压到 pets 目录，每只宠物一个文件夹：
# macOS / Linux
~/.codex/pets/<宠物id>/
├── pet.json
└── spritesheet.webp (PNG 也可以)
# Windows
%USERPROFILE%\.codex\pets\<宠物id>\放好后在 Codex App 的宠物选择里就能看到新宠物。如果没出现，重启一次 Codex App。
精灵图规格（官方）
宠物的全部动画都在一张图里：1536×1872 像素，PNG 或 WebP，透明背景，切成 8 列 × 9 行，每格 192×208。注意：每行实际使用的帧数不同（这是官方合同 animation-rows.md 明确规定的），行内没用到的格子必须保持全透明。从上到下依次是：
| 行 | 状态 ID | 名称 | 使用帧数 | 循环时长 | 播放时机 |
|---|---|---|---|---|---|
| 0 | idle | 待机 | 6 | 1100ms | 安静呼吸，偶尔眨眼 |
| 1 | running-right | 向右跑 | 8 | 1060ms | Codex 派它去右边干活 |
| 2 | running-left | 向左跑 | 8 | 1060ms | 跑回来的路上 |
| 3 | waving | 打招呼 | 4 | 700ms | 任务开始前先跟你挥挥手 |
| 4 | jumping | 跳跃 | 5 | 840ms | 任务完成，开心起跳 |
| 5 | failed | 失败 | 8 | 1220ms | 出错了，蔫在原地冒冷汗 |
| 6 | waiting | 等你回复 | 6 | 1010ms | Codex 停下来等输入，它盯着你看 |
| 7 | running | 工作中 | 6 | 820ms | Codex 正在生成代码，忙得发抖 |
| 8 | review | 审查 | 6 | 1030ms | 眯起眼睛左右扫视你的代码 |
几条容易踩的规则：
- 整只宠物必须完整待在 192×208 的格子里，跳跃最高点也不能出格；
- 透明就是真透明：不用的像素 alpha 必须为 0 且不能残留 RGB 值，不能画半透明投影、地面阴影、速度线这类“分离特效”（官方 validate_atlas.py 会逐像素检查）；
- 不要在宠物身上画可读的文字或 logo；
- 细节要够大——最终显示尺寸很小，一两个像素的花纹根本看不见。
pet.json 长什么样
{
"id": "momo",
"displayName": "Momo",
"description": "A round cream-orange cat.",
"spritesheetPath": "spritesheet.webp"
}四个字段就够了。id 用小写字母数字，和文件夹名保持一致；spritesheetPath 是相对 pet.json 的路径。
自己做一只
方法一：让 AI 画（官方路线）。OpenAI 在 openai/skills 里提供了 hatch-pet 技能。在 Codex 里装上后描述你想要的角色，它会调用图像生成把 9 行动画一行行画出来，再自动拼成规格精灵图，产物直接落在 ~/.codex/pets/ 里。适合想要精致手绘质感的人。
方法二：用代码逐帧画（本站路线）。本站 91 只宠物全部是 Python + Pillow 程序化生成的：在 24×26 的逻辑网格上用色块画出身体，再按状态给每帧套参数——待机是呼吸起伏加眨眼，跳跃是蹲下、拉伸、腾空、落地的位移曲线，失败是压扁身体加 X 眼和冷汗。最后按官方各行帧数拼成 1536×1872 大图。做到几十只的规模后我们把它抽象成了「配置驱动」：身体形状、配色、耳朵尾巴眼镜围巾都是参数，加一只新宠物只需要写十行配置。
两条路线产物是同一种东西：一张合规精灵图加一个 pet.json。做完把文件夹丢进 pets 目录就能跑。
常见问题
宠物不动或者不出现？先检查目录层级——pet.json 必须直接在 pets/<id>/ 下，不能多套一层解压出来的文件夹；再检查图的尺寸是不是精确的 1536×1872。
V1 和 V2 是什么区别？社区里说的 V2 是在 9 行基础规格之外增加了 16 个朝向的“环顾”帧，让宠物能看向鼠标方向。基础 9 行规格的宠物（包括本站的）在新版 Codex App 里依然完全可用。
本站宠物能拿去改吗？能。91 只全部是原创像素作品（灵感系列参考的只是题材类型，不含受版权保护的角色形象），随便改、随便传播，不需要署名。