codex-pet

Codex Pet — RunComfy Pro 套件

runcomfy.com · GPT Image 2 edit endpoint · 文档

RunComfy 上的 Codex Pet 生成器。 将一张源图像转换为与 Codex 兼容的自定义 Codex Pet — pet.json + spritesheet.webp — 将其放入 ${CODEX_HOME:-$HOME/.codex}/pets/<name>/，Codex 就会与内置的 8 个 Codex Pet 一起识别它。

npx skills add agentspace-so/runcomfy-agent-skills --skill codex-pet -g

什么是 Codex Pet

OpenAI Codex Pets（于 2026 年 5 月发布）是像素艺术动画伙伴，会在 Codex 编码时悬浮在桌面上方 — 它们会响应鼠标交互和 Codex 状态（思考时挠头，任务完成时弹出对话气泡）。Codex 内置了 8 个 Codex Pet，并支持将自定义 Codex Pet 作为文件夹安装在本地的 ${CODEX_HOME:-$HOME/.codex}/pets/ 下。

每个自定义 Codex Pet 文件夹恰好包含两个文件：

• pet.json — 清单，包含 id、displayName、description、spritesheetPath。
• spritesheet.webp — Codex Pet 精灵图集，1536x1872 PNG 或 WebP，8 列 x 9 行，每格为 192x208 像素，背景透明。

9 行分别对应 Codex 播放的 9 种动画状态。每行使用固定数量的起始帧；后续单元格保持完全透明。

为什么选择这个 Codex Pet 技能（而不是 OpenAI 官方的 hatch-pet）

OpenAI 提供了官方的 hatch-pet 技能，它通过 Codex 内部的 $imagegen 系统技能生成相同的 Codex Pet 成品（需要 Codex Pro + 配置 $imagegen）。

这个 Codex Pet 技能是可直接替换的方案，通过 RunComfy CLI 运行：只需一个 RUNCOMFY_TOKEN 以及 runcomfy 和 magick 二进制文件 — 无需 Codex Pro、无需 $imagegen、无需 OPENAI_API_KEY。生成的 Codex Pet 成品完全相同 — pet.json 结构相同，spritesheet.webp 1536x1872 图集相同，9 行动画相同 — 因此 Codex 会将这个 Codex Pet 与通过 hatch-pet 制作的完全一样对待。

此技能沿用 Codex 内置 Codex Pets 的相同模式：制作一个标准姿势，再通过 ImageMagick 微变换将其复制到各个单元格，以实现细微动画（1-2 px 位移、眨眼帧、倾斜帧）。这与官方 hatch-pet 输出逐格呈现的效果一致 — Codex 桌面应用中可见的 Codex Pet 动画本身就刻意设计得很细微。

以下情况适合选择此技能：

• 你想要自定义 Codex Pet，但没有 Codex Pro / $imagegen。
• 你想通过 RunComfy Model API 制作自定义 Codex Pet。
• 你想从一个源图像文件夹批量生成 Codex Pet（每个宠物只需一次标准调用）。
• 你正在参加 OpenAI Codex Pet 大赛，希望使用不同的模型生成视觉效果。
• 你明确说了“codex pet”、“/hatch”、“make me a codex pet”、“spritesheet.webp”或“desktop pet for codex”。

Codex Pet 动画行

Codex 读取一个固定图集：8 列、9 行，每个单元格为 192x208。每一行 Codex Pet 对应一种动画状态，并有特定数量的起始帧。

行	状态	使用的列	帧数	Codex Pet 行为
0	idle	0-5	6	平静地呼吸／眨眼；Codex Pet 在减少动态效果模式下显示的首帧
1	running-right	0-7	8	Codex Pet 向右移动
2	running-left	0-7	8	镜像后的向左移动
3	waving	0-3	4	打招呼／引起注意的动作
4	jumping	0-4	5	蓄势、腾空、到达顶点、下降、落稳
5	failed	0-7	8	出错／难过／泄气的反应
6	waiting	0-5	6	耐心等待时的闲置状态变体
7	running	0-5	6	活跃工作／进行中的循环（不是跑步）
8	review	0-5	6	专注／检查／思考

每行最后一个使用列之后的单元格必须完全透明。

Codex Pet 风格

Codex Pet 的视觉风格：

• 夸张的 Q 版比例：头部约占整个形象高度的 60%；身体和腿都很小、短而敦实。整体形象应适合放入近似正方形的边界框。
• 接近像素艺术的低分辨率吉祥物，轮廓敦实
• 粗重的深色 1-2 px 描边，边缘呈现明显的阶梯状像素效果
• 配色有限、平面赛璐珞阴影、简单生动的面部表情、四肢小巧
• 透明背景

