**从零开始掌握 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 安装技能

```text
$skill-installer hatch-pet
```

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

### 3.2 触发生成

```text
$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. 本地文件结构与包规范

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

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

最小 `pet.json` 示例：

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

关键一致性要求：

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

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

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

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

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

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

```bash
npx 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）：
   - https://github.com/openai/codex/issues/20836
   - https://github.com/openai/codex/issues/20778
   - https://github.com/openai/codex/issues/20947