OpenPets 标志OpenPets
← 返回集成
OpenCode

集成指南

已支持

OpenCode + OpenPets

通过 OpenPets 插件、MCP 工具、全局桌面设置、项目本地设置、宠物路由以及安全托管指令，将 OpenCode 连接到 OpenPets。

此集成的功能

OpenCode 集成将 OpenCode 的活动连接到你的 OpenPets 桌面伴侣。它由两部分组成：一个用于自动反应的 OpenCode 插件，以及一个用于主动调用 OpenPets 工具的 MCP server。

组成部分功能说明重要性
OpenCode 插件 监听 OpenCode 活动，将有用的事件映射为宠物反应。 宠物可以自动呈现思考、编辑、测试、等待、成功或错误状态。
MCP server 向 OpenCode 注册 OpenPets MCP 工具。 OpenCode 可以主动调用 openpets_status、openpets_react 和 openpets_say。
托管指令 为 OpenPets 使用添加简短的安全引导。 OpenCode 知道要保持可见宠物消息简短且无敏感内容。

运行时控制在本地进行。OpenCode 加载 OpenPets 插件或 MCP 命令，这些包使用 @open-pets/client，客户端通过本地 IPC 与 OpenPets 桌面应用通信并更新宠物窗口。

快速安装

在 OpenPets 桌面应用中，打开 Integrations，使用 OpenCode 卡片。该卡片是针对单台机器的简单设置路径：点击 Install 写入全局 OpenCode 设置，或点击 Configure 先查看详情。

OpenPets 集成窗口，显示准备安装的 OpenCode 卡片。
集成网格。OpenCode 已激活并准备就绪；Install 开始全局设置，Configure 则打开详细设置面板。
  • Install 为插件、MCP server 和 OpenPets 指令写入全局 OpenCode 配置。
  • Configure 打开详细的全局设置页面，包含宠物路由、命令检测、安装/移除、刷新和配置预览。
  • 设置更改后重启 OpenCode，以加载插件和 MCP 配置。

桌面设置是全局的，可能影响该机器上的每个 OpenCode 项目。如需针对特定仓库的设置，请改用项目本地 CLI 命令。

全局桌面设置

OpenCode 详情面板仅管理全局设置。它会检测 OpenCode，显示 OpenPets 全局配置是否已安装，允许你选择宠物，并在写入前预览 JSON。

OpenCode 设置详情页，显示全局设置状态、宠物路由、高级检测、安装和移除按钮，以及配置预览。
全局设置面板。在安装前使用它检查目标配置文件、所选宠物、命令路径和 JSON 预览。
面板区域用途修改内容
全局连接 显示 OpenCode 是否被检测到，以及全局 OpenPets 设置的状态：已安装、就绪、自定义、冲突或错误。 读取 OpenCode 命令状态和全局 OpenCode 配置文件。
宠物路由 选择 OpenCode 应指向的已安装宠物。 将宠物 ID 添加到插件选项和 MCP 命令中。
高级检测 当 opencode 不在 PATH 中时，允许你保存完整的 OpenCode 命令路径。 用于检测和设置检查。
预览 显示配置文件、指令文件、清理路径和 JSON 预览。 允许你在安装前审核计划中的全局配置。

除非 @open-pets/opencode 已被缓存或在本地安装，否则 OpenCode 可能需要 npm 或网络访问来加载已发布的插件。

自定义建议

  • 当你希望 OpenPets 在每个 OpenCode 项目中都可用时，使用全局设置。
  • 在安装前选择宠物，这样所有全局 OpenCode 活动都会指向同一个伴侣。
  • 使用配置预览确认将要写入的具体文件。
  • 如果你的 OpenCode 二进制文件安装在非标准 PATH 位置，使用命令路径字段。

项目本地设置

当仓库需要拥有自己的 OpenPets 配置时，项目本地设置是更好的选择。它将插件配置和指令保存在项目中，使不同的仓库可以指向不同的宠物或策略。

项目设置bash
npx -y @open-pets/cli@latest configure --agent opencode --pet <pet-id> --cwd .
设置方式适合场景文件位置
全局桌面设置 个人机器范围的 OpenCode 设置。 OpenCode 配置目录，例如 ~/.config/opencode/。
项目本地 CLI 设置 需要明确携带 OpenPets 设置的仓库。 .opencode/opencode.jsonc 和 .opencode/openpets.md。

如果同时存在全局设置和项目设置，请优先使用项目本地配置处理仓库特定行为，全局设置仅作为默认值。

托管配置与指令

OpenPets 使用托管标记或可预测的配置结构写入插件、MCP 和指令条目。在可能的情况下使用 JSONC 感知编辑，以保留现有注释和尾随逗号。

OpenCode 配置