避免：运动线、投影、辉光、闪光、漂浮效果、文字标签、场景、白色／黑色背景。

前置条件

1. RunComfy CLI — npm i -g @runcomfy/cli
2. RunComfy 账号 — runcomfy login。CI 替代方案：RUNCOMFY_TOKEN=<token>。
3. ImageMagick — brew install imagemagick（macOS）或 apt-get install imagemagick（Linux）。提供用于确定性图集组装的 magick 命令。
4. 源图像 URL — 可公开访问的 HTTPS、JPEG/PNG/WebP 图像，作为 Codex Pet 的建模对象。

Codex Pet 流水线（调用 1 次 GPT Image 2，约 2 分钟）

1. 标准 Codex Pet — 单次调用 runcomfy run openai/gpt-image-2/edit，生成一张以洋红色抠像背景呈现的 1024x1024 Q 版姿势图。
2. 单元格规范化 — 将抠像洋红色转换为 alpha 0，裁剪，并在透明留白下按比例适配到 192x208。
3. 9 条行条带，以编程方式生成 — 针对 9 种动画状态中的每一种，使用 ImageMagick 对标准单元格进行微变换（平移／遮罩／镜像）来构建该行的 8 个单元格。末尾单元格填充透明的 192x208 图像。
4. 图集 — 将 9 条行条带垂直堆叠，组成 1536x1872 的 Codex Pet 图集。
5. WebP — 将图集 PNG 转换为 WebP。
6. 清单 + 安装 — 写入 pet.json，并将两个文件复制到 ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/。

微变换方法与 Codex 内置 Codex Pets 的实际实现相符——Codex Pet 的动画刻意设计得很细微，因此每个单元格移动 1-2 px 并使用眨眼遮罩，就能带来恰当的视觉效果，无需消耗 72 次 GPT Image 2 调用。

第 1 步：生成标准 Codex Pet（调用 1 次）

PET_NAME="my-pet"
PET_DESC="A friendly companion for late-night refactors."
SOURCE_URL="https://.../source.png"
RUN_DIR="./codex-pet-run/${PET_NAME}"
CHROMA="#FF00FF"   # magenta chroma-key
mkdir -p "${RUN_DIR}"

runcomfy run openai/gpt-image-2/edit \
  --input "{
    \"prompt\": \"Generate one canonical Codex digital pet sprite based on the input image. EXAGGERATED chibi proportions: the head occupies about 60 percent of the total figure height; body and legs are tiny stubby and short. The whole pet figure must fit within a near-square bounding box (overall aspect close to 1:1). Pixel-art-adjacent low-resolution mascot, chunky whole-body silhouette, thick dark 1-2 px outline, visible stepped pixel edges, limited palette, flat cel shading, simple expressive face, tiny limbs. Centered in the image. No polished illustration, no painterly render, no anime key art, no 3D render, no glossy app-icon polish, no realistic detail. Background: solid flat magenta ${CHROMA} chroma-key fill outside the pet silhouette. The pet itself must not use the chroma-key color or any close-to-magenta highlights. No gradients, no shadows, no halos, no scenery, no text. Identity preserved from the input image.\",
    \"images\": [\"${SOURCE_URL}\"],
    \"size\": \"1024*1024\"
  }" \
  --output-dir "${RUN_DIR}/decoded/"

BASE=$(ls "${RUN_DIR}/decoded/"*.png | head -1)
echo "canonical Codex Pet: ${BASE}"

第 2 步：将标准形象规范化为 192x208 的 Codex Pet 单元格

将抠像洋红色转换为 alpha，裁剪至宠物精灵图的边界框，并在透明留白下按比例适配到 192x208。

magick "${BASE}" \
  -fuzz 18% -transparent "${CHROMA}" \
  -alpha set \
  -trim +repage \
  -resize 192x208 \
  -gravity center \
  -background none \
  -extent 192x208 \
  "${RUN_DIR}/cell.png"

18% 的模糊容差针对 GPT Image 2 的抗锯齿洋红色边缘进行了调优。如果 Codex Pet 周围的洋红色光晕较宽，可调整为 25%；如果宠物带有接近洋红色的高光并被裁掉，则可调整为 8-10%。

第 3 步：以编程方式构建 9 条 Codex Pet 行条带

对于每一行，使用 ImageMagick 对标准形象进行微变换，构建 8 个单元格；未使用的末尾单元格填充为透明，然后拼接成 1536x208 的行条带。

