更新日期：2026 年 7 月 10 日
适用对象：使用 Codex、Claude Code、Cursor、Gemini CLI 等 AI 编程工具的普通用户和开发者

导读

最近 GitHub 上出现了不少“Codex 宠物”项目：有的是给 Codex 官方小宠物更换皮肤，有的是把 AI Agent 的工作状态做成一只常驻桌面的动画角色，还有的能通过 MCP 与 Codex 互动，甚至有人把宠物装进了 ESP32 小屏幕。

它们看起来都叫“宠物”，实际用途却不完全相同。本文会解决五个问题：

1. 这些项目分别能做什么，适合什么系统；
2. 哪些项目仍在维护，普通用户应该怎么选；
3. 每个项目如何安装、部署和验证；
4. 零基础用户如何把一段提示词交给本机 Agent，让它自动完成部署；
5. 使用第三方宠物时，需要注意哪些隐私、版权和兼容性问题。

如果你只想快速得到结论：

• 只想给 Codex 官方宠物换造型：优先使用 Petdex；
• 想看到 Codex 正在思考、执行命令还是等待确认：优先使用 Clawd on Desk；
• 想让多个 AI 工具共用一只桌面宠物，并通过 MCP 控制它：选择 OpenPets Electron 版；
• 只使用 Mac，追求原生、轻量和本地运行：选择 OpenPets Swift 版；
• 喜欢 Windows 时代的回形针助手：试试 Agent Paperclip；
• 想在桌面上同时放多只 Codex 宠物：可以部署 Multi Codex Pets。

一、先弄懂：什么是 Codex 宠物

Codex Desktop 内置了一个小型动画宠物。它通常出现在输入框附近，会根据 Codex 当前的状态切换动作，例如待机、奔跑、等待、成功或失败。输入 /pet 可以让它出现或暂时收起，也可以在 Codex 的外观设置中切换宠物。

围绕这个功能，社区项目大致分成四类。

1. 官方宠物皮肤包

这类项目不单独运行一个应用，只是往 Codex 的宠物目录里放入配置文件和精灵图。代表项目包括 Petdex、Awesome Codex Pet、Codex Anime Pets 和 Codex Pokepets。

优点是安装简单、资源占用低，与 Codex 原生界面结合得最好。缺点是只能出现在 Codex 窗口里，能够展示的状态也受官方接口限制。

2. 独立桌面宠物

这类项目是一个单独的桌面应用。宠物可以悬浮在所有窗口上方，或者住在菜单栏、桌面边缘和一个独立的小房间中。代表项目包括 Clawd on Desk、CodexPet Nest、Multi Codex Pets 和 Codex Pet Companion。

3. Agent 状态与 MCP 互动工具

这类项目不仅负责显示动画，还会读取本机的 Agent 状态，或者通过 MCP 接收 Codex 发来的指令。宠物可以说话、做动作、显示当前工具和任务状态。两个同名但不同团队开发的 OpenPets 都属于这一类。

4. 硬件宠物

这类项目把 Codex 状态显示在 ESP32、M5Stack 等外接小屏幕上。它们更适合喜欢折腾硬件的用户，不建议作为第一次尝试。

二、热门项目快速对比

项目更新速度很快，版本号和安装包名称可能变化。下载时应以各项目的 Releases 页面为准，不要从不明网盘获取安装包。

三、开始之前需要准备什么

普通用户

建议先把 Codex Desktop 更新到当前稳定版，然后确认官方宠物能够正常显示：

1. 打开 Codex Desktop；
2. 进入 Settings；
3. 打开 Appearance；
4. 找到 Pets，选择一只宠物；
5. 回到对话窗口，输入 /pet 测试。

如果这里只显示空白、宠物被裁掉，或者设置中根本没有 Pets，应该先解决 Codex 本身的版本或兼容性问题，再安装第三方资源。

需要运行命令的项目

建议准备以下工具：

• Node.js 当前长期支持版，用于运行 npx、npm 和 Electron 项目；
• Git，用于下载源码；
• macOS 用户如需编译 Swift 项目，还要安装 Xcode Command Line Tools；
• 硬件项目需要 PlatformIO、数据线和对应开发板。

在 Mac 或 Linux 上，Codex 自定义宠物通常位于：

~/.codex/pets/<pet-id>/

Windows 通常位于：

%USERPROFILE%\.codex\pets\<pet-id>\

一个完整的宠物包至少应包含 pet.json 和精灵图文件。安装新宠物前，可以先备份整个 pets 文件夹。

四、Codex 官方宠物与自定义宠物包

官方宠物如何使用

官方宠物无需单独安装。在 Settings → Appearance → Pets 中选择角色，然后点击 Select。在任务页面输入 /pet，可以唤醒或收起宠物。

Codex 自定义宠物本质上是“配置文件加精灵图”。常见图集尺寸为 1536×1872 像素，按照 8 列、9 行划分为 192×208 的动画格。常见动作包括待机、左右奔跑、挥手、跳跃、等待、失败和审阅。不过，最终应以宠物包自己的 pet.json 为准，不要只按固定尺寸猜测。

