Claude Code + OpenPets

此集成的功能

Claude Code 集成将 Claude 连接到你的 OpenPets 桌面伴侣。它有一个基本安装路径，以及两个你可以在之后检查或自定义的高级层。

组成部分	是否必需？	为 Claude 提供的功能
MCP server	是	名为 `openpets_status`、`openpets_react` 和 `openpets_say` 的工具。
指令 / 提示词引导	是	告知 Claude 何时使用 OpenPets，以及哪些内容绝不能出现在可见的宠物消息中。
Hooks	可选	由 Claude 生命周期事件触发的自动反应，即使 Claude 未调用 MCP 工具时也能生效。

所有运行时通信均在本地进行。Claude 启动 OpenPets 相关包，这些包通过本地 IPC 与 OpenPets 桌面应用通信，桌面应用负责管理宠物窗口。如果 OpenPets 已关闭，Claude Code 仍可正常运行；宠物更新属于尽力而为的反馈。

快速安装

在 OpenPets 桌面应用中，打开 Integrations，使用 Claude Code 卡片。此卡片适用于普通用户流程：点击 Install，如果 Claude Code 已打开则重启它，Claude 即可开始使用 OpenPets MCP 工具。

OpenPets 集成窗口，显示已安装的 Claude Code 卡片和其他编辑器集成卡片。 — 集成网格是简单的设置视图。Install 负责处理 Claude MCP 连接和托管指令；Configure 则打开高级详情。

Install 会添加名为 openpets 的 Claude MCP server，并更新 OpenPets Claude 指令。
Configure 会打开高级 MCP、指令、hook、宠物路由和命令检测控制面板。
Installed 表示 Claude 已有 OpenPets MCP 连接。

快速安装不会安装 hooks。Hooks 是有意分开的，因为它们会修改 Claude Code 的 hook 设置，并为 Claude 事件添加自动反应。

MCP 连接

MCP 是 Claude 与 OpenPets 之间的主要桥梁。OpenPets 注册一个名为 openpets 的 Claude MCP server。Claude 加载后，即可在想要在桌面宠物上显示状态时调用一套小型安全工具集。

Claude Code 详情页，显示连接状态、宠物路由、高级检测、替换和删除操作，以及高级 MCP 详情部分。 — MCP 连接卡片显示 Claude 检测、宠物路由、替换/删除控制，以及高级 MCP 命令和 JSON 预览。

工具	用途	Claude 应在何时使用
`openpets_status`	检查 OpenPets 桌面应用是否可达，以及当前目标宠物是哪个。	在使用 OpenPets 之前，或在调试设置时。
`openpets_react`	在不显示文本的情况下更改宠物反应。	用于静默状态变化，如思考、编辑、测试、等待、成功或错误。
`openpets_say`	显示一条简短的可见对话气泡。	用于有意义的进度通知、阻塞提示、完成通知或审核交接。

在打包的桌面构建版本中，高级 MCP JSON 预览使用应用内置的 OpenPets MCP server：

Claude MCP JSON 预览json

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

在已发布包模式下，命令更简短，使用 npm：

已发布命令bash

claude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest --pet <pet-id>

自定义建议

在 Pet routing 中选择特定宠物，以附加 --pet <pet-id>。
如果 claude 命令不在 PATH 中，使用 Advanced detection。
仅当你希望 OpenPets 重新创建自定义 openpets MCP 条目时，才使用 Replace configuration。
如果你想精确审核 Claude 将运行的内容，使用 JSON 预览。

Claude 指令 / 提示词引导

MCP 为 Claude 提供工具。指令则告诉 Claude 如何使用这些工具，同时避免将私有上下文泄露到可见的桌面气泡中。这也是基本安装会写入托管 OpenPets 指令文件的原因。

OpenPets 将其引导内容写入 ~/.claude/openpets.md，并向 ~/.claude/CLAUDE.md 添加一个托管导入。现有 Claude 指令会被保留。

~/.claude/CLAUDE.mdmd

<!-- OPENPETS:IMPORT:START -->
@~/.claude/openpets.md
<!-- OPENPETS:IMPORT:END -->

~/.claude/openpets.mdmd

<!-- OPENPETS:START -->
## OpenPets
OpenPets MCP tools may be available.
Use OpenPets as a short visible status channel for meaningful coding progress:
    - Use `openpets_say` when starting, completing, blocking, or needing review on non-trivial work.
    - Keep messages brief, user-facing, and non-sensitive.
    - Do not include code, logs, secrets, URLs, or file paths.
    - Use `openpets_react` for small visual or emotional feedback.
    - Use `openpets_status` only when checking availability or the targeted pet.
    - Do not spam every internal step.
<!-- OPENPETS:END -->

消息风格

良好的宠物消息	应避免的内容
`Checking the next step.`	私有文件路径或仓库结构。
`Tests are running.`	原始命令输出或日志。
`Waiting for approval.`	用户提示词、密钥、令牌或 URL。
`Ready with the result.`	代码片段或完整的错误堆栈。

自定义建议