SRC="${RUN_DIR}/cell.png"
mkdir -p "${RUN_DIR}/cells"

# Helpers
shift_cell() { magick "$SRC" -background none -roll "+${1}+${2}" -alpha set "$3"; }
rotate_cell() { magick "$SRC" -background none -distort SRT "$1" -alpha set "$2"; }
make_blink() {
  # Eyes are roughly at y=80-100 in a 208-tall cell.
  # Soften with a skin-tone overlay across that horizontal band.
  magick "$SRC" \
    -region 80x6+56+82 -fill "#f4e6d8" -colorize 70% -blur 0x0.5 +region "$1"
}
blank_cell() { magick -size 192x208 xc:none -alpha set "PNG32:$1"; }

build_row() {
  local row=$1; shift
  local i=0
  for spec in "$@"; do
    local out="${RUN_DIR}/cells/row${row}-frame${i}.png"
    case "$spec" in
      base)      cp "$SRC" "$out" ;;
      blink)     make_blink "$out" ;;
      shift:*)   IFS=':' read -r _ x y <<< "$spec"; shift_cell "$x" "$y" "$out" ;;
      rotate:*)  IFS=':' read -r _ ang <<< "$spec"; rotate_cell "$ang" "$out" ;;
    esac
    i=$((i+1))
  done
  while [ "$i" -lt 8 ]; do
    blank_cell "${RUN_DIR}/cells/row${row}-frame${i}.png"
    i=$((i+1))
  done
  magick "${RUN_DIR}/cells/row${row}-frame"*.png +append -alpha set \
    "${RUN_DIR}/cells/row${row}-strip.png"
}

# 9 Codex Pet rows with their per-frame micro-transforms
build_row 0 base base blink base base blink                                       # idle (6)
build_row 1 base shift:1:0 shift:2:-1 shift:1:0 base shift:-1:0 shift:-2:-1 shift:-1:0  # running-right (8)
# row 2 = running-left = horizontal flip of row 1, built below
build_row 3 base shift:0:-1 base shift:0:-1                                       # waving (4)
build_row 4 shift:0:2 base shift:0:-8 shift:0:-2 base                              # jumping (5) — vertical arc
build_row 5 base shift:0:1 rotate:1 shift:0:1 shift:0:2 shift:0:1 rotate:-1 base  # failed (8)
build_row 6 base base shift:0:-1 base base shift:0:1                              # waiting (6)
build_row 7 base shift:0:-1 base shift:0:-1 base shift:0:-1                       # running (6)
build_row 8 base rotate:-2 base rotate:2 base base                                # review (6)

# Row 2: running-left = mirror of running-right
magick "${RUN_DIR}/cells/row1-strip.png" -flop -alpha set "${RUN_DIR}/cells/row2-strip.png"

微变换表让 Codex Pet 在 Codex 中呈现清晰而细微的动态效果。可根据喜好调整每一行的数值；这些差值刻意设得很小（1-2 px），让 Codex Pet 显得生动又不会喧宾夺主。

步骤 4：合成 Codex Pet 图集

将 9 条行带垂直堆叠为 1536x1872 的 Codex Pet 图集，然后转换为 WebP。

magick \
  "${RUN_DIR}/cells/row0-strip.png" \
  "${RUN_DIR}/cells/row1-strip.png" \
  "${RUN_DIR}/cells/row2-strip.png" \
  "${RUN_DIR}/cells/row3-strip.png" \
  "${RUN_DIR}/cells/row4-strip.png" \
  "${RUN_DIR}/cells/row5-strip.png" \
  "${RUN_DIR}/cells/row6-strip.png" \
  "${RUN_DIR}/cells/row7-strip.png" \
  "${RUN_DIR}/cells/row8-strip.png" \
  -append -alpha set "${RUN_DIR}/spritesheet.png"

magick "${RUN_DIR}/spritesheet.png" "${RUN_DIR}/spritesheet.webp"

步骤 5：编写 Codex Pet 清单

cat > "${RUN_DIR}/pet.json" <<EOF
{
  "id": "${PET_NAME}",
  "displayName": "${PET_NAME}",
  "description": "${PET_DESC}",
  "spritesheetPath": "spritesheet.webp"
}
EOF

步骤 6：安装 Codex Pet

DEST="${CODEX_HOME:-$HOME/.codex}/pets/${PET_NAME}"
mkdir -p "${DEST}"
cp "${RUN_DIR}/pet.json" "${RUN_DIR}/spritesheet.webp" "${DEST}/"
echo "Codex Pet installed at ${DEST}"