OpenAI 的 Skills 仓库中还提供了 hatch-pet 工作流，可用于制作符合 Codex 结构的自定义宠物包。对于普通用户，先用 Petdex 安装现成角色会更省时间；确认自己喜欢这种形式之后，再制作原创角色。

五、Petdex：最适合普通用户的宠物商店

项目地址：crafter-station/petdex
在线图库：petdex.dev

Petdex 同时提供在线图库、命令行安装器和 macOS 桌面悬浮工具。它最大的优势不是宠物数量，而是把“搜索、安装、选择和诊断”做成了一条完整流程。

安装一个宠物

先确认电脑已经安装 Node.js，然后打开终端，依次执行：

npx petdex install boba
npx petdex init
npx petdex doctor

第一条命令安装名为 boba 的宠物，第二条完成初始化，第三条检查目录和文件是否正常。

安装完成后：

1. 重启 Codex Desktop；
2. 打开 Settings → Appearance → Pets；
3. 选择 Boba；
4. 点击 Select；
5. 在任务中输入 /pet。

也可以直接在终端中选择宠物：

npx petdex select

如果已经知道宠物的短名称，可以执行：

npx petdex select boba

如何判断安装成功

检查下面这个目录是否存在：

~/.codex/pets/boba/

目录中应包含宠物配置和精灵图。如果文件存在但 Codex 中没有显示，先完全退出 Codex 再重新打开，而不是只关闭当前任务。

六、Awesome Codex Pet：一条命令安装社区角色

项目地址：legeling/awesome-codex-pet

这是一个社区宠物合集，适合已经知道自己想安装哪个角色的用户。它的安装逻辑仍然是把资源放进 Codex 的标准宠物目录。

使用 Node.js 安装

下面的命令适用于已经安装 Node.js 的 macOS、Windows 和 Linux：

npx awesome-codex-pet firefly--lingxiaotian

将最后的宠物 ID 替换成项目列表里的其他角色即可。

使用安装脚本

Mac 和 Linux 用户也可以使用项目提供的脚本：

curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- firefly--lingxiaotian

查看可安装列表：

curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- --list

更稳妥的做法是先在浏览器中打开脚本，确认内容后再运行，不要养成把陌生脚本直接交给终端执行的习惯。

安装后仍然需要重启 Codex，并在 Settings → Appearance → Pets 中手动选择。

七、Clawd on Desk：把 Agent 工作状态变成桌面动画

项目地址：rullerzhou-afk/clawd-on-desk
下载页面：GitHub Releases

Clawd on Desk 不是一个简单皮肤包，而是完整的跨平台桌面应用。它可以监控 Codex CLI、Claude Code、Cursor、Gemini 等多种 Agent，把“正在思考、执行工具、等待批准、任务完成”等状态显示成动画。

普通用户安装方法

1. 打开项目的 Releases 页面；
2. Windows 下载对应架构的安装包，macOS 下载 .dmg，Linux 选择 .AppImage 或 .deb；
3. 完成安装并启动 Clawd on Desk；
4. 首次运行时允许它同步 Codex；
5. 其他 Agent 可以在 Settings → Agents 中继续添加。

新版本通常会自动同步 Codex 和 Claude Code。Codex 一侧可通过官方 hooks 获取事件，也可以读取 ~/.codex/sessions 下的本地会话记录作为兼容方案。

从源码运行

git clone https://github.com/rullerzhou-afk/clawd-on-desk.git
cd clawd-on-desk
npm install
npm start

验证方法

打开一个新的 Codex 任务，让 Codex 执行一个会调用工具的操作。正常情况下，宠物应该依次出现工作、等待或完成状态。如果动画始终停在待机状态，进入 Agents 设置检查 Codex 是否已启用，并确认应用有权读取本机 Codex 会话目录。

适合谁

如果你经常让 Agent 长时间运行，又不想反复切回终端查看进度，Clawd on Desk 的实用性比单纯换皮肤更高。它还支持中文界面，普通用户上手成本较低。

八、OpenPets Electron 版：跨平台宠物加 MCP

项目地址：alvinunreal/openpets
官方网站：openpets.dev

这是一个基于 Electron 的跨平台 OpenPets，支持 Windows、macOS 和 Linux。它提供桌面宠物、插件 SDK 和可选的 MCP 服务。接入 MCP 后，Codex 不只是被宠物“观察”，还可以主动让宠物说话、做动作或展示任务结果。

安装桌面应用

1. 从 Releases 页面下载当前系统的安装包；
2. macOS Apple Silicon 选择 arm64 版本，Intel Mac 选择 x64 版本；
3. Windows 使用安装程序，Linux 可以使用 AppImage；
4. 启动应用并选择宠物。

部分版本可能没有完成代码签名。确认安装包确实来自官方仓库后，macOS 如果仍然拦截，可以先在 Finder 中右键应用并选择“打开”。项目文档也提供了清除隔离标记的方法：

xattr -dr com.apple.quarantine /Applications/OpenPets.app

这条命令会放宽系统对该应用的隔离限制，只应对来源已经核实的应用使用。

接入 Codex MCP

在终端中执行：

