OpenPets Docs

OpenPets 是什么

OpenPets 是一款小型开源桌面应用，它会在你的屏幕上显示一只动态宠物，并让你的 AI 编程助手通过它做出反应。当助手在思考、编辑文件、运行测试、等待审批或完成任务时，宠物会展示对应的反应或简短的状态消息。

OpenPets 以本地优先为设计原则。桌面应用、MCP 服务器和 CLI 均通过本机上的本地套接字相互通信。应用发起的唯一对外网络请求是下载你选择安装的宠物以及检查 OpenPets 更新。没有任何遥测数据。

OpenPets 可与任何支持 MCP 的助手配合使用。它为 Claude Code 和 OpenCode 提供了专用的一键集成；其他客户端（如 Cursor、VS Code、Windsurf、Zed）可通过 MCP 参考 页面上显示的标准 stdio MCP 命令进行连接。

文档结构

本文档将所有内容从上至下排列在一个页面中。每个章节也是一个独立页面，可以直接链接，例如 /docs/concepts 或 /docs/mcp。左侧边栏按章节对锚点进行分组，方便快速跳转。

从哪里开始

• 如果你尚未安装 OpenPets，请先阅读 快速开始。
• 如果已安装并希望连接助手，请跳转至 配置 AI 助手。
• 如果你是集成开发者、插件作者，或对架构感到好奇，请先阅读 OpenPets 的工作原理。

1. 安装桌面应用

下载适用于你操作系统的最新 OpenPets 版本并安装。由于安装包目前尚未签名，每个操作系统都会在首次启动时要求你确认。

完整的各平台安装步骤（包括如何处理 Gatekeeper 和 SmartScreen，以及如何卸载）请参见 安装桌面应用。

2. 选择宠物

OpenPets 启动后会驻留在系统托盘，而非 Dock。点击托盘图标并打开宠物管理器。你可以从内置画廊安装宠物，也可以在 openpets.dev/gallery 浏览所有可用宠物。

• 点击你喜欢的宠物上的安装。
• 桌面应用会下载宠物包并在本地解压。
• 安装完成后，如需在启动时显示该宠物，请将其设置为默认宠物。

安装过程完全在本地进行。桌面应用通过 HTTPS 获取目录和宠物 ZIP 包，对其进行验证后写入用户数据目录，不会有其他内容离开你的机器。有关请求的完整列表，请参见 隐私与网络行为。

3. 连接助手

打开托盘菜单，选择集成，然后选择你的 AI 助手。OpenPets 为 Claude Code 和 OpenCode 提供了专用的集成卡片。

其他支持 MCP 的助手（Cursor、Windsurf、VS Code MCP、Zed、Claude Desktop 等）目前还没有专用卡片。若要接入这些助手，请使用 MCP 服务器参考 上显示的标准 stdio 命令。

基本安装流程不会安装 Hooks。Hooks 是一项选装功能，它会修改助手的 hook 设置文件以自动触发反应。如需启用，请在 Claude Code 卡片上打开配置。

4. 验证是否正常运行

安装集成后重启你的助手，使其加载新的 MCP 服务器。然后让助手检查 OpenPets：

Can you call openpets_status and tell me which pet I have configured?

助手应调用 openpets_status 工具，并回复正在运行的应用版本和当前目标宠物。你也可以尝试 openpets_react 和 openpets_say，查看宠物切换反应或显示简短消息的效果。

如果助手提示 OpenPets 不可用，请确认桌面应用仍在托盘中运行，并且你在安装集成后已重启助手。若仍无法连接，请参见 故障排除。

后续步骤

• 阅读 OpenPets 的工作原理，了解默认宠物与代理宠物、租约以及可用反应。
• 有关 Claude Code 的深入配置（包括 hooks），请参见 Claude Code 集成指南。
• 有关 OpenCode 配置（包括插件），请参见 OpenCode 集成指南。
• 有关其他内容（CLI、文件格式、OpenPets 写入的具体文件），请继续向下滚动或使用侧边栏导航。

默认宠物与代理宠物

OpenPets 区分桌面上的两种宠物窗口。

默认宠物是日常陪伴的宠物。代理宠物适用于同时运行多个助手并希望每个助手驱动自己的宠物，或为特定助手指定特定宠物的场景。

如果助手请求的宠物未安装或已损坏，OpenPets 会将事件路由至默认宠物，而不是直接报错。状态响应中包含回退原因，助手可以据此了解发生了什么。

租约与路由

助手不会直接发送宠物反应，而是先向 OpenPets 申请一个宠物的租约。租约是一个短暂的凭证，表示"在接下来几秒内，将我的反应和消息路由至这只宠物"。租约允许多个助手共享 OpenPets 而互不干扰。

OpenPets 自带的 MCP 服务器会透明地处理这一切：在启动时获取租约，每 5 秒发送一次心跳，并在关闭时释放租约。租约 id 会自动附加到它发送的每个反应和消息中。

lease TTL          15 seconds
heartbeat (MCP)    every 5 seconds
server sweep       every 5 seconds (releases expired leases)
fallback           default pet if requested pet is missing or broken

本地 IPC

所有 OpenPets 通信均在本机完成。没有网络总线、没有云队列、没有远程端点。桌面应用暴露一个本地套接字，CLI、MCP 服务器以及任何其他 OpenPets 客户端均直接连接到该套接字。

OpenPets 启动时会写入一个小型发现文件，告知客户端套接字的位置和所需的令牌。客户端读取该文件，打开套接字，发送带令牌的 JSON 请求，并读取单个 JSON 响应。

macOS    ~/Library/Application Support/OpenPets/runtime/ipc.json
Windows  %APPDATA%\OpenPets\runtime\ipc.json
Linux    $XDG_RUNTIME_DIR/openpets/ipc.json  (if private)
         ~/.config/OpenPets/runtime/ipc.json (fallback)

发现文件以 0600 权限写入 0700 目录中。令牌在每次桌面应用启动时轮换。

协议结构

