펫이 움직이지 않거나 나타나지 않으면 어떻게 하나요?

먼저 디렉터리 계층을 확인하세요. pet.json은 반드시 pets/ / 바로 아래에 있어야 하며, 압축을 풀 때 생긴 폴더가 한 겹 더 있으면 안 됩니다. 그다음 이미지 크기가 정확히 1536×1872인지 확인하세요.

V1과 V2 펫은 뭐가 다른가요?

커뮤니티에서 말하는 V2는 기본 9행 규격에 더해 16방향의 둘러보기 프레임을 추가한 것입니다. 기본 9행 규격 펫도 최신 Codex App에서 여전히 완벽하게 동작합니다.

이 사이트의 펫을 수정하거나 재배포해도 되나요?

됩니다. 모든 펫은 오리지널 픽셀 작품이며 자유롭게 수정하고 배포할 수 있습니다. 출처 표기도 필요 없습니다.

Codex 데스크톱 펫 사용 가이드

2026-07-16 업데이트

이게 뭔가요

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가 픽셀 단위로 검사합니다).
펫 몸에 읽을 수 있는 글자나 로고를 그리지 마세요.
디테일은 충분히 크게. 최종 표시 크기가 아주 작아서 한두 픽셀짜리 무늬는 아예 보이지 않습니다.

pet.json은 이렇게 생겼습니다

{
  "id": "momo",
  "displayName": "Momo",
  "description": "A round cream-orange cat.",
  "spritesheetPath": "spritesheet.webp"
}

필드 네 개면 충분합니다. id는 소문자와 숫자로 쓰고 폴더명과 일치시키세요. spritesheetPath는 pet.json 기준 상대 경로입니다.

직접 한 마리 만들기

방법 1: AI에게 그리게 하기(공식 루트). OpenAI는 openai/skills에서 hatch-pet 스킬을 제공합니다. Codex에 설치한 뒤 원하는 캐릭터를 설명하면, 이미지 생성을 호출해 9행 애니메이션을 한 행씩 그려낸 다음 규격에 맞는 스프라이트시트로 자동 합성합니다. 결과물은 곧바로 ~/.codex/pets/에 떨어집니다. 정교한 손그림 질감을 원하는 사람에게 어울립니다.

방법 2: 코드로 한 프레임씩 그리기(이 사이트의 루트). 이 사이트의 펫 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에서 여전히 완벽하게 동작합니다.

참고 이미지를 어떻게 만들지 막막하다면? PixPix에서 한 문장만으로 '캐릭터 전신, 단색 배경' 참고 이미지를 만들 수 있습니다. hatch-pet에 넘겨도 좋고, 보면서 한 프레임씩 직접 그려도 좋습니다.