codex mcp add openpets -- npx -y @open-pets/mcp@latest

然后检查是否已经登记：

codex mcp list

重启 Codex，新建一个任务，让它调用 OpenPets 的状态、动作或说话工具。如果连接异常，可以运行项目提供的诊断程序：

npx @open-pets/cli doctor

从源码开发

项目源码开发需要 Node.js 20 及以上和 pnpm 11 及以上：

git clone https://github.com/alvinunreal/openpets.git
cd openpets
pnpm install
pnpm dev:desktop

普通用户建议优先使用发布页安装包，只有准备开发插件时才需要源码部署。

九、OpenPets Swift 版：Mac 原生共享宠物

项目地址：alterhq/openpets
官方网站：openpets.sh

注意：它与上一节的 OpenPets 不是同一个项目。这一版使用 Swift 开发，只支持 macOS 14 及以上，重点是原生、轻量和本地运行。同一只宠物可以接收 Codex、Claude、Cursor、OpenCode 或本地脚本发来的事件。

安装步骤

1. 从 GitHub Releases 下载最新的 macOS 应用；
2. 将应用移动到“应用程序”文件夹；
3. 启动菜单栏应用；
4. 唤醒内置宠物；
5. 在应用中启动 MCP 服务。

默认 MCP 地址为：

http://127.0.0.1:3001/mcp

把它添加到 Codex：

codex mcp add openpets-native --url http://127.0.0.1:3001/mcp

这里使用 openpets-native 作为名称，是为了避免与前一个 Electron 项目重名。

安装并测试命令行工具

在 OpenPets 的爪印菜单中安装 CLI，默认位置为 ~/.local/bin/openpets。安装后可以测试：

openpets ping
openpets animate waving --once
openpets notify --title "Build Passed" --status done --text "All tests completed."

如果终端提示找不到 openpets，把 ~/.local/bin 加入系统的 PATH，或者先使用完整路径执行。

安全设置

MCP 服务应该只监听 127.0.0.1。不要为了“让它能连接”而改成 0.0.0.0，否则同一网络中的其他设备可能访问这个控制接口。

十、Agent Paperclip：复活经典回形针助手

项目地址：fredruss/agent-paperclip

Agent Paperclip 把早期办公软件里的回形针助手带回了桌面，并让它显示 Codex 或 Claude Code 的工作状态。它更偏向“状态观察器”，而不是 Codex 原生宠物皮肤。

安装步骤

需要 Node.js 18 或更高版本：

npm install -g agent-paperclip
agent-paperclip setup
agent-paperclip

停止后台程序：

agent-paperclip stop

程序检测到 ~/.codex 后，会自动识别 Codex，并在后台观察 ~/.codex/sessions 中的会话变化。当前 Codex 兼容性主要在 macOS 上测试，Windows 和 Linux 用户应先阅读最新 Issues。

从源码运行

git clone https://github.com/fredruss/agent-paperclip.git
cd agent-paperclip
npm install
npm run dev

按照项目说明，它会读取工具名称、文件名、命令的首个单词、简短搜索词和部分状态信息，不会主动上传完整提示词或文件内容。即便如此，在公司电脑或敏感项目中使用前，仍应先看清权限和源码。

十一、其他值得关注的扩展项目

1. CodexPet Nest：宠物小窝与社区市场

项目地址：RyanNiu/codexpet-nest
官网：codexpet.app

CodexPet Nest 目前以 macOS 为主，提供悬浮小窝、社区宠物市场、本地宠物管理、快捷操作和实时用量环。普通用户可以从官网或 Releases 下载当前 macOS 版本，安装后直接在市场中选择宠物。Windows 和 Linux 版本仍应以项目路线图为准。

2. Multi Codex Pets：桌面上同时养多只

项目地址：anthnykr/multi-codex-pets

该项目适用于 macOS 14 及以上，会加载内置宠物和 ~/.codex/pets 中的自定义宠物。它没有现成发布包，需要本地编译：

git clone https://github.com/anthnykr/multi-codex-pets.git
cd multi-codex-pets
./script/build_and_run.sh

构建后会生成 dist/MultiCodexPets.app。应用出现在菜单栏后，可以调整显示数量、动画、移动方式和缩放比例。

3. Codex Pet Live：给官方宠物增加状态徽章

项目地址：Sakaax/codex-pet-live

它会在官方宠物附近显示当前命令、改动文件数量、Git 分支、增删行数和用量等信息。目前是偏实验性的 macOS 项目，需要 Swift 和 Xcode Command Line Tools：

xcode-select --install
git clone https://github.com/Sakaax/codex-pet-live.git
cd codex-pet-live
./install.sh

诊断命令：

~/.codex/tools/codex-pet-live/codex-pet-live --diagnose
~/.codex/tools/codex-pet-live/codex-pet-live --once

卸载时执行：

./uninstall.sh

安装脚本会建立一个 macOS 后台启动项。若不再使用，应运行卸载脚本，不要只删除源码目录。

4. Codex Pet Companion：Windows 电子宠物

项目地址：pixel-raccoon/codex-pet-companion