项目本地配置通过 OpenPets CLI 加载 OpenPets 插件并启动 OpenPets MCP server。已发布的设置会固定其写入的 OpenPets 包版本。

.opencode/opencode.jsoncjson
{
  "plugin": [["@open-pets/opencode@<version>", { "pet": "<pet-id>" }]],
  "mcp": {
    "openpets": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@open-pets/cli@<version>",
        "mcp",
        "--pet",
        "<pet-id>"
      ],
      "enabled": true
    }
  }
}

npm 插件包为 @open-pets/opencode。该包导出的运行时插件 ID 为 open-pets-opencode。

OpenPets 指令

OpenPets 会写入一个小型指令文件，使 OpenCode 能安全且有节制地使用可见宠物消息。请将你自己的备注添加到托管块之外。

.opencode/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 only for brief, user-facing, non-sensitive status updates.
- Do not include code, logs, secrets, URLs, file paths, prompts, or private data.
- Use openpets_react for small visual progress changes.
- Use openpets_status only when checking availability or the targeted pet.
- Do not spam every internal step.
<!-- OPENPETS:END -->

自定义建议

  • 在 OpenPets 托管块之外添加项目特定的 OpenCode 规则。
  • 通过使用不同的 --pet 重新运行设置，为每个仓库固定一个宠物。
  • 仅当你有意刷新 OpenPets 托管条目时，才使用 --force。

插件事件反应

插件监听 OpenCode 事件，并将有意义的时刻转化为宠物反应。它会忽略 OpenPets MCP 工具调用，避免宠物对自身状态更新产生反应。

OpenCode 事件触发条件反应语音
chat.message任意聊天消息。thinking无
tool.execute.before工具名称包含 edit、write、patch 或 apply_patch。editing无
tool.execute.before类 shell 工具且参数看起来像测试命令。testing无
permission.asked非 OpenPets 工具的权限请求。waitingApproval needed
session.errorOpenCode 会话错误。error简短错误池消息
session.status状态变为 idle。success无

Shell/测试检测是有意设计为粗粒度的。工具参数仅用于分类反应，不会被复制到对话气泡中。

MCP 工具

MCP server 为 OpenCode 提供了一种主动与 OpenPets 通信的方式。当 OpenCode 需要有意地显示状态（而非仅响应生命周期事件）时使用 MCP。

工具用途适用场景
openpets_status检查桌面可达性和目标宠物。设置检查和调试。
openpets_react在不显示语音的情况下更改反应。静默进度状态。
openpets_say显示一条简短的安全消息。有意义的进度通知、阻塞提示、完成或审核交接。

保持语音简短且无敏感内容。不要在宠物气泡中放入代码、日志、文件路径、命令输出、提示词、URL、令牌或私有数据。

宠物路由

如果未配置宠物，OpenCode 事件会指向桌面默认宠物。如果配置了宠物 ID，插件和 MCP 命令会指向该宠物。

运行时路径text
OpenCode
  -> OpenPets plugin or OpenPets MCP tools
  -> @open-pets/client
  -> OpenPets desktop local IPC
  -> default pet or selected agent pet
  • 未配置宠物：使用桌面默认宠物。
  • 已配置已安装的宠物：使用显式代理宠物租约。
  • 宠物缺失、无效或损坏：回退到默认宠物。
  • 租约关闭或到期：最后一个租约结束后，代理宠物窗口关闭。

安全性与行为

OpenCode 集成采用即发即忘模式。如果 OpenPets 已关闭，它不应拖慢 OpenCode 或改变 OpenCode 的行为。

保护机制行为说明
反馈循环OpenPets MCP 工具调用被插件事件映射器忽略。
语音冷却普通语音和错误语音均受节流限制。
权限语音权限消息有其自己的更短冷却时间。
重复反应相同的反应会被短暂抑制，避免刷屏。
调试日志路径和类密钥值会被脱敏处理。
配置编辑原子写入、备份、权限检查、符号链接拒绝和大小限制。

故障排查

OpenCode 没有反应

  • 确认 OpenPets 桌面应用正在运行。
  • 更改插件或 MCP 配置后重启 OpenCode。
  • 检查你的全局或项目 OpenCode 配置中是否包含 OpenPets 插件和 MCP server。
  • 使用桌面详情页的 Refresh 操作重新检查全局设置。

状态显示自定义或冲突

在强制更新前先检查 OpenCode 配置。将你自己的备注保留在 OPENPETS:START 和 OPENPETS:END 之外，这样 OpenPets 才能安全刷新其托管块。

出现了错误的宠物

使用你想要的宠物 ID 重新运行设置。如果该宠物未安装、无效或损坏，桌面应用会回退到默认宠物。

刷新项目设置bash
npx -y @open-pets/cli@latest configure --agent opencode --pet <pet-id> --cwd . --force
Alvin 制作