codex-pet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Pet — Pro Pack on RunComfy

Codex Pet — RunComfy专业工具包

runcomfy.com · GPT Image 2 edit endpoint · docs

Codex Pet generator on RunComfy. Turn one source image into a Codex-compatible custom Codex Pet —

pet.json

spritesheet.webp

— drop it into

${CODEX_HOME:-$HOME/.codex}/pets/<name>/

, Codex picks it up next to the 8 built-in Codex Pets.

bash

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

runcomfy.com · GPT Image 2 edit endpoint · docs

RunComfy上的Codex Pet生成工具。将一张源图片转换为与Codex兼容的自定义Codex Pet资源包——

pet.json

spritesheet.webp

——将其放入

${CODEX_HOME:-$HOME/.codex}/pets/<name>/

目录，Codex就会将其与内置的8款Codex Pet并列识别。

bash

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

What a Codex Pet is

什么是Codex Pet

OpenAI Codex Pets (released May 2026) are pixel-art animated companions that float over your desktop while Codex codes — they react to mouse interaction and Codex status (scratching head when thinking, popping a speech bubble when a task completes). Codex ships with 8 built-in Codex Pets and supports custom Codex Pets installed locally as a folder under

${CODEX_HOME:-$HOME/.codex}/pets/

Each custom Codex Pet folder contains exactly two files:

pet.json

— manifest with

id

displayName

description

spritesheetPath

```
spritesheet.webp
```
— Codex Pet sprite atlas, 1536x1872 PNG or WebP, 8 columns x 9 rows of 192x208 cells, transparent background.

The 9 rows correspond to 9 animation states Codex plays. Each row uses a fixed number of leading frames; trailing cells stay fully transparent.

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列×9行的192x208像素单元格，背景透明。

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

Why this Codex Pet skill (vs OpenAI's official

hatch-pet

)

为什么选择这款Codex Pet工具（对比OpenAI官方

hatch-pet

）

OpenAI ships an official

hatch-pet

skill that produces the same Codex Pet artifact via the Codex-internal

$imagegen

system skill (requires Codex Pro +

$imagegen

configured).

This Codex Pet skill is a drop-in alternative that runs via the RunComfy CLI: a single

RUNCOMFY_TOKEN

plus

runcomfy

and

magick

binaries — no Codex Pro, no

$imagegen

, no OPENAI_API_KEY. The output Codex Pet artifact is identical — same

pet.json

shape, same

spritesheet.webp

1536x1872 atlas, same 9 animation rows — so Codex treats this Codex Pet exactly like one made by

hatch-pet

This skill follows the same pattern Codex's built-in Codex Pets use: one canonical pose, replicated across cells with ImageMagick micro-transforms for subtle animation (1-2 px shifts, blink frames, tilt frames). That matches what the official

hatch-pet

output actually looks like cell-by-cell — the Codex Pet animation visible in the Codex desktop app is intentionally subtle.

Pick this skill when:

You want a custom Codex Pet but don't have Codex Pro /
```
$imagegen
```
.
You want a custom Codex Pet built via the RunComfy Model API.
You want batch Codex Pet generation from a folder of source images (one canonical call per pet).
You're entering the OpenAI Codex Pet contest with a different model behind the visuals.
You said "codex pet", "/hatch", "make me a codex pet", "spritesheet.webp", "desktop pet for codex" explicitly.

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

结构、相同的1536x1872像素

spritesheet.webp

图集、相同的9个动画行——因此Codex会将这款工具生成的Codex Pet视为与

hatch-pet

生成的完全相同。

该工具遵循Codex内置Codex Pet的相同模式：一个标准姿态，通过ImageMagick微变换复制到各个单元格，实现微妙的动画效果（1-2像素位移、眨眼帧、倾斜帧）。这与官方

hatch-pet

输出的单元格细节完全一致——Codex桌面应用中的Codex Pet动画特意设计得十分微妙。

在以下场景选择这款工具：

你想要自定义Codex Pet，但没有Codex Pro /
```
$imagegen
```
权限。
你想要通过RunComfy模型API构建自定义Codex Pet。
你需要批量生成Codex Pet（从源图片文件夹中生成，每个宠物调用一次标准接口）。
你要参加OpenAI Codex Pet竞赛，希望使用不同的模型生成视觉效果。
你明确说出了"codex pet"、"/hatch"、"make me a codex pet"、"spritesheet.webp"、"desktop pet for codex"等触发词。