这是一个 Windows 桌面养成工具，包含喂食、玩耍、休息、心情、精力、专注和亲密度等状态。安装方式很直接：

1. 从 Releases 下载最新 ZIP；
2. 解压到固定文件夹；
3. 运行 CodexPetCompanion.exe；
4. 让程序自动检测 Windows、WSL 或自定义 .codex 路径。

它更像一款电子宠物游戏，不是严肃的 Agent 监控面板。

5. Codex Buddy：把宠物装进硬件小屏幕

项目地址：openelab-commits/codex-buddy

Codex Buddy 是 M5Stack StickS3、ESP32-S3 方向的原型项目，可以通过蓝牙显示使用量和权限确认状态。需要准备对应开发板、PlatformIO 和 Python：

git clone https://github.com/openelab-commits/codex-buddy.git
cd codex-buddy
pio run -e m5stack-sticks3
pio run -e m5stack-sticks3 -t upload
pio run -e m5stack-sticks3 -t uploadfs
python3 -m pip install bleak

这是工作原型，不是买来即用的成品。首次刷写前要确认开发板型号、串口和供电，不建议没有 ESP32 经验的用户直接照抄。

6. Codex Pets React：给网页应用加入宠物

项目地址：backnotprop/codex-pets-react

它不是桌面程序，而是面向 React 开发者的组件库：

npm install codex-pets-react

适合在本地项目控制台、Agent 监控面板或个人网站中复用 Codex 风格的精灵动画。普通用户不需要安装它。

7. 动漫与宝可梦风格宠物包

社区还出现了 Codex Anime Pets 和 Codex Pokepets 等资源包。它们的安装方式与普通自定义宠物相似，但角色形象可能涉及第三方版权。个人非商业使用和公开视频展示都应阅读仓库授权说明，商业项目尤其不能默认“GitHub 上能下载就能商用”。

十二、懒人一键安装部署：复制提示词给 Codex 或其他 Agent

前面的部署步骤已经尽量写得简单，但对零基础用户来说，打开终端、判断系统架构、选择安装包和处理依赖仍然可能比较困难。更省事的办法，是把一段完整的任务提示词交给运行在自己电脑上的 Codex 或其他本地 Agent，让它先检查环境，再代替我们完成下载、安装、配置和验证。

这里所说的“一键安装”，不是把一条来路不明的脚本交给系统直接执行，而是让 Agent 按照明确的安全规则完成整个流程。它需要能够访问本机终端和文件；只会聊天、不能操作电脑的网页版 AI，无法真正完成安装。

使用方法

1. 在需要安装宠物的那台电脑上打开 Codex、Claude Code、Gemini CLI、Cursor Agent 或其他具备本机操作能力的 Agent；
2. 每次只复制下面的一段提示词，不要同时安装多个方案；
3. Agent 遇到管理员密码、系统权限、SmartScreen 或 macOS 安全确认时，应停下来让用户亲自处理；
4. 安装结束后，检查 Agent 给出的版本、安装位置、验证结果和卸载方法；
5. 如果失败，不要从头反复重装，继续使用本节后面的“失败自动排查提示词”。

提示词一：小白推荐组合，一次安装 Petdex 和 Clawd on Desk

这套组合最适合第一次尝试：Petdex 负责更换 Codex 内置宠物，Clawd on Desk 负责在桌面显示 Agent 的工作状态。

你现在是我的本机部署助手。请在这台电脑上完整安装并配置“Petdex + Clawd on Desk”小白组合，不要只给我教程或命令，要在获得的本机权限范围内实际执行、验证并收尾。

安全与执行规则：
1. 先识别操作系统、系统版本、CPU 架构、当前用户权限、默认终端，以及 Codex Desktop、Node.js、npm、npx 和 Git 是否已经安装。
2. 只允许使用以下官方来源：
   - Petdex：https://github.com/crafter-station/petdex
   - Clawd on Desk：https://github.com/rullerzhou-afk/clawd-on-desk
3. 使用最新稳定版，不使用测试版、夜间版、第三方网盘、镜像站或名称相似的项目。
4. 修改前先备份现有 Codex 宠物目录。macOS/Linux 通常是 ~/.codex/pets，Windows 通常是 %USERPROFILE%\.codex\pets。备份目录要带日期和时间，不得删除或覆盖现有宠物。
5. 不执行来源不明的 curl | bash，不关闭系统安全功能，不读取或上传账号凭据、Cookie、auth.json、聊天正文和私人文件。
6. 不默认设置开机启动。需要管理员权限、安装系统依赖或放宽安全限制时，先解释原因并等待我亲自确认。

安装任务：
1. 如果 Node.js 或 npx 缺失，使用操作系统可信的软件管理方式安装当前长期支持版；安装后重新检查版本。
2. 依次执行 npx petdex install boba、npx petdex init 和 npx petdex doctor。确认 pet.json 和精灵图确实位于正确的 Codex pets 目录。
3. 从 Clawd on Desk 的 GitHub Releases 下载与当前系统和 CPU 架构匹配的最新稳定安装包，优先使用预编译版本，不从源码编译。
4. 安装并启动 Clawd on Desk，只为 Codex 开启必要的 Agent 连接。能使用官方 hooks 时优先使用 hooks，兼容回退才读取本地 Codex sessions 状态。
5. 重启 Codex Desktop，在 Settings → Appearance → Pets 中选择 Boba；如果你具备界面控制能力就完成选择，否则只把最后需要我点击的位置说清楚。
6. 新建一个无敏感内容的 Codex 测试任务，确认官方宠物能够显示，同时确认 Clawd on Desk 能从待机切换到工作、等待或完成状态。

