在 codex 养宠物？真的假的？

本文整理了在 Codex 中启用 pet、安装自定义 pet、以及从一张参考图制作属于自己的 pet 的完整流程。示例以本仓库的 FleetSnowfluff 为准。

1. 先理解几个概念

1.1 Codex pet 是什么

Codex pet 是一个会随工作状态变化的小型动画伙伴。一个可安装的 pet 通常是一个本地文件夹，里面至少包含：

<pet-id>/
  pet.json
  spritesheet.webp

pet.json 负责描述名字、ID、说明和 spritesheet 文件路径；spritesheet.webp 是动画图集。

本仓库的最终安装包是：

~/.codex/pets/fleetsnowfluff/
  pet.json
  spritesheet.webp

1.2 hatch-pet skill 和 pet 包不是同一个东西

• hatch-pet 是用于“制作 pet”的 Codex Skill。
• ~/.codex/pets/<pet-id>/ 是 Codex 最终读取的“pet 成品包”。

也就是说，别人给你一个已经做好的 pet 包时，你不需要安装 hatch-pet

只有自己从图片或 prompt 生成 pet 时才需要 hatch-pet

2. 如何在 Codex 中启用 pet

2.1 启用内置 pet

在 Codex 桌面端：

1. 打开 Codex。
2. 进入 Settings。
3. 切到 Appearance。
4. 找到 Pets 区域。
5. 选择你想启用的 pet。
6. 如果界面里有 Tuck Away Pet，可以用它暂时隐藏 pet。

也支持在 Codex 会话里使用：

/pet

如果你看不到 pet 选择器，先更新 Codex，再重启应用。

2.2 启用自定义 pet

把 pet 包放到本机 Codex pets 目录。

macOS / Linux：

mkdir -p "$HOME/.codex/pets/fleetsnowfluff"
cp pet.json spritesheet.webp "$HOME/.codex/pets/fleetsnowfluff/"

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\pets\fleetsnowfluff"
Copy-Item .\pet.json, .\spritesheet.webp "$env:USERPROFILE\.codex\pets\fleetsnowfluff\"

然后重启 Codex，回到：

Settings -> Appearance -> Pets

选择 FleetSnowfluff。

3. 自定义 pet 的文件规范

3.1 最小 pet.json

{
  "id": "fleetsnowfluff",
  "displayName": "FleetSnowfluff",
  "description": "A tiny pink-haired chibi coder sprite with oversized sunglasses, white-blue outfit, and small attached wings.",
  "spritesheetPath": "spritesheet.webp"
}

注意：

• id 建议使用小写字母、数字和连字符。
• 文件夹名最好和 id 一致。
• displayName 是界面显示名，可以保留大小写。
• spritesheetPath 通常指向同目录下的 spritesheet.webp。

3.2 spritesheet 图集规格

hatch-pet 工作流使用固定 atlas：

尺寸：1536 x 1872
网格：8 列 x 9 行
单格：192 x 208
格式：WebP 或 PNG，必须支持透明背景

9 行状态如下：

行	状态	帧数	用途
0	idle	6	待机、呼吸、眨眼
1	running-right	8	向右移动
2	running-left	8	向左移动
3	waving	4	挥手
4	jumping	5	跳跃
5	failed	8	失败或沮丧
6	waiting	6	等待
7	running	6	任务进行中
8	review	6	检查或 review

未使用的格子必须是透明的。

4. 如何制作一个属于自己的 pet：hatch-pet

如果你还没有安装 hatch-pet，在 Codex 中输入：

$skill-installer hatch-pet

安装后重启 Codex。

如果需要手动安装 curated skill，可以参考 OpenAI skills 仓库中的安装方式：

python "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo openai/skills \
  --path skills/.curated/hatch-pet

通常不需要自己手动跑这条命令，直接在 Codex 里用 $skill-installer hatch-pet 更方便。

5. 从参考图制作自己的 pet

5.1 准备参考图

参考图可以是：

• 角色头像
• 像素角色
• 吉祥物
• 截图
• logo 或草图

图片越清楚，生成结果越稳定。最好提前决定：