重启 Codex（或重新加载宠物列表），自定义 Codex Pet 就会出现在 8 个内置宠物旁边。

为经典 Codex Pet 编写提示词——有效方法

单次 GPT Image 2 调用决定一切。把提示词写好，后续步骤就都是确定性的。

首先锁定 Q 版比例。“夸张的 Q 版比例，头部约占人物高度的 60%”是纤细高挑的角色（在 192x208 单元格中会因两侧留白而显得不协调）与头部占主导、能自然填满单元格的 Q 版角色之间的区别。后者才是 Codex 内置 Codex Pet 的样子。

**在每个 Codex Pet 基础提示词中明确要求洋红色 #FF00FF 色度键背景。**GPT Image 2 只会输出 RGB（不含 alpha），因此要获得透明的 Codex Pet，唯一方法是后处理时通过色度键移除指定背景色。

**禁止宠物本身使用色度键颜色。**添加：“宠物本身不得使用色度键颜色，也不得使用任何接近洋红色的高光。”否则，色度键处理会移除 Codex Pet 身上恰好呈洋红色的部分。

固定风格。“像素艺术风格、粗犷的轮廓、1-2 px 描边、有限调色板、平涂赛璐璐阴影”——固定所有能让 Codex Pet 符合 Codex 整体风格的要素。

禁止不合适的风格。“不要精致插画，不要绘画质感渲染，不要动漫主视觉图，不要 3D 渲染，不要有光泽的应用图标质感，不要写实细节。”如果不这样限定，GPT Image 2 往往会生成过度渲染的动漫艺术风格。

反面模式：

• 只写笼统的“透明背景”——GPT Image 2 会绘制近白色背景。应使用色度键。
• 任由模型自由发挥比例——它会画出高而窄的 Q 版角色，无法适配 192x208。
• 在一个提示词中混合多种风格——固定一种风格锚点并始终保持一致。

调整微动画

步骤 3 中默认的 ImageMagick 配方会生成类似内置 Codex Pet 的动画——轻微上下浮动、偶尔眨眼、跳跃弧线、头部倾斜。要让动画更明显或更不明显，可以调整偏移量：

• 加大待机浮动幅度：在第 0 行将 shift:0:-1 改为 shift:0:-2。
• 加快跑步循环：增加第 1 行的水平偏移（例如使用 shift:3:0 而不是 shift:2:-1）。
• 跳得更高：将第 4 行的峰值从 shift:0:-8 改为 shift:0:-12。
• 让检查时的头部倾斜更明显：将 rotate:-2 / rotate:2 改为 rotate:-4 / rotate:4。

偏移量应保持较小（≤ 4 px 或 ≤ 4°），以免 Codex Pet 变得分散注意力。

FAQ — Codex 宠物

什么是 Codex 宠物？ OpenAI Codex Pets 是于 2026 年 5 月推出的像素艺术动画伙伴，会悬浮在桌面上，并根据 Codex 的编码状态做出反应。自定义 Codex Pets 以 pet.json + spritesheet.webp 文件的形式存放在 ${CODEX_HOME:-$HOME/.codex}/pets/<name>/ 下。

为什么使用这个 Codex Pet 技能，而不是 hatch-pet？ 官方的 hatch-pet 需要 Codex 内部的 $imagegen 系统技能（Codex Pro）。此技能只需要 RUNCOMFY_TOKEN，并通过 RunComfy CLI 使用相同的动画行规格，总共只需调用一次 GPT Image 2。

生成一个 Codex 宠物需要多久？ 约 2 分钟——一次 GPT Image 2 编辑调用（约 90 秒），再加上几秒钟的 ImageMagick 图集拼装时间。

为什么只调用一次 API？ Codex 桌面应用中的 Codex 宠物动画刻意做得很细微（检查任意内置 Codex 宠物的图集即可确认：其中 72 个单元的姿势几乎相同，只有微小变化）。一个标准姿势加上确定性的 ImageMagick 微变换，就能产生相同的动画效果，无需耗费 72 次单独的生成调用。

Codex 宠物技能可以使用非人类主体吗？ 可以——宠物、吉祥物、物品和食物都适用。基础提示词会自动将来源简化为 Codex 宠物的风格。

如何安装我的 Codex 宠物？ 将 pet.json 和 spritesheet.webp 复制到 ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/，然后重新加载 Codex。

如果标准 Codex 宠物的形象发生偏移，该怎么办？ 使用更严格的身份保留提示词重新运行步骤 1（例如，具体说明头发颜色、眼镜和配饰等特征）。步骤 2–6 是确定性的，无需更改。