完成后请给我一份中文结果报告，必须包含：检测到的系统和架构、安装的准确版本、安装位置、备份位置、验证通过与失败项目、保留的手动步骤、停止或卸载方法。任何步骤失败都不要假装成功，也不要用删除配置或重装系统等破坏性方法修复。

提示词二：只安装 Petdex 和一个官方界面宠物

不想常驻额外桌面应用，可以只复制这一段：

请在这台电脑上实际安装并验证 Petdex，官方仓库是 https://github.com/crafter-station/petdex 。

执行前先检测操作系统、CPU 架构、Codex Desktop、Node.js、npm 和 npx。备份现有 ~/.codex/pets 或 %USERPROFILE%\.codex\pets，备份名称必须包含日期时间，不得删除原有宠物。

只使用 Petdex 官方 npm 包和官方仓库。若缺少 Node.js，使用可信的系统软件管理方式安装当前长期支持版；需要管理员权限时先让我确认。禁止使用第三方下载站，禁止执行未检查的远程脚本，禁止读取账号凭据。

完成以下任务：
1. 执行 npx petdex install boba 安装宠物；
2. 执行 npx petdex init 完成初始化；
3. 执行 npx petdex doctor 检查安装；
4. 检查 boba 目录中是否存在 pet.json 和精灵图；
5. 完全重启 Codex Desktop；
6. 如果能控制界面，就在 Settings → Appearance → Pets 中选择 Boba 并用 /pet 测试；不能控制界面时，告诉我最后三步应该点击哪里。

最后输出安装版本、实际目录、备份目录、doctor 结果、验证结果和完整卸载方法。不要只输出教程，要执行到你权限允许的最后一步。

提示词三：只安装 Clawd on Desk 桌面状态宠物

请在本机完整安装并配置 Clawd on Desk，官方仓库是 https://github.com/rullerzhou-afk/clawd-on-desk 。目标是让它能够显示 Codex 的待机、工作、等待确认和完成状态。

先检测操作系统版本、CPU 架构、Codex 安装情况和现有 Clawd on Desk。只从官方 GitHub Releases 获取最新稳定版，并选择与当前系统、架构完全匹配的预编译安装包；除非官方没有发布包，否则不要从源码构建。

安全要求：不要使用第三方网盘；不要关闭 Gatekeeper、SmartScreen 或杀毒软件；不要读取账号密码、Cookie 或会话正文；不要默认开启开机启动；不要给应用超出状态监控所需的文件权限。macOS 如果拦截未签名应用，先尝试 Finder 右键“打开”，不要自动执行 xattr，除非先向我解释并得到确认。

安装后启动应用，只连接 Codex。优先使用官方 hooks，必要时才使用 ~/.codex/sessions 的本地状态回退。创建一个不含隐私信息的 Codex 测试任务，验证宠物至少出现待机和工作状态，并检查应用日志中是否存在连接错误。

最后用中文列出：系统与架构、下载来源、安装版本、安装位置、使用的 Codex 连接方式、验证结果、应用读取了哪些本地信息、如何停止、如何卸载。失败时保留日志，不要反复覆盖安装。

提示词四：安装 OpenPets 并接入 Codex MCP

这条提示词会根据系统自动选择版本：macOS 14 及以上优先使用 Swift 原生版，Windows、Linux 和较旧的 macOS 使用 Electron 版。它不会同时安装两个同名项目。

请在这台电脑上安装一个适合当前系统的 OpenPets，并把它安全接入 Codex MCP。不要只写教程，要实际完成检测、安装、配置和验证。

允许使用的官方项目只有两个：
1. macOS 14 及以上优先使用 Swift 原生版：https://github.com/alterhq/openpets
2. Windows、Linux 或不满足 Swift 版要求的系统，使用 Electron 版：https://github.com/alvinunreal/openpets

先识别操作系统、版本、CPU 架构、Codex CLI 是否可用、codex mcp 子命令是否存在、Node.js/npx 是否存在、3001 端口是否被占用，以及当前是否已经配置名为 openpets 或 openpets-native 的 MCP。不得覆盖同名现有配置；发现冲突时先说明。

安全要求：只使用最新稳定版和官方 Releases；不使用第三方下载站；不关闭系统安全功能；不读取 auth.json、Cookie 或私人文件；不把 MCP 监听地址改成 0.0.0.0；不开放防火墙端口；不默认设置开机启动。