Codex Pet animation rows

Codex Pet动画行

Codex reads one fixed atlas: 8 columns, 9 rows, 192x208 cells. Each Codex Pet row corresponds to one animation state with a specific number of leading frames.

Row	State	Used columns	Frames	Codex Pet behavior
0	idle	0-5	6	calm breathing/blinking; the reduced-motion first frame for the Codex Pet
1	running-right	0-7	8	Codex Pet locomotion to the right
2	running-left	0-7	8	mirrored locomotion to the left
3	waving	0-3	4	greeting / attention gesture
4	jumping	0-4	5	anticipation, lift, peak, descent, settle
5	failed	0-7	8	error / sad / deflated reaction
6	waiting	0-5	6	patient idle variant
7	running	0-5	6	active working / in-progress loop (NOT foot-running)
8	review	0-5	6	focused / inspecting / thinking

Trailing cells after each row's last used column must be fully transparent.

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 style

Codex Pet风格

The Codex Pet visual house style:

EXAGGERATED chibi proportions: head occupies ~60 percent of total figure height; body and legs are tiny stubby and short. The whole figure should fit a near-square bounding box.
pixel-art-adjacent low-resolution mascot, chunky silhouette
thick dark 1-2 px outlines, visible stepped pixel edges
limited palette, flat cel shading, simple expressive face, tiny limbs
transparent background

Avoid: motion lines, drop shadows, glows, sparkles, floating effects, text labels, scenery, white/black backgrounds.

Codex Pet的视觉风格规范：

夸张的Q版比例：头部占整体身高的约60%；身体和腿短小粗壮。整个角色应接近正方形的边界框。
类像素风格的低分辨率吉祥物，轮廓厚重
1-2像素的深色粗轮廓，可见阶梯状像素边缘
有限配色，平涂 cel shading，表情简洁生动，四肢细小
透明背景

避免：运动线条、投影、光晕、闪光、悬浮效果、文字标签、场景、白/黑背景。

Prerequisites

前置条件

RunComfy CLI —
```
npm i -g @runcomfy/cli
```
RunComfy account —
```
runcomfy login
```
. CI alternative:
```
RUNCOMFY_TOKEN=<token>
```
.
ImageMagick —
```
brew install imagemagick
```
(macOS) or
```
apt-get install imagemagick
```
(Linux). Provides the
```
magick
```
command for the deterministic atlas assembly.
A source image URL — publicly fetchable HTTPS, JPEG/PNG/WebP, the subject the Codex Pet will be modeled on.

RunComfy CLI —
```
npm i -g @runcomfy/cli
```
RunComfy账号 —
```
runcomfy login
```
。CI环境替代方案：设置环境变量
```
RUNCOMFY_TOKEN=<token>
```
。
ImageMagick — macOS执行
```
brew install imagemagick
```
，Linux执行
```
apt-get install imagemagick
```
。提供
```
magick
```
命令用于确定性图集组装。
源图片URL — 可公开访问的HTTPS链接，格式为JPEG/PNG/WebP，作为Codex Pet的原型。

Codex Pet pipeline (1 GPT Image 2 call, ~2 min)

Codex Pet生成流程（1次GPT Image 2调用，约2分钟）

Canonical Codex Pet — single
```
runcomfy run openai/gpt-image-2/edit
```
call producing one 1024x1024 chibi pose on a magenta chroma-key background.
Cell normalization — chroma-key magenta → alpha 0, trim, aspect-fit into 192x208 with transparent padding.
9 row strips, programmatic — for each of 9 animation states, build the row's 8 cells via ImageMagick micro-transforms (translate / mask / mirror) of the canonical cell. Trailing cells filled with transparent 192x208.
Atlas — stack 9 row strips vertically into the 1536x1872 Codex Pet atlas.
WebP — convert atlas PNG to WebP.

Manifest + install — write

pet.json

, copy both files into

