文档 · AgentPets

快速开始

一条命令就能把精选宠物装进 Codex。安装不需要账号，只有提交作品时才需要登录。

CLI 会拉取宠物包，并放到 ~/.codex/pets/boba/。要在 Codex 里启用它，打开 Settings → Appearance → Pets，然后点击 Select。在 Codex 里使用 /pet 可以让宠物 wake 或 sleep。

还没有宠物点子？先用 Codex Hatch Pet skill 孵化一只，再回来运行 agentpets submit。

安装

CLI 支持 Node 20+（也支持 Bun）。按你的使用习惯选一种方式即可，两种方式的能力和会话持久化都一样。

快速安装

直接用 npx。无需提前配置，第一次运行后包会被缓存。

全局安装

全局安装后可以立即调用，也更适合长期高频使用。

两种方式的登录持久化完全一样。Token 会保存在系统钥匙串里（macOS Keychain、Windows Credential Manager、Linux Secret Service），服务名是 agentpets-cli。即使 npx 清掉了包缓存，你的登录状态也还在。

命令

CLI 覆盖完整流程：发现、安装、孵化、发布，以及桌面应用和 Agent hooks。所有命令都支持 --help。

`agentpets list`

列出所有已通过审核的宠物和署名信息。安装前用它来浏览很方便。

`agentpets install <宠物名>`

把宠物放到 ~/.codex/pets/<宠物名>/。效果等同于 curl -sSf https://agentpets.dev/install/<宠物名> | sh。

`agentpets submit <路径>`

把你的宠物发布到图库。CLI 支持三种提交形式：

单个文件夹：agentpets submit ~/.codex/pets/boba
单个 zip：agentpets submit ~/Downloads/boba.zip
批量提交：agentpets submit ~/.codex/pets，每个直接子文件夹都会作为一只宠物提交

批量模式会为每只宠物显示进度，并在最后汇总失败项。宠物名会自动去重，不会因为名称已存在而提交失败。

`agentpets login / logout / whoami`

见上面的“登录”部分。

桌面应用

AgentPets Desktop 是一个漂浮在工作区上的桌面宠物，会根据 Agent 的工具调用做出反应。目前支持 macOS，Linux 和 Windows 稍后支持。视觉介绍见 /download。

`agentpets install desktop`

从 GitHub Releases 拉取适合当前平台的最新二进制文件，并放到 ~/.agentpets/bin/agentpets-desktop。CLI 会移除 macOS quarantine 属性，让应用打开时不再触发 Gatekeeper 提示。

`agentpets hooks install`

把桌面应用接入你的 Agent，让宠物在你工作时摇摆。CLI 会识别本机已有的 Agent，并分别写入 hooks：

Claude Code: ~/.claude/settings.json
Codex CLI: ~/.codex/hooks.json
Gemini CLI: ~/.gemini/settings.json
OpenCode: ~/.config/opencode/plugins/agentpets.js

工具事件会映射到宠物状态：tool.before → running，tool.after → idle，session.end → waving，session.error → failed。每个 hook 都会 POST 到本地 sidecar：http://127.0.0.1:7777/state。

`agentpets desktop <start | stop | status>`

管理正在运行的宠物。start 会以 detached 方式启动（PID 在 ~/.agentpets/desktop.pid，日志在 ~/.agentpets/desktop.log）。stop 发送 SIGTERM。status 显示 running、stopped 或 stale。

`agentpets up / down / toggle`

一次性切换桌面宠物的 wake 或 sleep 状态。up 会启用 hooks 并启动 desktop；down 会禁用 hooks 并停止 desktop；toggle 根据当前状态切换。这也是你在 Agent 里运行 /agentpets 时触发的命令。

`/agentpets` （斜杠命令）

运行过 agentpets hooks install 后，每个受支持的 Agent（Claude Code、Codex、Gemini、OpenCode）都会获得 /agentpets 命令。你可以在 Agent 里直接输入它，让宠物 wake 或 sleep，不需要离开当前对话：

/agentpets：切换状态（sleep 时切到 wake，wake 时切到 sleep）
/agentpets up：切到 wake 状态
/agentpets down：切到 sleep 状态
/agentpets status：查看 hooks 是否启用
/agentpets doctor：诊断安装和 Agent 接入状态

`agentpets hooks` （开关）

即使已经安装 hooks，也可以暂停它们，而不必改动 Agent 配置。agentpets hooks off 会在 ~/.agentpets/runtime/hooks-disabled 写入一个标记文件；所有已安装 hook 都会先检查它，命中后直接退出 0。agentpets hooks on 会删除这个文件。适合 sidecar 异常时临时停用。

`agentpets hooks uninstall`

撤销 hooks install：从每个 Agent 配置中移除 agentpets 项（保留你自己的 hooks），删除 /agentpets 斜杠命令文件，并移除 OpenCode 插件。传入 --remove-token 还会删除 ~/.agentpets/runtime/update-token 里的 auth token。

`agentpets doctor`

诊断命令。会检查二进制文件、sidecar bundle、sidecar 可达性、pid 文件格式、token 权限、kill-switch 状态、各 Agent 是否安装 hooks、Codex 的 codex_hooks feature flag，以及可用宠物数量。每个失败项都会给出可执行的提示。

`agentpets update`

比较本机已安装版本和最新 GitHub Release tag，如果有更新就下载。若桌面应用正在运行，会先停止、替换二进制，再重新启动。传入 --force 可以重新下载同一版本。

