在 codex 养宠物？真的假的？

2026 年 5 月 8 日

2388 字

12 分钟

技术

Codex Pet 启用与制作教程

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

说明

适用场景：你已经在使用 Codex 桌面端或 Codex CLI，希望启用内置 pet，或者制作一个自己的动画 pet 并上传分享。

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 桌面端：

打开 Codex。
进入 Settings。
切到 Appearance。
找到 Pets 区域。
选择你想启用的 pet。
如果界面里有 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 步：

准备 run 目录、名字、描述和 prompt。
生成 base pet，也就是主视觉参考。
基于 base 生成 9 行动作。
合成 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 使用。