${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/

The micro-transform approach matches what Codex's built-in Codex Pets actually do — the Codex Pet animation is intentionally subtle, so 1-2 px shifts and blink masks per cell give the right visual feel without burning 72 GPT Image 2 calls.

标准Codex Pet生成 — 调用一次
```
runcomfy run openai/gpt-image-2/edit
```
，生成一张1024x1024像素的Q版姿态图片，背景为洋红色抠图底色。
单元格标准化 — 将洋红色转为透明（alpha 0），裁剪多余区域，按比例适配到192x208像素尺寸，保留透明边距。
程序化生成9行动画条 — 针对9种动画状态，通过ImageMagick微变换（平移/遮罩/镜像）将标准单元格生成每行的8个单元格。后续未使用的单元格填充为192x208像素的透明图。
图集组装 — 将9行动画条垂直堆叠为1536x1872像素的Codex Pet图集。
转换为WebP格式 — 将PNG图集转换为WebP格式。
生成清单并安装 — 写入
```
pet.json
```
文件，将两个文件复制到
```
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
```
目录。

微变换方法与Codex内置Codex Pet的实现方式一致——Codex Pet的动画特意设计得十分微妙，因此每个单元格1-2像素的位移和眨眼遮罩就能达到合适的视觉效果，无需调用72次GPT Image 2接口。

Step 1: Generate the canonical Codex Pet (1 call)

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

bash

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}"

bash

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}"

Step 2: Normalize the canonical into a 192x208 Codex Pet cell

步骤2：将标准图片归一化为192x208像素的Codex Pet单元格

Chroma-key magenta to alpha, trim to the pet sprite bounding box, aspect-fit into 192x208 with transparent padding.

bash

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

The 18% fuzz is tuned for GPT Image 2's anti-aliased magenta edges. Adjust to 25% if the Codex Pet has wider magenta halos, or to 8-10% if the pet has near-magenta highlights getting clipped.

将洋红色抠图底色转为透明，裁剪到宠物精灵的边界框，按比例适配到192x208像素尺寸并添加透明边距。

bash

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%。

Step 3: Build the 9 Codex Pet row strips programmatically

步骤3：程序化生成9个Codex Pet动画行

For each row, build 8 cells from the canonical via ImageMagick micro-transforms, fill unused trailing cells with transparent, then concatenate into a 1536x208 row strip.

bash

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

针对每行，通过ImageMagick微变换从标准单元格生成8个单元格，未使用的后续单元格填充为透明图，然后拼接为1536x208像素的行动画条。

bash

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" }

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"; }

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"


The micro-transform table is what gives the Codex Pet its readable-but-subtle motion in Codex. Tweak the numbers per row to taste; the deltas are intentionally small (1-2 px) so the Codex Pet feels alive without becoming distracting.

magick "${RUN_DIR}/cells/row1-strip.png" -flop -alpha set "${RUN_DIR}/cells/row2-strip.png"


微变换参数表是Codex Pet在Codex中呈现清晰但微妙动效的关键。可根据喜好调整每行的数值；为避免分散注意力，数值变化应控制在小范围（1-2像素）。

Step 4: Compose the Codex Pet atlas

步骤4：组装Codex Pet图集

Stack the 9 row strips vertically into the 1536x1872 Codex Pet atlas, then convert to WebP.

bash

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"

将9行动画条垂直堆叠为1536x1872像素的Codex Pet图集，然后转换为WebP格式。

bash

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"

Step 5: Write the Codex Pet manifest

步骤5：编写Codex Pet清单文件

bash

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

bash

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

Step 6: Install the Codex Pet

步骤6：安装Codex Pet

bash

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}"

Restart Codex (or reload the pet list) and the custom Codex Pet appears next to the 8 built-ins.

bash

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款宠物一起显示。

Prompting the canonical Codex Pet — what works

标准Codex Pet提示词技巧

The single GPT Image 2 call decides everything. Get this prompt right and the rest is deterministic.

Lead with the chibi proportion lock. "EXAGGERATED chibi proportions, head ~60 percent of figure height" is the difference between a thin tall character (which fits the 192x208 cell badly with pillarbox) and a head-dominant chibi (which fills the cell naturally). The latter is what Codex's built-in Codex Pets look like.

