Codex Pets 使用详细说明（官方 + 社区实战整合）

Mon, 11 May 2026 00:00:00 +0000

从零开始掌握 Codex Pets：先启用内置宠物，再生成自定义宠物，最后完成本地安装与稳定排障。

1. Codex Pets 是什么

Codex Pets 是 Codex App 的可选动画伙伴层（floating overlay），核心价值不是“装饰”，而是让任务状态可视化：

在使用其他应用时，仍可看到当前活跃线程。
直接显示状态变化：运行中、等待输入、待审阅。
用简短进度提示快速了解“刚刚发生了什么”。

这套机制对长时任务和多线程任务非常实用，能明显减少反复切回主界面的成本。

2. 官方启用路径（建议先做）

根据 OpenAI Codex App 官方设置文档，推荐按以下顺序启用：

打开 Settings -> Appearance -> Pets。
选择内置宠物，或刷新本地自定义宠物列表。
使用以下任一方式切换悬浮层显示状态：
- 在输入框输入 /pet
- Settings -> Appearance 中使用 Wake Pet / Tuck Away Pet
- Cmd+K（macOS）或 Ctrl+K（Windows）执行同名命令

3. 自定义宠物生成：hatch-pet 正确流程

3.1 安装技能

$skill-installer hatch-pet

安装后若没有立即生效，先重启 Codex；也可以先通过命令面板执行 Force Reload Skills。

3.2 触发生成

$hatch-pet create a new pet inspired by my recent projects

也可以直接给出更精确描述，例如颜色、风格、性格、动作偏好。

3.3 生成机制（官方 skill 关键点）

openai/skills 里的 hatch-pet 说明了完整生成契约：

通过 $imagegen 负责视觉生成。
标准流程最多约 10 个视觉任务（1 个 base + 9 个状态行）。
目标图集规格是 8 x 9 网格，单格 192 x 208，总尺寸 1536 x 1872。
最终以 pet.json + spritesheet.webp 作为可安装包落地。

4. 本地文件结构与包规范

社区安装文档与生成工具的约定高度一致，最小可用包建议如下：

~/.codex/pets/my-pet/
 pet.json
 spritesheet.webp

最小 pet.json 示例：

{
 "id": "my-pet",
 "displayName": "My Pet",
 "description": "A concise pet description.",
 "spritesheetPath": "spritesheet.webp"
}

关键一致性要求：

文件夹名、id、资源路径要对齐。
spritesheetPath 指向包内文件（本地安装场景不建议外链）。
图集尺寸和网格不匹配时，动画会错位或花屏。

5. 已有宠物的两种安装方式

方式 A：手动安装（可控）

mkdir -p "$HOME/.codex/pets/tater"
unzip -o "./tater-codex-pet.zip" -d "$HOME/.codex/pets/tater"

安装后通过 /pet 或设置页选择该宠物。

方式 B：社区 CLI 一键安装（更快）

npx codex-pet-cli add <pet-slug>

社区站点说明该命令会把宠物安装到 ~/.codex/pets/<name>，适合快速体验大量现成宠物。

6. 官方与社区能力边界

维度	官方文档/官方仓库	社区站点/第三方工具
功能定义	权威来源（设置路径、命令入口、技能机制）	主要补充教程、示例、素材市场
兼容保证	与 Codex 版本同步更新	可能滞后或偏差
风险	相对可控	需自行校验来源与包内容
推荐用途	作为“标准答案”	作为“提效补充”

实践建议：以官方说明为准绳，以社区工具做提速。

7. 高频问题与排障清单

7.1 `/pet` 输入后没有触发，仅当普通消息发送

已在 openai/codex 出现公开问题案例（例如 #20836）。可按以下顺序排查：

先在 Settings -> Appearance -> Pets 里直接切换，确认基础功能可用。
升级到最新 Codex 版本后重试。
通过 Cmd+K/Ctrl+K 执行宠物切换命令，验证是否仅 slash 行为异常。
若仍异常，记录版本号和平台信息后提 issue。

7.2 `hatch-pet` 已安装但命令补全里找不到

公开问题（如 #20778）反映过“slash 自动补全不可见”的情况。重点是区分：

Skill 被安装，并不一定等于 slash 自动补全立刻可见。
按官方技能文档，优先使用 $skill-name 形式触发技能。
安装后先 Force Reload Skills 或重启应用。

7.3 生成流程中断并出现 stream disconnected

#20947 的排障信息显示，某些环境中可能涉及 $imagegen 发现/依赖问题。建议：

检查 hatch-pet 是否完整安装。
核实系统技能链路是否正常加载（尤其图像生成依赖）。
先跑最小生成任务验证流程，再逐步增加复杂度。

8. 面向生产使用的建议

先固定一套“已验证可用”的宠物模板与尺寸规范。
把 pet.json 校验做成脚本，提交前自动检查关键字段。
团队内统一宠物包目录命名，避免重复或覆盖。
社区来源包先在隔离环境验证后再分发。
每次 Codex 版本升级后做一次宠物回归检查。

9. 快速上手清单（10 分钟版本）

设置里启用一个内置宠物，确认 overlay 正常。
安装 hatch-pet 并重载技能。
生成第一个自定义宠物。
检查输出目录是否包含 pet.json 与 spritesheet.webp。
放入 ~/.codex/pets/<pet-id>/ 并在设置页启用。
用 /pet 与快捷键验证开关是否正常。

参考链接

OpenAI Developers（Codex App Settings）：https://developers.openai.com/codex/app/settings
OpenAI Developers（Agent Skills）：https://developers.openai.com/codex/skills
OpenAI Skills 仓库 README：https://github.com/openai/skills
hatch-pet（官方技能定义）：https://github.com/openai/skills/blob/main/skills/.curated/hatch-pet/SKILL.md
社区安装说明（含 manifest 示例）：https://codexpets.org/install
社区 Hatch 指南：https://codex-pet.org/how-to-create-a-codex-pet/
社区一键安装工具说明：https://codex-pet.com/
兼容问题参考（官方仓库 issue）：

Codex on 忘川