执行逻辑：
- 如果选择 Swift 版：安装并启动应用，启动它的本地 MCP 服务，确认只监听 127.0.0.1:3001，然后执行 codex mcp add openpets-native --url http://127.0.0.1:3001/mcp。
- 如果选择 Electron 版：安装与系统架构匹配的官方发布包，核对 npm 包来源后执行 codex mcp add openpets -- npx -y @open-pets/mcp@latest。
- 修改 MCP 后执行 codex mcp list。Swift 版使用 ping 或 animate 做测试；Electron 版运行 npx @open-pets/cli doctor，并测试一次无敏感内容的状态或动作调用。

需要管理员权限、安全放行或用户点击时暂停，让我亲自完成。最后报告实际选择了哪个 OpenPets、准确版本、安装位置、MCP 名称和地址、端口监听范围、验证结果、如何移除 MCP、如何卸载应用。任何验证没有通过都明确写“未通过”。

提示词五：安装 Agent Paperclip 回形针助手

请在这台电脑上实际安装并验证 Agent Paperclip，官方仓库是 https://github.com/fredruss/agent-paperclip 。

先检测操作系统、CPU 架构、Node.js、npm、Codex CLI、~/.codex 目录和是否已经存在 agent-paperclip。当前项目对 Codex 的测试以 macOS 为主；如果系统不在官方明确支持范围内，先停止安装并说明风险，不要强行修改系统。

只使用官方 npm 包和官方仓库。Node.js 必须满足 18 或更高版本；如需安装或升级，优先使用当前系统可信的软件管理方式。尽量使用当前用户可写的 npm 安装位置，避免为了全局安装直接使用 sudo。任何开机启动设置都要先询问我。

确认环境满足要求后，依次执行 npm install -g agent-paperclip、agent-paperclip setup 和 agent-paperclip。确认它能够识别 Codex 本地会话状态，再用一个无隐私内容的测试任务验证状态变化。检查它实际读取的目录和元数据，确认没有把服务监听到公网，也不要读取或输出完整提示词、文件正文、账号凭据或 Cookie。

最后报告安装版本、npm 安装位置、运行状态、读取范围、验证结果，以及 agent-paperclip stop 和完整卸载方法。遇到错误先保存日志并做安全排查，不要删除 ~/.codex。

提示词六：Mac 一键部署 Multi Codex Pets

请在这台 Mac 上实际部署 Multi Codex Pets，官方仓库是 https://github.com/anthnykr/multi-codex-pets 。

先确认系统是 macOS 14 或以上，检测 CPU 架构、Git、Swift 和 Xcode Command Line Tools，并检查 ~/.codex/pets 中现有宠物。系统不兼容时停止，不要尝试绕过最低版本要求。

把现有 pets 目录做带日期时间的备份。只从官方仓库克隆源码到用户目录下清晰命名的开发文件夹，先检查 README 和 script/build_and_run.sh 的内容，再执行 ./script/build_and_run.sh。不要使用 sudo 运行构建脚本，不要删除已有宠物，不要自动修改网络、防火墙或开机启动设置。

构建后确认 dist/MultiCodexPets.app 存在，把应用安装到当前用户可用的 Applications 目录并启动。验证菜单栏图标、Visible Pets、动画和至少一只 ~/.codex/pets 中的宠物能够显示。记录编译错误和系统权限提示。

最后报告源码目录、生成应用位置、安装版本或提交号、备份目录、验证结果、如何关闭、如何卸载应用和源码。构建失败时不要假装已经安装。

提示词七：Windows 一键安装 Codex Pet Companion

请在这台 Windows 电脑上实际安装并验证 Codex Pet Companion，官方仓库是 https://github.com/pixel-raccoon/codex-pet-companion 。

先检测 Windows 版本、x64/ARM64 架构、Codex 的实际目录、WSL 是否参与运行，以及电脑上是否已有该程序。只从官方 GitHub Releases 下载与架构匹配的最新稳定 ZIP，不使用第三方网盘或重新打包版本。

下载后先检查文件名、发布版本和数字签名或官方校验信息（如果项目提供）。不要关闭 Defender 或 SmartScreen；出现警告时暂停并把发布页、文件名和风险解释给我，由我决定是否继续。把程序解压到当前用户的本地应用目录，不要散落在下载文件夹，也不要默认创建开机启动项。

启动 CodexPetCompanion.exe，确认它正确识别 Windows、WSL 或自定义 .codex 路径。测试宠物窗口、喂食、玩耍和至少一个 Codex 状态变化。不要上传会话正文、凭据或私人文件。

最后报告版本、下载来源、安装目录、识别到的 Codex 路径、验证结果、是否出现安全警告、如何备份宠物数据和如何彻底卸载。

本文其他项目的通用安装提示词

CodexPet Nest、Codex Pet Live、Codex Buddy、Codex Pets React、动漫宠物包等项目，可以使用下面这份通用模板。复制前只需要替换第一行中的项目名和官方仓库地址。

请在本机实际安装并验证这个项目：
项目名称：[填写项目名称]
官方仓库：[粘贴本文给出的 GitHub 仓库地址]

先阅读官方 README、Releases、许可证和当前系统要求，再检测操作系统、版本、CPU 架构、依赖、磁盘空间以及是否已经安装过。只使用官方仓库和最新稳定版；有预编译安装包就优先使用安装包，没有发布包时才考虑源码构建。