Demand the magenta
#FF00FF
chroma-key explicitly in every Codex Pet base prompt. GPT Image 2 only outputs RGB (no alpha), so the only way to get a transparent Codex Pet is to chroma-key a known background color out post-process.

Forbid the chroma-key color in the pet itself. Add: "The pet itself must not use the chroma-key color or any close-to-magenta highlights." Otherwise the chroma-key step removes Codex Pet body parts that happen to be magenta-ish.

Pin the style. "pixel-art-adjacent, chunky silhouette, 1-2 px outline, limited palette, flat cel shading" — pin every term that makes the Codex Pet match the Codex house style.

Forbid the wrong styles. "No polished illustration, no painterly render, no anime key art, no 3D render, no glossy app-icon polish, no realistic detail." Without this, GPT Image 2 will gravitate toward over-rendered anime art.

Anti-patterns:

Generic "transparent background" — GPT Image 2 paints near-white instead. Use chroma-key.
Letting the model freestyle proportions — it will draw a tall narrow chibi that doesn't fit 192x208.
Mixing styles in one prompt — pin one style anchor and stick to it.

单次GPT Image 2调用决定了所有效果。写对提示词，后续流程就是确定性的。

首先锁定Q版比例。"EXAGGERATED chibi proportions, head ~60 percent of figure height"是区分瘦高角色（难以适配192x208单元格，会出现黑边）和头部主导Q版角色（自然填充单元格）的关键。后者正是Codex内置Codex Pet的样式。

明确要求洋红色
#FF00FF
抠图底色。在每个Codex Pet基础提示词中都要明确说明。GPT Image 2仅输出RGB格式（无透明通道），因此获取透明Codex Pet的唯一方法是后期抠除已知的背景色。

禁止宠物本身使用抠图底色。添加："The pet itself must not use the chroma-key color or any close-to-magenta highlights."否则抠图步骤会误删除宠物身上接近洋红色的部位。

固定风格。"pixel-art-adjacent, chunky silhouette, 1-2 px outline, limited palette, flat cel shading"——固定每个符合Codex风格规范的术语。

禁止错误风格。"No polished illustration, no painterly render, no anime key art, no 3D render, no glossy app-icon polish, no realistic detail."如果不添加这些，GPT Image 2会倾向于生成过度渲染的动漫风格图像。

反模式：

通用的"transparent background"——GPT Image 2会生成接近白色的背景。应使用抠图底色。
让模型自由定义比例——它会生成瘦高的Q版角色，无法适配192x208单元格。
在一个提示词中混合多种风格——固定一种风格锚点并坚持使用。

Tuning the micro-animation

微动画调校

The default ImageMagick recipe in step 3 produces a Codex Pet animation similar to the built-in Codex Pets — subtle bob, occasional blink, jumping arc, head tilt. To make the animation more or less perceptible, tweak the deltas:

Bigger idle bob: change
```
shift:0:-1
```
to
```
shift:0:-2
```
in row 0.
Faster running cycle: increase the horizontal shifts in row 1 (e.g.
```
shift:3:0
```
instead of
```
shift:2:-1
```
).
Higher jump: change row 4's peak from
```
shift:0:-8
```
to
```
shift:0:-12
```
.
Stronger head tilt in review: change
```
rotate:-2
```
/
```
rotate:2
```
to
```
rotate:-4
```
/
```
rotate:4
```
.

Keep deltas small (≤ 4 px or ≤ 4°) so the Codex Pet doesn't become distracting.

步骤3中的默认ImageMagick脚本生成的Codex Pet动画与内置Codex Pet类似——轻微晃动、偶尔眨眼、跳跃弧线、头部倾斜。要让动画更明显或更柔和，可调整参数：

更明显的空闲晃动：将第0行的
```
shift:0:-1
```
改为
```
shift:0:-2
```
。
更快的跑步循环：增加第1行的水平位移（例如将
```
shift:2:-1
```
改为
```
shift:3:0
```
）。
更高的跳跃：将第4行的峰值从
```
shift:0:-8
```
改为
```
shift:0:-12
```
。
更明显的思考时头部倾斜：将
```
rotate:-2
```
/
```
rotate:2
```
改为
```
rotate:-4
```
/
```
rotate:4
```
。

