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

1. Codex Pets 是什么

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

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

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

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

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

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

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

3.1 安装技能

1$skill-installer hatch-pet

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

3.2 触发生成

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

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

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

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

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

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

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

1~/.codex/pets/my-pet/
2  pet.json
3  spritesheet.webp

最小 pet.json 示例：

1{
2  "id": "my-pet",
3  "displayName": "My Pet",
4  "description": "A concise pet description.",
5  "spritesheetPath": "spritesheet.webp"
6}

关键一致性要求：

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

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

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

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

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

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

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

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

6. 官方与社区能力边界

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

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

7. 高频问题与排障清单

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

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

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

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

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

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

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

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

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

8. 面向生产使用的建议

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

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

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

参考链接

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