修改任何内容前，备份该项目会影响的现有配置和数据。不得删除现有 Codex 配置，不得执行来源不明的远程脚本，不得使用第三方网盘，不得关闭系统安全功能，不得读取或上传凭据、Cookie、auth.json、聊天正文和私人文件，不得默认开启公网监听或开机启动。

请实际完成：环境检查、下载来源核对、安装、最小必要配置、启动、功能测试和日志检查。需要管理员权限、硬件刷写、安全放行、付费操作或不可逆修改时必须暂停，让我亲自确认。系统或硬件不兼容时停止，不要强行绕过要求。

最终用中文报告：项目与版本、系统兼容性、下载来源、安装和数据目录、创建或修改的配置、启动方式、验证结果、遗留的手动步骤、升级方法、停止方法和完整卸载方法。没有验证的项目必须标记为“未验证”，失败时保留日志并说明下一步。

安装失败后的自动排查提示词

如果前面的 Agent 中途报错，把下面这段继续发给同一个 Agent：

刚才的安装没有完整成功。请不要从头盲目重装，也不要删除现有配置。先根据刚才实际执行过的操作，对当前电脑进行一次只读诊断：确认系统与架构、已下载文件、安装目录、进程、端口、依赖版本、Codex pets 目录、MCP 列表和最近的相关错误日志。

把问题分成“下载失败、依赖缺失、系统不兼容、权限阻止、路径错误、端口冲突、应用已安装但未连接、验证方法错误”中的一种或几种。对照项目官方 README、Releases 和 Issues，给出最可能的根因。

只自动执行可逆且低风险的修复，例如补齐可信依赖、修正当前用户目录中的路径、重新选择正确架构安装包、恢复被误改的项目配置、重启相关应用并重新验证。禁止使用 rm -rf、清空 ~/.codex、关闭系统安全功能、暴露公网端口或覆盖未知配置。

修复后重新执行最小功能测试，并用中文列出：根因、修复内容、修改的文件、是否验证通过、仍需我手动处理的步骤和回滚方法。如果仍然失败，停止继续尝试并保留完整错误信息。

已安装项目的安全升级提示词

请安全升级我指定的 Codex 宠物项目：[填写项目名]。先识别当前版本、安装方式、配置目录和数据目录，再查询官方仓库的最新稳定版与升级说明。升级前备份配置和宠物数据，不跨越不兼容的大版本，不安装测试版，不改变开机启动、网络监听和权限设置。完成升级后重新执行原有功能验证，并报告旧版本、新版本、备份位置、配置迁移、验证结果和回滚方法。若无法确认原来的安装方式或官方升级路径，停止并向我说明，不要覆盖安装。

这些提示词能降低操作门槛，但不能替代系统权限和用户判断。一个可靠的 Agent 应该明确告诉你它做了什么、验证了什么，以及哪些步骤没有完成；如果它只回复“已经安装成功”却不给版本、路径和验证结果，就不应该直接相信。

十三、推荐的五套部署方案

方案 A：最省心

适合第一次使用：

Codex 官方宠物 + Petdex

优点是简单、稳定、资源占用低。先用 Petdex 安装一只宠物，确认官方状态动画工作正常，再考虑其他工具。

方案 B：兼顾好看与实用

适合内容创作者和长任务用户：

Codex 官方宠物 + Clawd on Desk

官方宠物负责 Codex 窗口内的视觉效果，Clawd on Desk 负责桌面级状态提醒。两者作用不同，可以同时使用。

方案 C：多 Agent 统一管理

适合同时使用 Codex、Claude Code、Cursor 和 Gemini 的用户：

Clawd on Desk 或 OpenPets Electron 版

如果主要想“看状态”，选 Clawd on Desk；如果希望 Agent 主动让宠物做动作、说话或通知，选 OpenPets。

方案 D：Mac 原生轻量化

适合不想常驻 Electron 应用的 Mac 用户：

OpenPets Swift 版 + Codex MCP

把 MCP 地址保持在 127.0.0.1，并用 openpets ping 验证本地连接。

方案 E：桌面展示和视频素材

适合录制 AI 编程演示：

Multi Codex Pets + Codex Pet Live

这一套更有画面感，但两个项目都偏实验性。正式录制前应测试 CPU 占用、窗口层级和屏幕录制权限，避免动画在录屏时消失。

十四、常见问题与排查方法

1. 安装了宠物，但 Codex 设置里找不到

依次检查：

1. 宠物目录是否多套了一层文件夹；
2. pet.json 是否直接位于宠物 ID 文件夹中；
3. 精灵图文件名是否与配置一致；
4. 是否完全退出并重启 Codex Desktop；
5. npx petdex doctor 是否报告错误。

正确结构应类似：

~/.codex/pets/boba/pet.json
~/.codex/pets/boba/spritesheet.webp

而不是：

~/.codex/pets/boba/boba/pet.json

2. 宠物只显示一部分，或者被输入框裁掉