在 CLAUDE.md 中的 OpenPets 托管块之外添加你自己的团队风格规则。
将 OpenPets 块专注于隐私保护和简短状态消息。
如果以后移除 OpenPets，托管导入和托管块可以被干净地删除。

可选的 Claude Hooks

Hooks 是可选的自动化功能。它们让 Claude 生命周期事件能触发宠物反应，无需 Claude 显式调用 MCP 工具。仅在你希望宠物在 Claude 工作时自动响应的情况下安装。

Claude 事件	触发时机	宠物反应	语音
`UserPromptSubmit`	用户提交提示词时。	`thinking`	无
`PreToolUse`	`Edit`、`Write` 或 `MultiEdit` 时。	`editing`	无
`PreToolUse`	`Bash` 命令看起来像测试命令时。	`testing`	无
`PermissionRequest`	Claude 请求审批时。	`waiting`	简短审批消息
`Notification`	Claude 发出通知时。	无	无
`Stop`	Claude 完成响应时。	`success`	无
`StopFailure`	Claude 终止失败时。	`error`	简短错误消息

Hook 命令标记有 --openpets-managed。OpenPets 使用该标记来仅更新或删除自己的 hooks，而不影响与 OpenPets 无关的 Claude Code hooks。

Hooks JSON 预览json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/claude/dist/cli.js hook --openpets-managed",
            "timeout": 3,
            "async": true,
            "asyncRewake": false
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/claude/dist/cli.js hook --openpets-managed",
            "timeout": 3,
            "async": true,
            "asyncRewake": false
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/claude/dist/cli.js hook --openpets-managed",
            "timeout": 3,
            "async": true,
            "asyncRewake": false
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/claude/dist/cli.js hook --openpets-managed",
            "timeout": 3,
            "async": true,
            "asyncRewake": false
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/claude/dist/cli.js hook --openpets-managed",
            "timeout": 3,
            "async": true,
            "asyncRewake": false
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Applications/OpenPets.app/Contents/Resources/app.asar.unpacked/node_modules/@open-pets/claude/dist/cli.js hook --openpets-managed",
            "timeout": 3,
            "async": true,
            "asyncRewake": false
          }
        ]
      }
    ]
  }
}

自定义建议

如果你希望每个 Claude 会话都有环境感知反应，使用 hooks。
如果你只希望 Claude 通过 MCP 工具有意识地使用 OpenPets，则跳过 hooks。
在安装 hooks 之前先在路由中选择宠物，这样 hook 事件才会指向特定的伴侣。
在更新 Claude Code 或移动 OpenPets 应用后，运行 Check hooks。

宠物路由与自定义

未选择宠物时，Claude 会指向 OpenPets 的默认宠物。选择宠物后，OpenPets 会在 MCP 和 hook 命令中添加 --pet <pet-id>，使 Claude 指向该伴侣。

运行时路径text

Claude Code
  -> OpenPets MCP server or Claude hook CLI
  -> @open-pets/client
  -> OpenPets desktop local IPC
  -> default pet or selected agent pet

未选择宠物：MCP 工具和 hooks 指向桌面默认宠物。
已选择宠物：命令中包含 --pet <pet-id>。
显式宠物会话使用短租约，代理宠物可自动清理。
如果请求的宠物缺失或不可用，OpenPets 会安全回退，而不会中断 Claude。

安全性与行为

OpenPets 专为可见状态而设计，而非私有对话输出。它保持消息简短，避免敏感内容，并使 hook 失败不阻塞主流程。

保护机制	行为说明
托管指令	告知 Claude 避免在宠物语音中包含代码、日志、URL、文件路径、密钥和用户提示词。
语音验证	在不安全文本到达桌面宠物之前予以拒绝。
Hook 标准输出	Hook 命令保持静默，避免 Claude 意外摄入上下文。
Hook 错误	默认忽略，确保宠物问题不会中断 Claude 会话。
冷却机制	重复的 hook 语音和反应会被节流，避免刷屏。
安全写入	OpenPets 在编辑 Claude 文件之前，会拒绝不安全的符号链接或非常规文件目标。

故障排查

Claude 未显示 OpenPets 工具

安装或替换 MCP 配置后重启 Claude Code。
打开 Claude 详情页，点击 Refresh。
在终端运行 claude --version 确认 Claude 可用。
使用 claude mcp list 和 claude mcp get openpets 检查条目。
如果 Claude 安装在自定义位置，请在 Advanced detection 下添加完整路径。

OpenPets 提示 MCP 条目为自定义

自定义条目意味着 Claude 已有一个名为 openpets 的 server，但其命令与当前 OpenPets 推荐不完全匹配。OpenPets 不会主动修改它。仅当你希望桌面应用重新创建该条目时，才选择 Replace configuration。

宠物对 hooks 没有反应

确认 OpenPets 桌面应用正在运行。
确认已从可选的 Claude hooks 卡片安装了 hooks。
检查 hook 命令中是否包含 --openpets-managed。
请记住，大多数 hook 事件仅有反应，故意不显示语音。

移除或重置所有内容

使用 Remove integration 移除名为 openpets 的 Claude MCP server 和 OpenPets 托管的 Claude 指令。如果你安装了可选的 hooks，请单独使用 Remove hooks。