• 协议版本：1。
• 编码：行分隔的 JSON。每个连接一个 JSON 请求，以 \n 结尾。
• 最大消息大小：16 KB。
• 连接超时：2 秒。响应超时：3 秒。
• 每个请求必须包含发现令牌，令牌错误或缺失将被拒绝。

可用方法：hello、status、pets.list、pets.install、 lease.acquire、lease.heartbeat、lease.release、pet.react 和 pet.say。完整的请求和响应结构请参见 MCP 参考。

MCP 与钩子

助手驱动宠物有两种方式。MCP 是主动路径，助手有意识地调用工具；钩子是被动路径，生命周期事件自动触发反应。

大多数用户保持 MCP 开启、钩子关闭。钩子可以在助手无需调用工具的情况下自动提供视觉反馈，但它们需要修改助手的钩子设置文件，这也是它们作为选装功能而非基础安装组成部分的原因。

两种路径在底层都使用相同的本地 IPC，在针对特定宠物时也都通过租约机制。

宠物资源

一只宠物是一个包含精灵图和元数据文件的小型数据包。OpenPets 从三个位置读取宠物。

目录 ZIP 包在写入磁盘前会经过验证：归档大小、解压后大小、条目数量、单文件大小、路径遍历尝试以及符号链接均会被检查。有关包结构和验证规则，请参见 宠物文件格式。

用户数据目录的位置因操作系统而异；具体路径列在 本地文件与配置 中。

反应

每只宠物支持相同的固定反应集合。助手调用 openpets_react 或通过 openpets_say 附带反应时，从以下列表中选择一个：

宠物只需为其关心的反应提供动画帧，未实现的反应会回退到 idle。

下载

OpenPets 的发布版本发布在 GitHub 上。每个版本包含每个平台和架构对应的一个安装包，文件名中包含版本号和目标平台信息。下载文件名始终遵循以下格式：

OpenPets-<version>-mac-<arch>.dmg
OpenPets-<version>-mac-<arch>.zip
OpenPets-<version>-win-<arch>-setup.exe
OpenPets-<version>-win-<arch>-portable.exe
OpenPets-<version>-linux-<arch>.AppImage
OpenPets-<version>-linux-<arch>.deb
OpenPets-<version>-linux-<arch>.tar.gz

每个版本还会发布一个 SHA256SUMS 文件，供你验证下载的完整性。当前 OpenPets 安装包未经代码签名，因此每个操作系统都会在首次启动时发出警告。

macOS

1. 下载适合你 Mac 的 .dmg（Apple Silicon 或 Intel）。
2. 打开 DMG，将 OpenPets.app 拖入应用程序文件夹。
3. 首次启动时，由于构建版本未签名，macOS Gatekeeper 会阻止运行。请右键点击 OpenPets.app 并选择打开，然后在弹出的对话框中再次点击打开。
4. 如果 macOS 持续拒绝启动，请手动移除隔离属性：

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

OpenPets 在 macOS 上默认不显示在 Dock 中。启动后，你只会看到宠物（如果已启用）和菜单栏中的托盘图标。

Windows

根据安装偏好，选择以下两种 Windows 安装包之一：

首次启动时，由于安装包未签名，Windows SmartScreen 可能会显示"Windows 已保护你的电脑"提示。请点击更多信息，然后点击仍要运行。

Linux

提供三种 Linux 安装包，请根据你的发行版和打包偏好选择：

chmod +x OpenPets-*.AppImage
./OpenPets-*.AppImage

OpenPets 使用私有运行时目录存放 IPC 套接字。在拥有严格 $XDG_RUNTIME_DIR（权限 0700，归当前用户所有）的系统上，套接字会放置在该目录下；否则回退至 /tmp/openpets-<uid>/。

首次启动

OpenPets 首次启动时会显示引导窗口，让你选择初始宠物并决定是否在启动时显示默认宠物。引导完成后，应用将驻留在系统托盘中。

在 macOS 上，OpenPets 不会出现在 Dock 中——应用有意将自身从 Dock 中隐藏，使宠物成为唯一可见的存在。所有操作均通过托盘菜单完成。

如果你在 Windows 或 Linux 上意外关闭了应用，点击托盘图标或再次启动 OpenPets 即可；应用使用单实例锁，不会重复运行。

更新

OpenPets 在启动时会检查 GitHub 上是否有新版本。如果有更新版本，托盘菜单会显示"有可用更新"条目，点击后跳转至最新发布页面。

更新不会自动安装。更新步骤如下：

1. 从托盘菜单退出 OpenPets。
2. 下载适用于你平台的新版安装包。
3. 运行安装包；你已安装的宠物和偏好设置会保留，因为它们存储在用户数据目录中，而不在应用包内。

卸载

删除应用不会删除已安装的宠物、偏好设置或集成文件。这些文件存放在应用包之外，以便更新时保留。如需彻底卸载，请手动删除这些文件。

如果你之前安装了 Claude Code 或 OpenCode 集成，请在删除应用之前先打开 OpenPets，并在"集成"窗口中移除这些集成。这样才能正确清理 ~/.claude 和 OpenCode 配置中的托管条目。有关 OpenPets 涉及的完整文件列表，请参见 本地文件与配置。

浏览画廊

OpenPets 宠物目录以静态 JSON 文件的形式发布于 https://openpets.dev/pets/catalog.v3.json。openpets.dev/gallery 页面将该文件渲染为一个宠物网格，每个宠物均附有预览精灵图、名称和简短描述，可直接安装。

每条目录条目是一个包含以下内容的小型数据包：