这类问题不一定是宠物包损坏，也可能是 Codex Desktop 的界面兼容问题。社区已经报告过 macOS 宠物被裁切或不可见 的情况。可以先更新 Codex、切换回官方宠物、调整窗口大小并重启应用。如果官方宠物也异常，应等待客户端修复，而不是反复重装宠物包。

3. WSL 中安装成功，Windows Codex 却看不到

Codex Desktop 运行在 Windows 主机时，未必会读取 WSL Linux 用户目录下的 ~/.codex/pets。这也是社区正在跟踪的 WSL 自定义宠物路径问题。最直接的处理方式是把宠物安装到 Windows 的：

%USERPROFILE%\.codex\pets\

4. macOS 提示应用无法验证或已损坏

先确认下载地址是项目官方 Releases，校验文件来源后，在 Finder 中右键应用并选择“打开”。只有项目文档明确说明时，才考虑执行 xattr。不要为了安装一个桌面宠物关闭整个系统的安全防护。

5. npx 或 npm 找不到

这通常表示没有安装 Node.js，或者 Node.js 没有加入 PATH。安装当前长期支持版 Node.js，重新打开终端后检查：

node --version
npm --version
npx --version

三个命令都能显示版本号，再继续安装 Petdex、OpenPets MCP 或 Agent Paperclip。

6. MCP 已添加，但 Codex 调用不到

先执行：

codex mcp list

然后确认桌面宠物应用正在运行，本地端口没有被其他程序占用。HTTP MCP 必须保证地址、端口和路径完全一致；stdio MCP 则要确认 npx 能在当前用户环境中运行。修改配置后最好完全重启 Codex。

7. 桌面宠物一直停在待机状态

这通常说明状态监听没有连接成功。检查应用的 Agent 设置、Codex 会话目录读取权限、hooks 配置以及 macOS 隐私权限。可以先新建一个最简单的 Codex 任务验证，不要直接拿一个已经运行数小时的旧会话测试。

十五、隐私、安全与版权提醒

1. 它们可能读取本地会话状态

为了判断 Codex 是在思考、运行工具还是等待批准，Clawd on Desk、Agent Paperclip、Codex Pet Live 等项目可能读取 ~/.codex/sessions、本地状态数据库、Git 信息或文件名。即使项目声明不上传数据，企业设备和敏感项目也应先审查权限与源码。

2. 不要随便开放本地 MCP 端口

桌面宠物的 MCP 服务只供本机使用时，应监听 127.0.0.1。除非你清楚认证、网络隔离和防火墙配置，否则不要把服务暴露到局域网或公网。

3. 安装脚本和未签名应用需要核实来源

curl | bash 很方便，但也意味着远程脚本会立即执行。重要设备上应先下载、查看脚本，再运行。macOS Gatekeeper 和 Windows SmartScreen 的警告也不应被无条件忽略。

4. 开源代码不等于素材可以商用

有些项目的程序代码采用 MIT 或 AGPL，但宠物图像、动漫角色和主题资源可能使用另一套授权，甚至只允许非商业使用。制作 YouTube 视频、付费主题或商业软件前，应分别检查代码许可和素材许可。

5. 不建议把账号凭据交给状态查看器

如果一个宠物项目要求读取 auth.json、浏览器 Cookie 或长期令牌，而它的用途只是显示动画和用量，就应该谨慎评估。能通过本地会话事件或官方 MCP 完成的功能，没有必要额外扩大权限。

十六、我的最终建议

Codex 宠物已经从一个小彩蛋，逐渐发展成三种实用工具：视觉反馈、Agent 状态监控和本地交互入口。不过，安装得越多并不代表体验越好。

普通用户最合理的顺序是：

1. 先启用 Codex 官方宠物；
2. 用 Petdex 安装一个第三方角色；
3. 需要桌面状态提醒时，再增加 Clawd on Desk；
4. 确实需要 Agent 主动控制宠物时，才部署 OpenPets 和 MCP；
5. Multi Codex Pets、Codex Pet Live、Codex Buddy 等实验项目，放到最后尝试。

如果只让我推荐一个组合，我会选择 Petdex + Clawd on Desk。前者解决“好不好看”，后者解决“Agent 现在到底在干什么”。这套方案跨平台、上手快，也不会一开始就把 MCP、端口、源码编译和硬件刷写全部堆到普通用户面前。

对于内容创作者，桌面宠物还有一个额外价值：它能把原本看不见的 AI 工作状态变成画面语言。录制 Codex 教程时，观众能直接看到 Agent 正在工作、等待确认还是已经完成，比单纯盯着终端日志更直观。

但无论选择哪个项目，都建议坚持三个原则：只从官方仓库下载、先看权限再授权、先装一个并验证再继续叠加。这样既能获得有趣的桌面体验，也不会让一个装饰工具变成本机隐私和稳定性的负担。

项目链接汇总

• OpenAI hatch-pet
• Petdex
• Awesome Codex Pet
• Clawd on Desk
• OpenPets Electron 版
• OpenPets Swift 版
• Agent Paperclip
• CodexPet Nest
• Multi Codex Pets
• Codex Pet Live
• Codex Pet Companion
• Codex Buddy
• Codex Pets React
• Codex Anime Pets
• Codex Pokepets