• pet 名字
• 要保留的核心特征
• 是否有必须保留的配件或身体结构
• 哪些东西不要生成

我们制作 FleetSnowfluff 时，参考图里最重要的特征是：

• 粉色短发
• 黑色大墨镜
• 白蓝色未来感服装
• 小型靴子
• 身体两侧的白蓝色翅膀

5.2 推荐 prompt 写法

可以这样要求 Codex：

使用 $hatch-pet，参考这张图片制作一个 Codex pet。
名字：FleetSnowfluff
必须保留：粉色短发、黑色墨镜、白蓝色衣服、白蓝色翅膀。
风格：Codex digital pet，像素感、小体型、粗轮廓、透明背景。
不要：文字、背景、阴影、漂浮装饰、音乐符号、散落星星。
完成后生成 pet.json、spritesheet.webp、QA contact sheet 和预览视频。

重点是把“必须保留”和“不要生成”写清楚。

5.3 正常生成流程

hatch-pet 的流程可以理解为 4 步：

1. 准备 run 目录、名字、描述和 prompt。
2. 生成 base pet，也就是主视觉参考。
3. 基于 base 生成 9 行动作。
4. 合成 spritesheet，做 QA，打包到 ~/.codex/pets/<pet-id>/。

我们当时的进度可以对应成：

Getting FleetSnowfluff ready.
Imagining FleetSnowfluff's main look.
Picturing FleetSnowfluff's poses.
Hatching FleetSnowfluff.

5.4 为什么要先确认 base

base 是后续所有动作行的身份锚点。base 错了，动作行通常也会错。

检查 base 时要看：

• 角色是不是完整全身。
• 核心特征是否保留。
• 是否有干净的纯色 chroma-key 背景。
• 是否有文字、阴影、漂浮装饰等不应出现的内容。
• 是否适合缩成 192x208 的小格子。

FleetSnowfluff 的第一次 base 没有翅膀，所以必须重做；第二次 base 保留了翅膀，才继续动作行生成。

6. 动作行生成要点

6.1 用子代理并行生成

hatch-pet 适合把动作行交给子代理并行生成。这样每个子代理只负责一个状态：

idle
running-right
running-left
waving
jumping
failed
waiting
running
review

父会话只负责：

• 记录生成结果
• 决定是否镜像 running-left
• 运行最终合成
• 检查 QA
• 打包 pet

这样可以避免多个代理同时改 imagegen-jobs.json 造成冲突。

6.2 不要随便镜像 running-left

有些 pet 可以用 running-right 水平镜像得到 running-left。但如果角色有非对称特征，就不要镜像。

FleetSnowfluff 有蓝色发夹、墨镜渐变和侧向翅膀细节，所以我们没有镜像，而是单独生成了 running-left。

判断标准：

• 有单侧发夹、徽标、文字、单边武器时，不镜像。
• 有方向性光照或手持道具时，不镜像。
• 左右完全对称的小动物，可以考虑镜像。

6.3 每行常见规则

• idle：只做轻微呼吸、眨眼、上下浮动。
• waving：只通过手部姿势表达挥手，不要画波浪线。
• jumping：只用身体位置表达跳跃，不要画地面阴影或落地烟尘。
• failed：可以有贴着身体的小眼泪或烟雾，但不要漂浮红叉、符号。
• waiting：安静等待，不要新增复杂道具。
• running：表示任务进行中，不是字面意义跑步。
• review：用身体前倾、头部角度或手部姿态表达专注，不要加代码窗口或纸张。

7. QA 与验证

生成完成后，至少检查这些文件：

qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/*.mp4

本仓库的 QA 文件：

qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/

7.1 contact sheet 看什么

人工检查 contact sheet：

• 每一行状态是否正确。
• 每个状态的帧数是否正确。
• 角色身份是否一致。
• 翅膀、发型、墨镜、衣服是否保持一致。
• 有没有白底、阴影、漂浮杂物、裁切、空帧。

7.2 JSON 验证看什么

validation.json 应该没有：

"errors": []

最好也没有：

"warnings": []

review.json 应该显示每一行 ok: true。

7.3 预览视频

如果安装了 ffmpeg，可以生成每个状态的 mp4 预览。

如果 ffmpeg 不存在，spritesheet 和 pet 包仍然可以生成，只是没有视频预览。我们制作 FleetSnowfluff 时就先遇到了这个问题，安装 ffmpeg 后再补生成了：

qa/videos/idle.mp4
qa/videos/running-right.mp4
qa/videos/running-left.mp4
qa/videos/waving.mp4
qa/videos/jumping.mp4
qa/videos/failed.mp4
qa/videos/waiting.mp4
qa/videos/running.mp4
qa/videos/review.mp4

8. 重命名 pet 的正确方式

只改 displayName 不够。应该同步：

~/.codex/pets/<pet-id>/
pet.json
run metadata
README / docs
QA summary
Git 仓库目录

以 FleetSnowfluff 为例：

{
  "id": "fleetsnowfluff",
  "displayName": "FleetSnowfluff",
  "spritesheetPath": "spritesheet.webp"
}

同时目录应该是：

~/.codex/pets/fleetsnowfluff

如果你保留了生成 run 目录，也建议把旧名字全局替换，避免后续上传或二次维护时混乱。

检查残留名称：

rg -n "OldName|oldname" .

9. 打包成可上传仓库

建议最终仓库结构：

my-pet/
  README.md
  pet.json
  spritesheet.webp
  qa/
    contact-sheet.png
    reports/
      review.json
      validation.json
    videos/
      idle.mp4
      running-right.mp4
      running-left.mp4
      waving.mp4
      jumping.mp4
      failed.mp4
      waiting.mp4
      running.mp4
      review.mp4

初始化 git：

git init
git add .
git commit -m "Add FleetSnowfluff Codex pet"

上传到 GitHub：

git remote add origin git@github.com:<user>/<repo>.git
git push -u origin main

如果你用 HTTPS：

git remote add origin https://github.com/<user>/<repo>.git
git push -u origin main

10. 常见问题

pet 没出现在 Codex 里

检查：

• 是否放在 ~/.codex/pets/<pet-id>/。
• 是否有 pet.json 和 spritesheet.webp。
• pet.json 里的 spritesheetPath 是否正确。
• id 是否和目录名一致。
• 是否重启了 Codex。

pet 出现白底或背景残留

通常是透明背景处理失败。应重新生成或修复对应动作行，确保：

• 背景是纯 chroma-key 色。
• 不要阴影、渐变、光晕。
• 不要把背景色用在角色本体上。

某一行动作坏了

不要重做整只 pet。只修复失败行：

queue repair -> regenerate that row -> record result -> finalize again

动作中角色变样了

这是 identity drift。修复时要把 base、原图、contact sheet 和失败说明都作为 grounding context，要求只重做失败行。

想保留某个细节

必须在 base 生成前说明。比如 FleetSnowfluff 的翅膀就是必须保留项：

必须保留白蓝色翅膀；翅膀是身体轮廓的一部分，不是漂浮装饰。

11. 一份可直接复制的制作请求

使用 $hatch-pet 帮我制作一个 Codex pet。

名字：<YourPetName>
参考图：见附件
必须保留：
- <核心特征 1>
- <核心特征 2>
- <核心特征 3>

风格：
- Codex digital pet
- pixel-art-adjacent
- 小体型 chibi 比例
- 粗深色轮廓
- 透明背景
- 平面赛璐璐阴影

不要：
- 文字
- 背景
- 阴影
- 漂浮装饰
- 波浪线
- 速度线
- 粒子特效

请生成：
- pet.json
- spritesheet.webp
- QA contact sheet
- 每个状态的预览视频

如果某一步失败，只重试失败的行，不要重做整只 pet。
完成后整理为一个 git 仓库，方便上传。

12. 本仓库的 FleetSnowfluff 成品

pet.json
spritesheet.webp
qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/*.mp4

安装路径示例：

~/.codex/pets/fleetsnowfluff

当前仓库可直接上传，也可直接复制到 ~/.codex/pets/fleetsnowfluff 使用。

参考资料

• OpenAI Codex docs
• OpenAI Codex product page
• OpenAI Agent Skills docs
• openai/skills repository
• openai/skills curated hatch-pet directory