opencode 安装 API 不匹配

你会遇到什么

在 opencode 里安装 claude-mem 插件报 API 不匹配 / 加载失败。别急着怀疑自己操作错了——这是 opencode 插件 API 与 claude-mem 插件实现版本不一致（CSDN 2026-05 案例），插件的主形态是 Claude Code，opencode 形态兼容性由上游推进。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

opencode 与 Claude Code 的插件 API 不完全一致，claude-mem 的实现按 Claude Code 的 API 版本走；两边版本对不上时 opencode 侧就加载失败。上游没有承诺 opencode 首发兼容，所以这不是安装姿势问题。

插件不是“一个文件拷过去就能跑”，它要对接客户端暴露的插件 API（生命周期钩子、工具注册、上下文接口等）。API 是版本化的：客户端升级会加新接口或改签名，插件按旧接口写的实现就会加载失败。

claude-mem 的实现跟着 Claude Code 的 API 版本走，opencode 的 API 和 Claude Code 不完全一致——两边版本一对不上，opencode 侧在加载阶段就报 API 不匹配，这是“客户端-插件契约”层面的不兼容，不是安装姿势问题。

由此得出两个确定性判断：一是判断插件版本别用 claude-mem --version（那是 npm CLI 的版本号），要看插件目录 ~/.claude/plugins/cache/thedotmack/claude-mem/<ver>（双轨版本号）；二是 opencode 场景的修复路径只能是“等上游更新”或“换兼容实现”，因为契约在别人手里。

本市场未实测 opencode 形态（无登录态），如实标注；Claude Code 形态已完整实测（安装/卸载全链路，2026-08-28）。

一步步来

1. 确认客户端场景 — 必做

Claude Code（插件主形态）：正常安装使用，本市场实测安装/卸载全链路通过（install exit=0 → uninstall 零残留）。

2. opencode 场景 — 必做

• 等待插件更新后再试 opencode 形态；
• 或替换为兼容实现（如官方支持的 memory 方案）。

3. 版本核对 — 必做

排查/升级判断以插件目录 ~/.claude/plugins/cache/thedotmack/claude-mem/<ver> 为准，不要用 claude-mem --version 当插件版本（npm CLI 12.4.7 ≠ 插件 13.16.1，双轨版本号）。

怎么确认修好了

claude-mem doctor && claude-mem status

Claude Code 场景 worker 就绪即成功（实测安装后 Worker port: 37700、Installation Complete、exit=0）。

其它环境的表现

症状

opencode 下安装 claude-mem 插件报 API 不匹配/加载失败。

原因

opencode 插件 API 与 claude-mem 插件实现版本不一致（CSDN 2026-05 案例）。

解法

1. 替换兼容实现，或优先在 Claude Code 场景使用（插件主形态）。
2. 等待插件更新后再试 opencode 形态。