• id — 简短的标识符（小写字母、数字、连字符、下划线，最多 64 个字符）。
• displayName — 人类可读的名称（最多 120 个字符）。
• description — 简短描述（最多 500 个字符）。
• preview — openpets.dev/pets/* 上预览图的 HTTPS URL。
• zip — zip.openpets.dev/pets/* 上可下载包的 HTTPS URL。

从桌面应用安装

这是最简单的方式。点击托盘图标，打开管理宠物...，选择一只宠物并点击安装。

1. 桌面应用通过 HTTPS 获取目录。
2. 从 zip.openpets.dev 下载宠物 ZIP 包。
3. 验证 ZIP 包并将其解压到用户数据目录。
4. 宠物出现在已安装列表中，并可设置为默认宠物。

每个平台上已安装宠物的具体存放目录，请参见 本地文件与配置。

从 CLI 安装

如果 OpenPets 桌面应用已在运行，你可以从终端安装宠物：

npx -y @open-pets/cli@latest install <pet-id>

CLI 通过本地 IPC 与运行中的应用通信，请求其执行安装操作。实际的下载和验证由桌面应用完成；CLI 仅负责转发请求并输出结果。

如果桌面应用未运行，此命令会输出明确的错误信息并失败。如需在不依赖应用的情况下安装，请使用下方的独立安装程序。

独立安装程序

在 CI、dotfile 引导，或任何无法确保 OpenPets 桌面应用正在运行的环境中，请使用独立的 install-pet 包：

npx -y install-pet <pet-id>

独立安装程序优先使用正在运行的应用，应用不可用时则直接下载。直接安装时：

• 在用户数据目录下获取每用户锁文件，防止两个安装程序同时运行。
• 通过 HTTPS 获取目录和宠物 ZIP 包。
• 写入前验证所有内容——请参见下方安全限制。
• 原子性地解压到 <userData>/pets/<pet-id>/ 并更新 OpenPets 状态文件。

本地 Codex 宠物

如果你正在创建自己的宠物，可以将其放入 ~/.codex/pets/ 目录，桌面应用会自动加载——无需访问目录服务器，无需打包成 ZIP。

~/.codex/pets/<pet-id>/
├── pet.json
├── spritesheet.webp
└── preview.webp   # 可选

文件夹名称必须与 pet.json 中的 id 字段完全一致。完整的 pet.json 结构和大小限制，请参见 宠物文件格式。

Codex 宠物用于开发阶段的测试。满意后，你可以将其发布到画廊——提交模板见 OpenPets GitHub 仓库。

管理已安装的宠物

宠物管理器窗口列出所有已安装的宠物，并支持：

• 将某只宠物设置为默认宠物（启动时显示的那只）。
• 从托盘显示或隐藏默认宠物。
• 暂停所有宠物（在演示或录屏时很有用）。
• 卸载不再需要的宠物。

内置宠物无法卸载——它是 OpenPets 在选定的默认宠物缺失或损坏时使用的兜底宠物。

安全限制

宠物 ZIP 包在写入磁盘前会经过验证。无论通过桌面应用还是独立安装程序安装，验证规则完全相同。

除大小限制外，验证器还会拒绝符号链接、路径逃逸宠物目录、不支持的压缩方式、加密条目和大小写冲突的文件名。与保留名称 builtin 相同的宠物 id 也会被拒绝。

概述

OpenPets 通过两个层次连接到助手：

两个层次都通过相同的本地 IPC 和 OpenPets 的工作原理 中描述的租约生命周期运作。

Claude Code

打开桌面应用的集成窗口，点击 Claude Code 卡片上的安装。这会安装用户范围的 MCP 服务器，并在 ~/.claude/openpets.md 写入一个小型托管指令文件，通过标记块从 ~/.claude/CLAUDE.md 导入。

钩子是同一卡片上的独立选装操作。它们会修改 ~/.claude/settings.json，为每个 Claude 生命周期事件（UserPromptSubmit、PreToolUse、PermissionRequest、Notification、Stop、StopFailure）添加 OpenPets 托管命令条目。

关于托管 JSON 的结构、钩子反应映射的工作方式、通过 openpets configure 进行的项目级配置以及故障排除，请参见专门的 Claude Code 集成页面。

OpenCode

OpenCode 集成会向你的 OpenCode 全局配置添加三项内容：一个 OpenPets MCP 条目、一个 OpenPets 插件引用，以及一个托管指令块。

OpenCode 插件接入编辑器的事件总线——聊天消息、工具执行事件——并将它们映射为宠物反应，与 Claude 的钩子机制类似。由于插件在 OpenCode 运行时内运行，除了在配置中启用插件外，无需修改任何设置文件。

全局配置与项目配置的区别、JSONC 感知配置写入方式以及托管指令块的结构，请参见 OpenCode 集成页面。

其他 MCP 客户端

任何支持 stdio MCP 服务器的助手都可以使用 OpenPets。将 OpenPets 服务器添加到你的客户端 MCP 配置中——具体命令和 JSON 示例见 MCP 服务器参考。

Cursor、VS Code（使用 MCP 插件）、Windsurf、Zed 和 Claude Desktop 均以此方式工作。部分客户端在添加 OpenPets 条目后需要重启；若工具未出现，请查阅相应客户端的 MCP 配置说明。

宠物路由

默认情况下，每个助手都将反应和消息发送至 OpenPets 默认宠物——即你在托盘菜单中选定的那只。如果你希望特定助手驱动特定的已安装宠物，请向 MCP 命令传入 --pet <pet-id>。

• 不传 --pet：所有内容路由至默认宠物。
• 传入 --pet：助手活跃时会打开一个独立的"代理宠物"窗口，助手停止时关闭。
• 若请求的宠物缺失、损坏或无效，OpenPets 将事件路由至默认宠物，并在状态响应中暴露回退原因。

桌面应用集成卡片上的宠物路由选择器会自动为你添加 --pet。如果你手动配置 MCP 客户端，请自行添加该标志。

移除集成

打开集成窗口，点击相应卡片上的移除集成。这会从你的助手配置中删除 OpenPets 托管的 MCP 条目和指令文件。

钩子需要从同一卡片上单独移除，因为它们存储在不同的设置文件中。如果你只是想停止自动反应，仅移除钩子即可，MCP 服务器会继续安装。

对于通过 openpets configure 安装的项目本地配置，请删除或重写项目的 .claude/settings.local.json 或 .opencode/ 目录。

概述

openpets CLI 与桌面应用使用相同的代码，打包为独立的终端工具。它可以做四件事：

通常情况下，你不需要手动运行 openpets mcp 或 openpets hook。它们是 Claude Code 和 OpenCode 集成在你点击桌面应用中的安装时写入助手配置的入口点。

如何调用

CLI 以 @open-pets/cli 包发布在 npm 上。没有单独的安装程序——桌面应用不会向你的 PATH 添加 openpets 可执行文件。请使用 npx 调用：

npx -y @open-pets/cli@latest <subcommand> [...args]

如果你希望使用永久的 openpets 命令，请使用 npm install -g @open-pets/cli 全局安装该包。下文用法块中的裸 openpets ... 语法描述的是子命令结构；若未全局安装，请将 openpets 替换为 npx -y @open-pets/cli@latest。

使用 -h 或 --help 运行任意子命令可查看摘要说明。

openpets install

通过向正在运行的桌面应用发送请求，从 OpenPets 目录安装宠物。桌面应用负责下载宠物 ZIP 包、验证并将其加入已安装列表。

openpets install <pet-id>

• <pet-id> 必须符合宠物 id 正则表达式（小写字母、数字、连字符、下划线；1–64 个字符；不能为 builtin）。
• OpenPets 桌面应用必须正在运行。如果应用未运行，安装会失败——请使用独立的 install-pet 包进行直接下载，无需应用即可安装。
• 安装请求使用较长的 60 秒响应超时，以适应较大的宠物包下载。

openpets configure

为特定项目配置 AI 助手。与桌面应用集成窗口提供的用户范围安装不同：openpets configure 写入项目本地配置，使设置可以随仓库一起分发。

openpets configure [--agent claude|opencode] [--pet <id>] [--cwd <path>]
                  [--yes] [--force] [--local-dev]

选项

configure 写入的内容

针对 Claude 项目：

• 通过 claude mcp add-json 在项目范围内添加一个 openpets MCP 条目。
• 在 <project>/.claude/settings.local.json 中为所有 Claude 生命周期事件写入 OpenPets 托管钩子条目。
• 钩子命令包含 --openpets-managed 标记和 --project-local 标志。

针对 OpenCode 项目：

• 在项目的 OpenCode 配置中写入一个 openpets MCP 条目。
• 写入 OpenPets 插件引用。
• 在项目的 .opencode/ 目录下写入托管指令文件。

OpenCode 配置可提交到版本库——你可以将其检入仓库，团队成员安装桌面应用后即可自动在该项目中使用 OpenPets。

安全

• 项目目录不能是符号链接，必须是真实目录。
• 如果 .claude 或 .claude/settings.local.json 已存在，它们不能是符号链接，且必须位于项目根目录内。
• 设置文件以原子方式写入（临时文件加重命名），权限为 0600。
• Claude 必须在 PATH 上——CLI 在执行任何操作前会调用 claude --version 进行检查。

openpets mcp

启动 OpenPets MCP 服务器。CLI 将 @open-pets/mcp 入口作为子进程启动并转发 stdio，使 MCP 客户端（Claude Code、Cursor 等）能够通过 stdin 和 stdout 直接与其通信。

openpets mcp [--pet <id>]

• --pet <id> 指向特定的已安装宠物。不传时，事件发送至默认宠物。
• 通常不需要手动运行此命令。集成配置会将类似 openpets mcp --pet <id> 的命令写入你助手的 MCP 配置。
• 服务器在启动时获取租约，每 5 秒发送一次心跳，并在收到 SIGINT 或 SIGTERM 时释放租约。

完整的工具接口、结构定义以及与其他 MCP 客户端的集成，请参见 MCP 服务器参考。

openpets hook

运行单个 Claude Code 钩子事件。Claude 将一个 JSON 事件通过 stdin 传入并等待命令退出；OpenPets 读取事件，决定反应或简短消息，然后静默退出。

openpets hook --openpets-managed [--project-local] [--pet <id>]

• --openpets-managed 是 CLI 在卸载或替换钩子时查找的标记。OpenPets 的每个钩子条目都必须包含此标记。
• --project-local 表示此钩子安装在项目范围（.claude/settings.local.json）。项目本地钩子单独跟踪，以便用户范围钩子跳过项目已处理的事件。
• --pet <id> 指向特定宠物。
• 钩子命令从不向 stdout 输出内容（以免 Claude 将其误作上下文），并始终以退出码 0 退出，除非 OpenPets 本身配置错误。如果桌面应用已关闭，钩子会成功且静默地退出。

退出码

openpets hook 是有意设计的例外：即使桌面应用不可用，它也会尽力以 0 退出，确保 Claude 会话不会因 OpenPets 问题而被阻塞。

环境变量

概述

OpenPets 自带一个 Model Context Protocol（MCP）服务器，允许任何支持 MCP 的助手驱动你的桌面宠物。它是一个小型、专用的接口：检查状态、切换宠物反应、显示简短消息，仅此而已。

服务器作为本地 stdio 进程运行。你的 MCP 客户端启动它，通过 stdin/stdout 传输 JSON-RPC，OpenPets 再通过本地 IPC 将请求转发给桌面应用。

MCP client (Claude, Cursor, Zed, ...)
  -> stdio
  -> @open-pets/mcp server
  -> @open-pets/client (token-stamped local IPC)
  -> OpenPets desktop app
  -> default pet or leased agent pet

快速安装

如果你的助手有专用的 OpenPets 集成卡片（目前为 Claude Code 或 OpenCode），请直接使用——它会为你的安装方式写入正确的命令并处理托管指令。否则，请手动将 OpenPets 作为 stdio MCP 服务器添加到你的客户端。

针对 Claude Code：

claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest

如需指向特定已安装的宠物，请在 @open-pets/mcp@latest 后添加 --pet <pet-id>。

服务器命令

服务器二进制文件以 @open-pets/mcp 名称发布在 npm 上，同时也捆绑在桌面应用内部。根据你使用的是发布包还是 OpenPets 版本中的捆绑包，命令形式有所不同。

发布包

npx -y @open-pets/mcp@latest [--pet <pet-id>]

桌面应用内的捆绑包

OpenPets 集成窗口会写入一个基于路径的命令，指向已安装的应用包内部，因此安装后无需访问网络即可使用。在 macOS 上命令如下：

node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/mcp/dist/index.js

参数标志

宠物 id 限制为 128 字节 UTF-8，不能包含控制字符、斜杠或反斜杠。id 还必须符合标准宠物 id 正则表达式（小写字母、数字、连字符、下划线）。

客户端配置示例

以下 JSON 片段展示了几种常见客户端的 OpenPets MCP 条目。将 <pet-id> 替换为你想要的宠物，或省略该标志以使用默认宠物。

Claude Code

{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp", "--pet", "<pet-id>"]
    }
  }
}

Cursor、Windsurf、通用 stdio MCP

{
  "mcpServers": {
    "openpets": {
      "command": "npx",
      "args": ["-y", "@open-pets/mcp"]
    }
  }
}

捆绑应用路径

如需跳过 npx，直接运行已安装 OpenPets 桌面应用中的 MCP 服务器，请使用此方式。

{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/mcp/dist/index.js"
      ]
    }
  }
}

工具

服务器注册了三个工具。输入结构在服务端通过 zod 进行强制校验；无效输入会返回工具错误，不会联系桌面应用。

输入结构

{}

{
  "reaction": "thinking"
}

{
  "message": "Building the pet manager",
  "reaction": "working"
}

反应与语音

反应从固定列表中选取。完整列表见 反应；允许的值为 idle、thinking、 working、editing、running、testing、waiting、waving、 success、error 和 celebrating。

语音消息须简短。服务器对每次 openpets_say 调用强制执行以下规则：

• 去除首尾空格后，长度在 1 到 140 个字符之间。
• 单行——回车和换行符会被拒绝。
• 不含代码类内容（反引号、<script、函数定义、JS 关键字如 class、import、const）。
• 不含 URL 或文件路径（HTTP URL、www.、斜杠路径、Windows 盘符）。
• 不含密钥类文本（api_key、secret、token、password、PEM 标头）。

拒绝原因以纯文本工具错误的形式返回。未通过验证的内容永远不会到达宠物。

验证与安全

MCP 服务器被设计为一个无害的可见状态通道。它有意无法读取你的编辑器状态、项目文件或助手的对话记录。

宠物指向与租约

宠物指向通过租约实现。底层生命周期请参见 租约与路由。在 MCP 服务器内部，其工作方式如下：

1. 服务器在启动时获取租约，将可选的 --pet <id> 作为请求的宠物传入。
2. 桌面应用选定实际宠物——若请求的宠物已安装且可用则使用该宠物，否则使用默认宠物并附上回退原因。
3. 每个反应和消息都包含租约 id，因此即使默认宠物也可见，事件仍会路由到租约对应的宠物。
4. 服务器每 5 秒发送一次心跳；若心跳失败，租约被标记为降级，工具调用会返回明确的"租约不可用"错误。
5. 收到 SIGINT 或 SIGTERM 时，服务器在关闭前释放租约。

如果请求的宠物缺失、损坏或无效，租约仍会被授予，但指向的是默认宠物。结构化状态响应通过 fallbackReason 暴露这一情况，以便谨慎的助手能够告知用户。

IPC 发现

MCP 服务器使用标准的 OpenPets 发现文件来定位桌面应用。文件格式和各平台路径请参见 本地 IPC。

在非常规环境中运行 MCP 服务器时，请注意以下两点：

• 发现文件的 platform 字段必须与 MCP 进程的平台一致。从 Linux VM 中使用 macOS 构建的 MCP 服务器连接 macOS 构建的桌面应用，发现验证会失败。
• 设置 OPENPETS_DISCOVERY_FILE 环境变量可覆盖发现路径——在 OpenPets 桌面应用以不同用户身份运行，或进行脚本化测试时很有用。

故障排除

MCP 服务器已启动，但每个工具都返回"OpenPets 不可用"

• 确认 OpenPets 桌面应用正在运行。
• 检查发现文件是否存在于你平台对应的预期路径。
• 如果你重启了桌面应用，发现令牌已轮换。请同时重启 MCP 客户端以获取新的租约。

工具返回"OpenPets 租约不可用"

• 启动时的租约获取失败或已过期。最常见的原因是 MCP 服务器启动时桌面应用未运行。
• 重启 MCP 客户端，服务器会在启动时重新尝试获取租约。

调用"成功"但宠物没有切换反应

• 检查默认宠物是否从托盘菜单中被暂停。暂停的宠物会静默接受反应。
• 如果你传入了 --pet <id>，而结构化状态显示有 fallbackReason，说明请求的宠物缺失或损坏——请重新安装。

openpets_say 消息被拒绝

• 出于安全原因，验证非常严格。请移除看起来像代码的内容、URL、路径或密钥类词语后重试。
• 如果你正在通过宠物发送堆栈跟踪、错误日志或文件路径，请不要这样做，使用单独的渠道传达这些信息。

非 MCP 路径特有的更广泛问题，请参见 故障排除。

包结构

一只宠物是一个包含元数据文件和精灵图的小型文件夹。在发布到画廊时，文件夹会被打包成 ZIP 并托管在 zip.openpets.dev 上。

<pet-id>/
├── pet.json
├── spritesheet.webp
└── preview.webp    # 可选，用作缩略图

文件夹名称必须与 pet.json 中的 id 完全一致。ZIP 内部没有特殊的"根目录"——条目直接位于归档的顶层。

pet.json

描述宠物的元数据文件。除非标注为可选，否则所有字段均为必填。

{
  "id": "my-pet",
  "displayName": "My Pet",
  "description": "A friendly companion that loves test suites.",
  "spritesheetPath": "spritesheet.webp"
}

精灵图

精灵图是一张单一的 WebP 图像，文件名由 spritesheetPath 指定。它包含你的宠物支持的所有反应的动画帧。

宠物不必实现所有反应。精灵图中没有对应帧的反应会回退到 idle。完整的反应列表见 反应列表。

可以参考现有画廊宠物（或 OpenPets 自带的内置宠物）的源码，了解精灵图布局示例。没有强制的单元格尺寸要求——桌面渲染器从宠物的精灵图元数据中读取帧坐标。

验证规则

OpenPets 在将每只宠物写入磁盘前都会进行验证。部分检查针对 ZIP 文件整体；部分检查针对内部的每个条目。

ZIP 级别限制

• 下载的 ZIP 不得超过 50 MB。
• 解压后的总大小不得超过 200 MB。
• 条目数量不得超过 500 个。
• 单个文件大小不得超过 100 MB。
• 开始解压前会验证 ZIP 魔数字节。

条目级别规则

• 路径必须保持在宠物目录内——不允许 .. 路径遍历。
• 不允许符号链接、加密条目和不支持的压缩方式。
• 大小写冲突会被拒绝（例如宠物包中不能同时存在 image.png 和 Image.png）。
• 条目的 Unix 模式必须是有效的文件或目录模式。

解压后的必需文件

宠物包必须包含 pet.json 和 spritesheetPath 中命名的文件。如果缺少其中任一，安装将被拒绝，不会向已安装宠物目录写入任何内容。

Codex（本地开发）宠物

开发阶段无需将宠物打包为 ZIP。将文件夹放入 ~/.codex/pets/，桌面应用会实时导入。

Codex 宠物的限制与 ZIP 宠物略有不同，因为它们以解压后的形式存储在磁盘上：

~/.codex/pets/ 中的文件夹名称必须与 pet.json 中的 id 一致。修改 Codex 宠物文件夹中的文件后，请重新加载 OpenPets。

发布宠物

宠物准备好后，请将其提交到 OpenPets 画廊。 OpenPets GitHub 仓库 中有宠物提交 issue 模板；请按要求填写元数据，并附上（或链接至）精灵图。通过审核的宠物会被添加到目录中，并可从桌面应用内直接安装。

仅托盘设计

OpenPets 没有传统的主窗口。应用驻留在系统托盘（Windows / Linux）或菜单栏（macOS）中。在 macOS 上，应用特意将自身从 Dock 中隐藏，使宠物成为唯一可见的存在。

所有操作——管理宠物、配置集成、更改设置、退出——均通过托盘菜单或其打开的短暂性"任务"窗口完成。

托盘菜单

托盘菜单根据应用状态显示不同的条目。完整条目按顺序如下：

宠物窗口

每只宠物在其专属的透明、无边框、始终置顶的 Electron 窗口中渲染。窗口没有任何界面装饰——只有精灵图及其透明背景，动画由 CSS 驱动。

默认宠物使用一个在整个会话期间持续存在的窗口。代理宠物各自拥有独立的短暂窗口，当助手请求时打开，当助手停止请求时关闭。

宠物窗口会追踪所在屏幕，并在启动之间记住其位置。

拖拽与点击穿透

你可以用鼠标在桌面上随意拖动宠物窗口。拖动之外，宠物窗口默认启用点击穿透，不会拦截针对其下方内容的点击操作。

拖拽功能和点击穿透开关通过一个小型预加载脚本实现，该脚本通过 Electron 的 contextBridge 向渲染器暴露有限的 API。渲染器本身在沙箱中运行，启用了上下文隔离，不集成 Node，并采用严格的 default-src 'none' CSP 策略。

任务窗口

任务窗口是从托盘菜单打开的短暂性 Electron 窗口，用于展示专注于单个任务的界面，完成后即关闭。

引导流程

OpenPets 首次启动时会自动打开引导窗口。完成（或跳过）引导后，应用会在状态文件中将引导标记为已完成，之后每次启动不再显示该窗口。

如果你跳过了引导并希望返回，可在引导状态仍为待完成时点击托盘菜单中的继续设置...。

更新检查

启动时，OpenPets 会查询 alvinunreal/openpets 仓库的 GitHub Releases API，检查是否有更新版本可用。检查在后台运行一次，并设有较短的超时时间。

若发现更新版本，托盘菜单会添加有可用更新条目，点击后在浏览器中打开发布页面。不会自动下载或安装任何内容。手动更新步骤请参见 更新。

单实例行为

OpenPets 使用 Electron 的单实例锁。如果你在应用已运行时再次启动，第二个实例会立即退出，正在运行的实例会将其托盘菜单最近打开的任务窗口置于最前。

这可以避免出现重复的托盘图标、重复的 IPC 服务器和重复的更新提示。

用户数据目录

OpenPets 将状态、已安装的宠物和运行时元数据统一保存在用户数据目录中。位置因平台而异。

你可以通过设置环境变量 OPENPETS_USER_DATA 来覆盖路径。覆盖适用于独立安装程序及所有使用用户数据路径的组件；桌面应用本身使用 Electron 的 app.getPath("userData")，遵循其自身的标准规则。

应用状态文件

应用状态文件 openpets-state.json 位于用户数据目录的根目录。它记录：

• 当前选定的默认宠物 id。
• 默认宠物是否在启动时打开，以及对话气泡是否启用。
• 宠物缩放偏好设置。
• 引导流程是否已完成。
• 可选的 Claude 和 OpenCode 命令路径（如果你设置了自定义二进制文件）。
• 已安装的宠物列表及其元数据。
• 默认宠物上次已知的位置。

对 openpets-state.json 的所有写入均以原子方式进行：OpenPets 先写入原始文件旁边的临时文件，再重命名到位。不存在部分写入的状态。

已安装的宠物

每只从画廊安装的宠物存放在 <userData>/pets/<pet-id>/ 下，目录中包含解压后的宠物包——pet.json、spritesheet.webp 以及可选的预览图。

本地开发的 Codex 宠物单独存放在 ~/.codex/pets/<pet-id>/ 下。桌面应用会同时读取这两个位置。

IPC 发现文件

桌面应用启动时会写入一个小型 JSON 文件，告知客户端（MCP 服务器、CLI、钩子）连接位置和所需令牌。该文件以 0600 权限存放在 0700 目录中。

在 Linux 上，仅当 $XDG_RUNTIME_DIR 是你拥有且权限为 0700 的真实目录时，才使用安全 XDG 位置；否则 OpenPets 回退到上述路径。

发现文件在每次桌面应用启动时包含一个新生成的令牌，旧令牌立即失效。

锁文件

• 单实例锁——Electron 内置锁；桌面应用运行期间自动持有。
• 直接安装锁——由独立的 install-pet 包使用，防止两个安装程序并发运行。位于 <userData>/.install-pet.lock。过期锁在 10 分钟后视为无效。
• Unix 套接字——在 macOS 和 Linux 上，实际 IPC 套接字文件位于 /tmp/openpets-<uid>/ 或 $XDG_RUNTIME_DIR/openpets/ 下。应用正常退出时删除。

Claude 托管文件

当你从桌面应用安装 Claude Code 集成时，OpenPets 会管理 ~/.claude/ 下的三个文件：

Claude 的 MCP 配置通过 claude mcp add-json 命令写入，而非直接编辑文件；条目以用户范围命名为 openpets。

通过 openpets configure 进行的项目本地 Claude 配置写入 <project>/.claude/settings.local.json。

OpenCode 托管文件

OpenCode 集成写入 OpenCode 的全局配置目录，通常为 ~/.config/opencode/。它在 OpenCode 配置文件中管理三项内容，另外还有一个独立的指令文件：

OpenCode 配置编辑使用 JSONC 解析器，因此现有注释和尾随逗号不会丢失。写入以原子方式进行并有备份。集成拒绝通过符号链接写入文件。

桌面应用未运行

大多数"OpenPets 不可用"错误意味着桌面应用已关闭或崩溃。

• 检查系统托盘（macOS 上为菜单栏）中是否有 OpenPets 图标。
• 如果图标消失，请重新启动应用。若应用仍在运行，单实例锁会将第二次启动路由到已有实例。
• 如果图标存在但工具仍然失败，发现令牌可能已轮换。请重启 MCP 客户端以获取新的租约。

Claude 不显示 OpenPets 工具

1. 安装或替换 MCP 配置后，请重启 Claude Code。
2. 在 OpenPets 中打开集成，点击 Claude 卡片上的刷新。
3. 在终端中运行 claude --version。CLI 必须在 PATH 上，OpenPets 才能检测到 Claude。如果二进制文件在其他位置，请在高级检测中设置完整路径。
4. 使用 claude mcp list 和 claude mcp get openpets 验证 MCP 条目。

OpenCode 没有反应

• 确认 OpenPets 正在运行。OpenCode 插件使用相同的本地 IPC，桌面应用关闭意味着没有反应。
• 确认 OpenPets 插件条目仍列在你的 OpenCode 配置中。如果被删除，可通过集成窗口重新添加。
• 反应受到频率限制。如果你最近已看过一次反应，下一个事件可能被静默——这是有意设计，不是 bug。

MCP 条目被报告为自定义

"自定义"表示 Claude（或 OpenCode）已有一个名为 openpets 的服务器，但其命令与 OpenPets 当前应写入的内容不匹配。OpenPets 在这种情况下会保留不动，避免覆盖你的自定义配置。

若要强制 OpenPets 重新创建条目，请打开集成卡片并点击替换配置。你之前的自定义命令将被覆盖。

宠物安装失败

• 检查宠物 id。须为小写字母、数字、连字符、下划线；最多 64 个字符；不能为 builtin。
• 确认宠物存在于画廊中。打开 openpets.dev/gallery 核对 id。
• 检查网络连接。目录和 ZIP 下载需要能通过 HTTPS 访问 openpets.dev 和 zip.openpets.dev。
• 如果独立的 install-pet 报告锁文件过期，请等待 10 分钟让锁自动过期，或在确认没有其他安装正在进行后手动删除 <userData>/.install-pet.lock。
• 验证器可能会拒绝格式有问题的宠物包。错误信息会指明失败的规则——符号链接、文件过大、缺少 pet.json、缺少精灵图等。

宠物未显示

• 在托盘菜单中检查显示默认宠物。如果显示的是隐藏默认宠物，说明宠物已显示——请查看其他显示器。
• 如果宠物处于暂停状态（托盘菜单中显示恢复所有宠物），请点击以恢复。
• 如果你通过 --pet 请求了特定宠物，请查看结构化状态响应。有 fallbackReason 说明该宠物缺失或损坏，事件已转发至默认宠物。
• 从宠物管理器重新安装受影响的宠物。

更新检查失败

更新检查会访问 GitHub Releases API，若网络较慢或受限则会迅速超时。检查失败不会影响正常使用——托盘菜单仅是不显示有可用更新条目。

• 如果你怀疑版本已过时，请直接访问 OpenPets GitHub 发布页面查看。
• 企业网络有时会屏蔽 api.github.com，检查在此情况下会静默失败。

反馈问题

如果按照本页步骤排查后问题仍然存在，请在 OpenPets GitHub 仓库 提交 issue。请包含以下信息：

• 你的操作系统和 OpenPets 应用版本（在设置窗口中可见）。
• 复现问题的确切步骤。
• 涉及的助手和集成（Claude Code、OpenCode 等）。
• 对于钩子相关问题，请提供使用 OPENPETS_DEBUG=1 运行钩子命令的输出。

请不要在 issue 中粘贴私密代码、密钥或完整对话记录。简短的错误信息和复现步骤通常已足够。

仓库结构

OpenPets 是一个 pnpm 工作区，包含两种顶层工作区模式：一种用于可部署的应用，一种用于可发布的包。

openpets/
├── apps/
│   └── desktop/        # Electron tray app
├── packages/
│   ├── agent-events/   # Speech pools + validation
│   ├── claude/         # Claude Code integration
│   ├── cli/            # `openpets` CLI
│   ├── client/         # Local IPC client
│   ├── install-pet/    # Standalone pet installer
│   ├── mcp/            # MCP server
│   ├── opencode/       # OpenCode integration
│   └── pet-format/     # Pet package marker type
└── web/                # openpets.dev (Nuxt 4)

每个工作区包均为 ESM（"type": "module"），使用 TypeScript 6 编写，目标运行环境为 Node ≥ 20。

环境搭建

安装 pnpm 11 和 Node 20+，然后执行：

pnpm install
pnpm build       # build all workspace packages
pnpm dev:desktop # run the desktop app in dev mode

桌面应用通过 workspace:* 依赖工作区包，因此在运行 dev:desktop 之前，需要先完整构建一次这些包。

常用命令

测试

OpenPets 采用轻量级契约式测试，而非重量级测试框架。每个包都有一个或多个 check-*.ts 文件，对包的公共接口进行端到端测试并断言预期行为。

• 契约文件在工作区根目录执行 pnpm test 时运行。
• 这些检查有意覆盖 IPC 协议、租约生命周期、ZIP 安全性、目录验证以及其他边界模块。
• 设计上快速且具有确定性——没有网络请求、没有 Electron 启动、没有测试框架。

发布：桌面应用

桌面版本从 macOS 上由单一编排脚本 apps/desktop/scripts/release-local.mjs 生成。它负责运行预检、构建，并从一台机器为 macOS、Windows 和 Linux 生成安装包。

默认构建计划：

可选标志可添加 macOS ZIP、Windows 便携版可执行文件、Linux .deb 或 tarball 构建，以及 Windows 和 Linux 的实验性 ARM64 构建。构建完成后，脚本会生成 SHA256SUMS 文件，使用 --yes 时还会创建 GitHub 草稿 Release 并上传产物。

发布：npm 包

工作区包独立发布。从仓库根目录运行 pnpm release:npm；编排器会构建、运行检查，并发布自上次发布以来版本号发生变化的每个包。

目前所有包共享 2.0.x 版本线，但各自拥有独立的 package.json 版本号，因此可以单独升级某个包而无需更新其他包。

延伸阅读

内部架构通过仓库内各目录的 codemap 文件记录，供贡献者参考，而非面向最终用户：

• 仓库根目录的 codemap.md——工作区高层架构概览。
• apps/desktop/src/codemap.md——Electron 应用的模块结构。
• packages/<name>/src/codemap.md——每个包的职责说明。

有关每个包的公开接口，请参见 包参考。

概述

OpenPets 拆分为多个小型、专注的 npm 包，以便集成和第三方工具只依赖所需的部分。在 monorepo 内部通过 workspace:* 链接；在 npm 上独立版本管理。

@open-pets/client

核心 IPC 客户端。每个需要与桌面应用通信的 OpenPets 包都使用它。

• 发现文件读取、端点验证、带令牌的请求。
• createOpenPetsClient() 工厂函数，返回 hello、status、listPets、installPet、acquireLease、heartbeatLease、releaseLease、react 和 say 方法。
• 强类型协议，带稳定错误码的自定义 OpenPetsClientError。

npm install @open-pets/client

@open-pets/cli

已发布的 npm CLI 包。每个命令的详细说明见 CLI 参考。

npx -y @open-pets/cli@latest configure --agent claude
# 可选的永久 shell 命令：
npm install -g @open-pets/cli

@open-pets/mcp

OpenPets MCP 服务器。stdio 传输、三个工具、租约感知生命周期。详见 MCP 服务器参考。

npx -y @open-pets/mcp@latest [--pet <pet-id>]

@open-pets/claude

Claude Code 集成包。包含钩子运行时、钩子设置管理器以及桌面应用和 CLI 使用的 MCP 配置辅助工具。

• runClaudeHookFromStdin()——执行单个 Claude 钩子事件。
• installClaudeHooks()、uninstallClaudeHooks()、doctorClaudeHooks()——管理 ~/.claude/settings.json。
• buildClaudeMcpPreview()、parseClaudeMcpGetOutput()、classifyClaudeMcpStatus()——检查 Claude MCP 配置。

@open-pets/opencode

OpenCode 集成包。包含 OpenPets OpenCode 插件以及项目/全局配置管理器。

• plugin.ts——OpenCode 使用的默认导出。
• prepareOpenCodeProjectSetup() / writePreparedOpenCodeProjectSetup()——原子性项目级配置写入。
• prepareOpenCodeGlobalSetup() / writePreparedOpenCodeGlobalSetup()——桌面应用使用的全局配置写入。

@open-pets/agent-events

共享语音池和验证器。Claude 钩子运行时和 OpenCode 插件都使用它，以确保所发送的消息风格一致并通过相同的安全规则。

• hookSpeechPools——按类别（thinking、success、error、permission）键入的只读记录。
• pickHookSpeech(category, randomFn)——安全地随机选取一条消息。
• validateHookSpeech(message)——拒绝看起来不安全的内容。

install-pet

用于安装单只宠物的独立 CLI。优先尝试正在运行的桌面应用；应用不可用时回退到直接下载。

npx -y install-pet <pet-id>

适用于 dotfiles、CI 引导以及任何无法确保 OpenPets 桌面应用已打开的场景。

@open-pets/pet-format

一个极小的标记包，为符合 OpenPets 宠物格式的包导出一个名义类型和常量。当你在 OpenPets 之上构建工具并希望在类型层面识别宠物包时可以使用它。

实际的宠物包结构定义位于桌面应用的目录验证器和 Codex 宠物验证器中——详见 宠物文件格式。

代码许可证

OpenPets 源代码依据 MIT 许可证 发布。该许可证适用于桌面应用、所有工作区包及网站源码。

MIT License
Copyright (c) 2026 OpenPets
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND...

宠物资源

宠物精灵图和预览图不在 OpenPets 代码许可证的覆盖范围内。每只宠物随其元数据一起发布；宠物创作者保留其艺术作品的权利，除非其明确以其他方式重新授权。

如需转载或改编特定宠物，请在操作前查看该宠物画廊页面上的许可说明或其 pet.json 元数据。

第三方软件

OpenPets 构建于众多优秀的开源项目之上。主要运行时依赖包括：

• Electron——桌面应用外壳。
• @modelcontextprotocol/sdk——MCP 服务器实现。
• yauzl——宠物包的流式 ZIP 解压。
• jsonc-parser——支持 JSONC 格式的 OpenCode 配置编辑。
• zod——MCP 服务器的运行时结构校验。
• highlight.js——本文档网站的代码高亮。
• Nuxt——驱动 openpets.dev 的框架。

每个依赖项均受其自身许可证约束。完整列表及对应许可证文本，请参见 OpenPets GitHub 仓库中的源代码。