每帧 Codex 宠物的尺寸是多少？ 192x208 px。每行条带为 1536x208（8 帧）。最终的 Codex 宠物图集为 1536x1872（9 行堆叠）。

可以添加自定义姿势或替换行吗？ 可以——修改步骤 3 中的 build_row 调用。每行的图集槽位数量必须符合 Codex 规范（idle=6、running-right/left=8、waving=4、jumping=5、failed=8、waiting/running/review=6），这样 Codex 才能正确播放。

限制

• 每个 Codex 宠物只有一个标准姿势——动画通过 ImageMagick 变换实现，而非多帧模型生成。这与内置 Codex Pets 的细微动画相符，但无法生成大幅度动作（例如逐帧各异的跑步循环）。
• GPT Image 2 不会输出 alpha 通道——洋红色彩度键 + 后处理是一种变通方案。如果 Codex 宠物含有接近洋红色的颜色（在 Q 版调色板中较少见），请在提示词和后处理中将彩度键改为其他纯色（#00FFFF 青色或 #00FF00 绿色）。
• 形象偏移——GPT Image 2 可能会将源图像的形象简化为 Codex 宠物风格；某些具体的小特征（例如耳环、道具颜色）可能会发生变化。
• Codex 宠物没有音频或语音——Codex Pets 仅包含视觉效果。

退出代码

runcomfy CLI 使用 sysexits 风格的代码：

code	meaning
0	成功生成 Codex 宠物标准形象
64	CLI 参数错误
65	Codex 宠物调用的输入 JSON 错误 / 架构不匹配（例如，size: "1024_1024" 而不是 "1024*1024"）
69	上游 5xx 错误
75	可重试：超时 / 429
77	未登录或令牌被拒绝

magick（ImageMagick）成功生成 Codex 宠物图集时返回 0；返回非零值表示缺少输入帧或输出路径权限有问题。

完整参考：docs.runcomfy.com/cli/troubleshooting。

工作原理

1. 该技能使用用户提供的源图像和精简的 Chibi 比例提示词调用一次 runcomfy run openai/gpt-image-2/edit，生成一张背景为洋红色、尺寸为 1024x1024 的标准 Codex Pet。
2. ImageMagick 使用色度键将洋红色转换为 alpha 0，裁剪精灵图边界框，并将图像按比例适配到 192x208 的单元格中。
3. ImageMagick 通过对标准单元格应用微变换（平移 1-2 px、眨眼蒙版、旋转、镜像），以编程方式构建 9 条行条带。
4. 将 9 条行条带堆叠成 1536x1872 的 Codex Pet 图集；再将图集转换为 WebP。
5. 写入 pet.json 清单；然后将这两个文件复制到 ${CODEX_HOME:-$HOME/.codex}/pets/<name>/，Codex 会自动加载自定义 Codex Pet。

鸣谢

9 行 Codex Pet 图集规范——包括列数、帧数和单元格尺寸——来自 OpenAI 官方的 hatch-pet 技能（采用 MIT 许可证）。其中记录了动画行约定和色度键策略。此技能沿用该规范，但替换了视觉生成器（$imagegen → RunComfy GPT Image 2）和图集拼接方式（Python → ImageMagick），因此无需 Codex Pro 即可运行。

此技能不是什么

它不是 Codex 客户端。如果 $imagegen 可用，它也不能替代 hatch-pet——使用 Codex Pro 时，官方 hatch-pet 更合适。它不是可自托管的 GPT Image 2——运行需要可用的 RunComfy 账户。

安全与隐私

• 令牌存储：runcomfy login 会将 API 令牌写入 ~/.config/runcomfy/token.json，文件权限为 0600。在 CI 中设置 RUNCOMFY_TOKEN 环境变量即可绕过该文件。
• 输入边界：Codex Pet 提示词会通过 --input 以 JSON 形式传递。该 CLI 不会进行 shell 展开，因此不存在 shell 注入攻击面。
• 第三方内容：源图像 URL 由 RunComfy 服务获取。请将外部 URL 视为不可信内容——对于任何图像编辑模型，基于图像的提示词注入都是已知风险。
• 出站端点：仅限 model-api.runcomfy.net 和 *.runcomfy.net / *.runcomfy.com。
• 生成文件大小上限：若单个 Codex Pet 标准图像的下载大小超过 2 GiB，CLI 会中止操作。
• 本地安装路径：最终的 Codex Pet 会写入 ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/。不会上传到远程位置。