保持参数变化较小（≤4像素或≤4°），避免Codex Pet过于分散注意力。

FAQ — Codex Pet

What is a Codex Pet? OpenAI Codex Pets are pixel-art animated companions launched May 2026 that float over your desktop and react to Codex's coding status. Custom Codex Pets live as

pet.json

spritesheet.webp

files under

${CODEX_HOME:-$HOME/.codex}/pets/<name>/

Why use this Codex Pet skill instead of
hatch-pet
? Official

hatch-pet

requires the Codex-internal

$imagegen

system skill (Codex Pro). This skill needs only

RUNCOMFY_TOKEN

and runs the same animation-row spec via the RunComfy CLI, with one GPT Image 2 call total.

How long does a Codex Pet generation take? ~2 minutes — 1 GPT Image 2 edit call (~90s) plus a few seconds of ImageMagick atlas assembly.

Why only one API call? The Codex Pet animation in the Codex desktop app is intentionally subtle (you can confirm by inspecting any built-in Codex Pet's atlas — 72 cells of nearly-identical poses with tiny variations). One canonical pose plus deterministic ImageMagick micro-transforms produces the same animation feel without burning 72 separate generation calls.

Can the Codex Pet skill take a non-human subject? Yes — pets, mascots, objects, foods all work. The base prompt simplifies the source into the Codex Pet house style automatically.

How do I install my Codex Pet? Copy

pet.json

and

spritesheet.webp

into

${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/

and reload Codex.

What if the canonical Codex Pet drifts off identity? Re-run step 1 with a tighter identity-preservation prompt (e.g. name specific features: hair color, glasses, accessory). Steps 2-6 are deterministic and don't need to change.

What size is each Codex Pet frame? 192x208 px. Each row strip is 1536x208 (8 frames). Final Codex Pet atlas is 1536x1872 (9 stacked rows).

Can I add custom poses or replace rows? Yes — modify the

build_row

calls in step 3. The atlas slot count per row must match the Codex contract (idle=6, running-right/left=8, waving=4, jumping=5, failed=8, waiting/running/review=6) for Codex to play them correctly.

什么是Codex Pet？ OpenAI Codex Pets是2026年5月推出的像素风格动画伙伴，会悬浮在桌面上方并对Codex的编码状态做出反应。自定义Codex Pet以

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 Pet需要多长时间？ 约2分钟——1次GPT Image 2编辑调用（约90秒）加上几秒的ImageMagick图集组装时间。

为什么只调用一次API？ Codex桌面应用中的Codex Pet动画特意设计得十分微妙（你可以查看任何内置Codex Pet的图集确认——72个单元格几乎都是相同的姿态，只有微小变化）。一个标准姿态加上确定性的ImageMagick微变换就能产生相同的动画效果，无需调用72次独立的生成接口。

这款Codex Pet工具可以处理非人类主题吗？ 可以——宠物、吉祥物、物品、食物都可以。基础提示词会自动将源图像简化为Codex Pet的风格。

如何安装我的Codex Pet？ 将

pet.json

和

spritesheet.webp

复制到

${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/

目录，然后重新加载Codex即可。

如果标准Codex Pet与源图像差异较大怎么办？ 重新运行步骤1，使用更严格的身份保留提示词（例如指定具体特征：头发颜色、眼镜、配饰）。步骤2-6是确定性的，无需修改。

每个Codex Pet帧的尺寸是多少？ 192x208像素。每行动画条为1536x208像素（8帧）。最终Codex Pet图集为1536x1872像素（9行堆叠）。

我可以添加自定义姿态或替换行吗？ 可以——修改步骤3中的

build_row

调用。每行的图集插槽数量必须符合Codex的规范（idle=6、running-right/left=8、waving=4、jumping=5、failed=8、waiting/running/review=6），Codex才能正确播放。

Limitations

局限性

One canonical pose per Codex Pet — animation is via ImageMagick transforms, not multi-frame model generation. This matches the built-in Codex Pets' subtle animation but won't produce dramatic motion (e.g. distinct frame-by-frame running cycle).
GPT Image 2 doesn't output alpha — the magenta chroma-key + post-process is a workaround. If the Codex Pet has near-magenta colors (rare for chibi palettes), switch the chroma-key to a different solid (
```
#00FFFF
```
cyan or
```
#00FF00
```
green) in both the prompt and the post-process.
Identity drift — GPT Image 2 may simplify the source image identity into Codex Pet style; specific small features (e.g. earrings, prop colors) may shift.
No audio / voice on Codex Pet — Codex Pets are visual-only.

每个Codex Pet仅一个标准姿态——动画通过ImageMagick变换实现，而非多帧模型生成。这与内置Codex Pet的微妙动画一致，但无法产生戏剧性的动作（例如逐帧不同的跑步循环）。
GPT Image 2不输出透明通道——洋红色抠图+后期处理是一种变通方案。如果Codex Pet有接近洋红色的颜色（Q版配色中很少见），可在提示词和后期处理中切换为其他纯色（
```
#00FFFF
```
青色或
```
#00FF00
```
绿色）。
身份偏差——GPT Image 2可能会将源图像的特征简化为Codex Pet风格；特定的小特征（例如耳环、道具颜色）可能会发生变化。
Codex Pet无音频/语音——Codex Pet仅支持视觉效果。

Exit codes

退出码

The

runcomfy

CLI uses sysexits-style codes:

code	meaning
0	Codex Pet canonical generated successfully
64	bad CLI args
65	bad input JSON for the Codex Pet call / schema mismatch (e.g. `size: "1024_1024"` instead of `"1024*1024"` )
69	upstream 5xx
75	retryable: timeout / 429
77	not signed in or token rejected

magick

(ImageMagick) returns 0 on a clean Codex Pet atlas; non-zero indicates a missing input frame or output-path permission issue.

Full reference: docs.runcomfy.com/cli/troubleshooting.

runcomfy

CLI使用sysexits风格的退出码：

代码	含义
0	标准Codex Pet生成成功
64	CLI参数错误
65	Codex Pet调用的输入JSON错误/ schema不匹配（例如 `size: "1024_1024"` 而非 `"1024*1024"` ）
69	上游服务5xx错误
75	可重试：超时/429错误
77	未登录或令牌被拒绝

magick

（ImageMagick）在图集组装成功时返回0；非零值表示缺少输入帧或输出路径权限问题。

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

How it works

工作原理

The skill calls
```
runcomfy run openai/gpt-image-2/edit
```
once with the user's source image and a tight chibi-proportion prompt, producing a 1024x1024 canonical Codex Pet on magenta.
ImageMagick chroma-keys the magenta to alpha 0, trims the sprite bbox, aspect-fits into a 192x208 cell.
ImageMagick programmatically builds 9 row strips by applying micro-transforms (1-2 px translate, blink mask, rotate, mirror) to the canonical cell.
The 9 row strips stack into the 1536x1872 Codex Pet atlas; the atlas converts to WebP.
A
```
pet.json
```
manifest is written; both files are copied into
```
${CODEX_HOME:-$HOME/.codex}/pets/<name>/
```
where Codex picks up the custom Codex Pet automatically.

工具调用
```
runcomfy run openai/gpt-image-2/edit
```
一次，传入用户的源图片和严格的Q版比例提示词，生成一张1024x1024像素的标准Codex Pet图片，背景为洋红色。
ImageMagick将洋红色转为透明（alpha 0），裁剪精灵的边界框，按比例适配到192x208像素的单元格。
ImageMagick通过对标准单元格应用微变换（1-2像素平移、眨眼遮罩、旋转、镜像），程序化生成9行动画条。
将9行动画条堆叠为1536x1872像素的Codex Pet图集，并转换为WebP格式。
写入
```
pet.json
```
清单文件；将两个文件复制到
```
${CODEX_HOME:-$HOME/.codex}/pets/<name>/
```
目录，Codex会自动识别该自定义Codex Pet。

Credits

致谢

The 9-row Codex Pet atlas spec — column counts, frame counts, cell dimensions — comes from OpenAI's official

hatch-pet

skill (MIT licensed). The animation-row contract and the chroma-key strategy are documented there. This skill reuses the spec but swaps the visual generator (

$imagegen

→ RunComfy GPT Image 2) and the atlas assembly (Python → ImageMagick) so it runs without Codex Pro.

9行Codex Pet图集规范——列数、帧数、单元格尺寸——来自OpenAI官方的

hatch-pet

工具（MIT许可证）。动画行规范和抠图策略均来自该工具的文档。本工具复用了该规范，但替换了视觉生成器（

$imagegen

→ RunComfy GPT Image 2）和图集组装方式（Python → ImageMagick），使其无需Codex Pro即可运行。

What this skill is not

本工具不包含的功能

Not a Codex client. Not a

hatch-pet

replacement when

$imagegen

is available — official

hatch-pet

is preferable when Codex Pro is in play. Not a self-hosted GPT Image 2 — depends on a working RunComfy account.

不是Codex客户端。当

$imagegen

可用时，不是

hatch-pet

的替代方案——官方

hatch-pet

在拥有Codex Pro权限时更适用。不是自托管的GPT Image 2——依赖可用的RunComfy账号。

Security & Privacy

安全与隐私

Token storage:
```
runcomfy login
```
writes the API token to
```
~/.config/runcomfy/token.json
```
with mode 0600. Set
```
RUNCOMFY_TOKEN
```
env var to bypass the file in CI.
Input boundary: Codex Pet prompts are passed as JSON via
```
--input
```
. The CLI does NOT shell-expand. No shell-injection surface.
Third-party content: source image URL is fetched by the RunComfy server. Treat external URLs as untrusted — image-based prompt injection is a known risk for any image-edit model.

Outbound endpoints: only

model-api.runcomfy.net

and

*.runcomfy.net

*.runcomfy.com

Generated-file size cap: the CLI aborts any single Codex Pet canonical download > 2 GiB.
Local install path: the final Codex Pet writes to
```
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
```
. No remote upload.

令牌存储：
```
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

。

生成文件大小限制：CLI会中止任何单个标准Codex Pet下载超过2 GiB的任务。
本地安装路径：最终的Codex Pet文件写入
```
${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
```
目录。无远程上传操作。

codex-pet

Original

Translation

Codex Pet — Pro Pack on RunComfy

Codex Pet — RunComfy专业工具包

What a Codex Pet is

什么是Codex Pet

Why this Codex Pet skill (vs OpenAI's official hatch-pet)

为什么选择这款Codex Pet工具（对比OpenAI官方hatch-pet）

Codex Pet animation rows

Codex Pet动画行

Codex Pet style

Codex Pet风格

Prerequisites

前置条件

Codex Pet pipeline (1 GPT Image 2 call, ~2 min)

Codex Pet生成流程（1次GPT Image 2调用，约2分钟）

Step 1: Generate the canonical Codex Pet (1 call)

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

Step 2: Normalize the canonical into a 192x208 Codex Pet cell

步骤2：将标准图片归一化为192x208像素的Codex Pet单元格

Step 3: Build the 9 Codex Pet row strips programmatically

步骤3：程序化生成9个Codex Pet动画行

Helpers

Helpers

Eyes are roughly at y=80-100 in a 208-tall cell.

Soften with a skin-tone overlay across that horizontal band.

Eyes are roughly at y=80-100 in a 208-tall cell.

Soften with a skin-tone overlay across that horizontal band.

9 Codex Pet rows with their per-frame micro-transforms

9 Codex Pet rows with their per-frame micro-transforms

row 2 = running-left = horizontal flip of row 1, built below

row 2 = running-left = horizontal flip of row 1, built below

Row 2: running-left = mirror of running-right

Row 2: running-left = mirror of running-right

Step 4: Compose the Codex Pet atlas

步骤4：组装Codex Pet图集

Step 5: Write the Codex Pet manifest

步骤5：编写Codex Pet清单文件

Step 6: Install the Codex Pet

步骤6：安装Codex Pet

Prompting the canonical Codex Pet — what works

标准Codex Pet提示词技巧

Tuning the micro-animation

微动画调校

FAQ — Codex Pet

FAQ — Codex Pet

Limitations

局限性

Exit codes

退出码

How it works

工作原理

Credits

致谢

What this skill is not

本工具不包含的功能

Security & Privacy

安全与隐私

Why this Codex Pet skill (vs OpenAI's official
`hatch-pet`
)

为什么选择这款Codex Pet工具（对比OpenAI官方
`hatch-pet`
）