Sidecar 是运行在本机 7777 端口的 HTTP server。任何能 curl 并读取每次会话 token（~/.agentpets/runtime/update-token）的程序都能驱动宠物。这个 token 每次 sidecar 启动都会轮换，文件权限是 0600，只有当前用户能读；浏览器和远程网站不能直接访问：

T="$(cat "$HOME/.agentpets/runtime/update-token")"
curl -X POST http://127.0.0.1:7777/state \
  -H "Content-Type: application/json" \
  -H "X-AgentPets-Update-Token: $T" \
  --data-raw '{"state":"waving"}'

分享上架你的宠物

在 Codex 里孵化好宠物之后，一条命令就能分享出去。完整流程如下：

创建。在 Codex Desktop 里安装 Hatch Pet skill，然后运行 /pet。Codex 会把精灵图集 Spritesheet 和 pet.json 生成到 ~/.codex/pets/<宠物名>/。完整教程见 /create。
登录。如果还没登录，先运行 npx -y https://github.com/agiagentsdev/agentpets-dev/releases/latest/download/agentpets-cli.tgz login。
提交。npx -y https://github.com/agiagentsdev/agentpets-dev/releases/latest/download/agentpets-cli.tgz submit ~/.codex/pets/<宠物名>。也可以直接提交父目录来批量提交。
等待审核。提交会进入 admin queue，状态为“pending”。通过或拒绝后你会收到 Resend 邮件；如果被拒绝，邮件里会包含原因。
任何人都能安装你的宠物。审核通过后，把 npx -y https://github.com/agiagentsdev/agentpets-dev/releases/latest/download/agentpets-cli.tgz install <你的宠物名> 分享给别人即可。对方会立刻把宠物安装到自己的 ~/.codex/pets/。

AgentPets 上的宠物由用户提交，可能包含同人创作内容。AgentPets 不会对任何第三方底层知识产权主张权属、所有权或相关权益。如果你是权利人或授权代表，希望申请下架，请查看 /legal/takedown。

校验规则

服务器会强制执行这些规则；CLI 也会在本地提前检查。

pet.json 和精灵图集文件 spritesheet.webp（或 .png）必须位于文件夹或 zip 根目录。
精灵图集 Spritesheet 至少 256×256。推荐尺寸是 1536×1872（8×9 帧网格）。
频率限制：每个用户 24 小时最多提交 10 次。管理员不受此限制。
宠物名会自动去重（boba → boba-2 → boba-3 → …）。成功提交后一定会得到可用名称。
身份信息（userId、email、credit）来自经过验证的 OAuth token，永远不信任请求体。

常见问题

现象	原因	处理方式
未登录	没有 token，或会话已过期	`agentpets login`
presign 401	Bearer token 被 Clerk userinfo 拒绝	`agentpets logout` 然后 `agentpets login`
presign 429	触发 24 小时 10 次提交限制	等待 24 小时，或创建 submit-fallback issue
register 400 invalid_spritesheet	精灵图Sprite 小于 256×256	按 1536×1872 重新生成
register 400 missing_field	文件夹缺少 pet.json 或精灵图集 Spritesheet	检查文件夹内容
R2 PUT 403	预签名 URL 已过期（60 秒 TTL）	重试：CLI 会自动重新生成预签名 URL

适用于 Agent 的用法（Skill）

AgentPets 提供兼容 Claude Code / Codex / Cursor 的 skill：.claude/skills/agentpets/SKILL.md。兼容的 Agent 会自动加载它，并学会在什么场景、用什么方式替你调用 CLI。

它能做什么

你可以在任意 Agent 工具里说 “给我的 Codex 装一个舒服点的宠物”。它会运行 agentpets list，推荐 Boba/Boxcat，安装你选中的宠物，并提醒你到 Settings → Appearance → Pets 启用。
你可以说 “把我的所有宠物分享出去”。Agent 会在需要时运行 agentpets login，再执行 agentpets submit ~/.codex/pets，最后展示批量提交摘要。
你可以问 “我怎么做自己的宠物？”。Agent 会带你走完整流程：Codex Desktop → Hatch Pet skill → /pet → agentpets submit。

如何启用

如果你使用 Claude Code，可以把这个 skill 保存到全局，让每个项目都能使用：

其它 Agent 工具也可以从仓库加载同一个 SKILL.md。这个文件是普通 Markdown；除了 allowed-tools 之外，没有 Agent 专属语法。

定制化自己的 skill

CLI 是可执行的操作入口，skill 是给 Agent 理解任务的认知入口。如果你想做派生 skill（例如自动给新宠物打标签，或生成每日精选），可以把 AgentPets skill 当作参考。直接阅读：

.claude/skills/agentpets/SKILL.md

配置

CLI 内置了指向生产环境的默认配置。只有在测试非生产部署时，才需要覆盖环境变量。

PETDEX_URL：基础 URL，默认 https://agentpets.dev
CLERK_ISSUER: optional OAuth issuer override. Production login is temporarily disabled while AgentPets auth is being reconfigured.
CLERK_OAUTH_CLIENT_ID：公开 client id（内置在 CLI 二进制文件里）

参与贡献

欢迎给这里提 PR： agiagentsdev/agentpets-dev
Bug 报告和功能请求：创建 issue
如果 AgentPets 确实帮你省了时间，也欢迎通过 GitHub Sponsors 支持项目。

快速开始

安装

快速安装

全局安装

登录

命令

agentpets list

agentpets install <宠物名>

agentpets submit <路径>

agentpets login / logout / whoami