hatch-pet 完全指南

1.1 准备工作

你需要拥有 OpenAI Codex 访问权限。请确保你的 Codex 客户端已升级到最新版（建议 v0.12+）。

网络环境：技能安装和宠物生成都需要访问 GitHub 以及 OpenAI API。如果你处于网络受限环境，请提前为终端和 Codex 配置好代理（见下文「常见问题」）。

1.2 安装技能

打开 Codex，在对话输入框中输入以下命令：

$skill-installer hatch-pet

系统会自动从官方技能库拉取 hatch-pet 技能。等待终端输出 Skill installed successfully。

必须重启 Codex。关闭客户端并重新打开，否则技能无法加载。

如果安装失败？

常见原因是 Git 无法连接 GitHub。请打开你的终端（PowerShell / zsh 等），执行：

git config --global http.proxy http://127.0.0.1:你的代理端口
git config --global https.proxy http://127.0.0.1:你的代理端口

配置完成后，重新执行安装命令。

1.3 召唤你的第一只宠物

重启 Codex 后，在输入框里输入：

/pet

此时你的屏幕上会出现一只默认宠物（通常是柴犬 Hachi）。它会停留在桌面右下角，并随着 Codex 的工作状态改变表情和动作。

再次输入 /pet 可以隐藏宠物。

1.4 深入定制：生成你的专属像素宠物

这是 hatch-pet 最有趣的功能。你可以用自然语言描述你想要的宠物，AI 会自动生成对应的像素动画和配置文件。

步骤详解

在 Codex 输入框中键入 /hatch-pet，然后空一格，接着输入描述。例如：

/hatch-pet A cyberpunk samurai cat with neon blue eyes, wearing a tiny katana on its back, pixel art style

按下回车后，Codex 会调用 DALL·E 或其他图像模型生成宠物精灵图（sprite sheet），并根据你的描述自动生成动画配置文件 animations.json。

整个过程大约需要 30~90 秒，期间你会看到进度提示："Hatching your pet..."。

生成完成后，你可以在 Settings → Appearance → Pets 中找到刚刚生成的作品，它会被自动添加到"自定义宠物"列表。点击选中即可切换。

写好描述的技巧

• 风格限定词：务必加上 pixel art，因为宠物是以像素动图呈现的。
• 明确特征：颜色、配饰、姿态。避免过于复杂的背景或细节，AI 在处理 32×32 或 64×64 精灵时细节过多会模糊。
• 多尝试：如果不满意，可以调整描述重新生成，每次生成都会覆盖之前同名宠物的文件（可手动重命名保留）。

1.5 管理你的宠物库

所有宠物数据都保存在本地目录：

• Windows: %APPDATA%\Codex\pets\
• macOS: ~/Library/Application Support/Codex/pets/
• Linux: ~/.config/Codex/pets/

你可以：

• 手动备份：直接复制整个 pets 文件夹。
• 手动添加第三方宠物：从 PetDex（见下）下载的宠物文件夹放入该目录，重启 Codex 即可识别。
• 删除宠物：直接删除对应文件夹，然后重启。

1.6 探索 PetDex 社区

PetDex 是官方推出的宠物分享平台，地址：github.com/crafter-station/petdex。

你可以浏览其他用户上传的宠物，下载 ZIP 包。解压后确保文件夹内包含 sprite.png 和 animations.json（这是宠物生效的两个核心文件）。将整个文件夹放入本地 pets 目录即可。

1.7 性能调优

如果宠物在你打字或运行大型模型时出现卡顿，或者你觉得它占用了过多 GPU 资源，可以尝试以下设置：

打开 Codex 的 settings.json（通常在配置文件夹内），添加或修改：

"hatch-pet": {
  "enableShadows": false,
  "animationFPS": 12,
  "renderScale": 0.8
}

保存并重启 Codex。关闭阴影能显著降低渲染负担，降低 FPS 和缩放可进一步减少资源占用。

1.8 常见问题

Q：输入 /pet 无反应。
A：确认技能已安装并重启。在 Settings → Skills 中查看 hatch-pet 是否显示为"已启用"。如果显示错误，点击"修复"或重装。

Q：生成宠物时卡在 "Hatching..." 超过 5 分钟。
A：大概率是 API 调用超时。检查代理，或缩小描述长度重试。

Q：宠物显示为白块或乱码。
A：更新显卡驱动。如果是 Linux，确保已安装 Vulkan 驱动。