## 1. 快速诊断命令

在终端依次运行以下命令，快速判断问题所在：

    # 1) 插件目录是否存在
    ls ~/.openclaw/extensions/memos-local-openclaw-plugin/

    # 2) better-sqlite3 原生模块是否可用
    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    node -e "require('better-sqlite3'); console.log('✔ better-sqlite3 OK')"

    # 3) 核心依赖是否完整
    node -e "['@sinclair/typebox','uuid','posthog-node'].forEach(d=>{try{require.resolve(d);console.log('✔',d)}catch{console.log('✖',d)}})"

    # 4) 运行 postinstall 脚本查看完整诊断
    node scripts/postinstall.cjs

    # 5) 查看 gateway 日志中的插件相关信息
    grep -i "memos\|plugin.*error\|plugin.*fail" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

## 2. 运行 postinstall 脚本

postinstall 脚本会自动检测并修复常见问题。进入插件目录后运行：

    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    node scripts/postinstall.cjs

正常输出应该包含三个阶段，每个都显示 `✔`：

    ─── Phase 0: 检测核心依赖 / Check core dependencies ───
      @sinclair/typebox ✔
      uuid ✔
      posthog-node ✔
      @huggingface/transformers ✔
    ✔ All core dependencies present.

    ─── Phase 1: 清理旧版本插件 / Clean up legacy plugins ───
    ✔ No legacy plugin directories found. Clean.

    ─── Phase 2: 检查 better-sqlite3 原生模块 / Check native module ───
    ✔ better-sqlite3 is ready.

    ✔ Setup complete!

⚠ 如果 Phase 0 失败

缺少依赖通常是网络问题。手动安装：

    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    npm install --omit=dev

⚠ 如果 Phase 2 失败

better-sqlite3 编译失败，参见下一节。

## 3. better-sqlite3 编译失败

这是最常见的安装问题。`better-sqlite3` 是一个需要 C/C++ 编译的原生 Node.js 模块。如果以下步骤无法解决你的问题，请参考 better-sqlite3 官方排查文档 获取更多平台特定的解决方案。

### 错误表现

    Error: Could not locate the bindings file. Tried:
     → .../node_modules/better-sqlite3/build/better_sqlite3.node
     → .../node_modules/better-sqlite3/build/Release/better_sqlite3.node
     ...

### 解决步骤

1

安装 C/C++ 编译工具

    # macOS
    xcode-select --install

    # Ubuntu / Debian
    sudo apt install build-essential python3

    # Windows — 通常不需要！
    # better-sqlite3 对 Windows + Node.js LTS 提供预编译二进制文件，
    # 大部分情况下可直接安装成功。
    # 如果仍然失败，安装 Visual Studio Build Tools:
    # https://visualstudio.microsoft.com/visual-cpp-build-tools/
    # 安装时勾选 "C++ build tools" 工作负载

2

重新编译 better-sqlite3

    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    npm rebuild better-sqlite3

3

验证是否成功

    node -e "require('better-sqlite3'); console.log('✔ OK')"

4

重启 gateway

    openclaw gateway stop && openclaw gateway start

💡 Node.js 版本说明

如果使用非 LTS 版本的 Node.js（如 v25.x），`better-sqlite3` 可能没有预编译的二进制文件，必须从源码编译。确保已安装上述编译工具。

推荐使用 Node.js LTS 版本（v18.x 或 v20.x），这些版本有预编译的二进制文件，通常不需要本地编译。

💡 更多排查资源

如果上述方法均无法解决，请查看以下资源：

- better-sqlite3 官方排查指南 — 包含所有平台的详细编译问题解决方案
- better-sqlite3 Issues — 搜索你的具体错误信息
- MemOS GitHub Issues — 提交问题或搜索已知问题

## 4. Plugin ID Mismatch 警告

### 错误表现

    warn plugin id mismatch (manifest uses "memos-local-openclaw-plugin",
         entry hints "memos-lite-openclaw-plugin")

### 原因

旧版本插件（`memos-lite-*`）的残留目录或配置未清理。

### 解决方法

    # 运行 postinstall 脚本自动清理（推荐）
    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    node scripts/postinstall.cjs

    # 或手动清理旧目录
    rm -rf ~/.openclaw/extensions/memos-lite
    rm -rf ~/.openclaw/extensions/memos-lite-openclaw-plugin

然后检查配置文件中是否有旧条目：

    cat ~/.openclaw/openclaw.json | grep -i "memos-lite"

如果有，删除对应的配置条目，或直接运行 postinstall 脚本自动迁移。

## 5. 插件加载失败 (register error)

### 错误表现

    error [plugins] memos-local-openclaw-plugin failed during register:
    Error: Could not locate the bindings file.

### 解决方法

这几乎都是 `better-sqlite3` 的问题，按照第 3 节的步骤修复即可。

插件内置了自愈机制——启动时会自动尝试 `npm rebuild better-sqlite3`，但如果系统没有编译工具，自愈也会失败。

## 6. Memory Viewer 页面报错

### Scan failed: Cannot read properties of undefined

通常是新安装时数据库为空或 store 未初始化。升级到最新版本即可解决：

    openclaw plugins update memos-local-openclaw-plugin

### 页面显示 undefined 或数据为空

尝试强制刷新浏览器缓存：`Ctrl+Shift+R`（macOS: `Cmd+Shift+R`）

## 7. 升级问题

### 升级命令（推荐）

    openclaw plugins update memos-local-openclaw-plugin

升级过程会自动运行 postinstall 脚本，处理依赖安装、旧版清理和原生模块编译。

### 如果 update 不可用，重新安装

    # 必须先删除旧目录，否则 install 会报 "plugin already exists"
    rm -rf ~/.openclaw/extensions/memos-local-openclaw-plugin
    openclaw plugins install @memtensor/memos-local-openclaw-plugin

💡 为什么要先删除？

OpenClaw 的 `plugins install` 命令检测到目标目录已存在时会直接拒绝安装，不会运行任何脚本。这是 OpenClaw 框架的安全机制，插件自身无法绕过。

✔ 数据安全

升级不会删除已有的记忆数据。数据库位于 `~/.openclaw/memos-local/memos.db`，独立于插件目录。

### 升级后 gateway 未加载新版本

    openclaw gateway stop && openclaw gateway start

## 8. 查看日志

### Gateway 运行日志

    # 查看当天完整日志
    cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

    # 只看插件相关
    grep -i "memos" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

    # 只看错误
    grep -i "error\|fail\|warn" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i "memos\|plugin"

    # 实时追踪（debug 用）
    tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i "memos"

### 重新启动并捕获完整启动日志

    openclaw gateway stop
    openclaw gateway start 2>&1 | tee /tmp/gateway-debug.log

然后将 `/tmp/gateway-debug.log` 发给开发者排查。

### postinstall 诊断日志

    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    node scripts/postinstall.cjs 2>&1 | tee /tmp/postinstall-debug.log

## 9. 完全重装

如果以上方法都无法解决，可以完全重装（不会丢失记忆数据）：

    # 1) 卸载
    openclaw plugins uninstall memos-local-openclaw-plugin

    # 2) 确认旧目录已删除
    rm -rf ~/.openclaw/extensions/memos-local-openclaw-plugin
    rm -rf ~/.openclaw/extensions/memos-lite
    rm -rf ~/.openclaw/extensions/memos-lite-openclaw-plugin

    # 3) 重新安装
    openclaw plugins install @memtensor/memos-local-openclaw-plugin

    # 4) 重启 gateway
    openclaw gateway stop && openclaw gateway start

✔ 数据保留

记忆数据存储在 `~/.openclaw/memos-local/memos.db`，不在插件目录内，重装不会影响。

## 10. 常见问题

### Q: 安装时一直卡在 "Installing plugin dependencies..." 不动

这通常是 `better-sqlite3` 正在编译。首次编译可能需要 30-60 秒，取决于网络和机器性能。如果超过 2 分钟，按 `Ctrl+C` 中断，然后手动运行：

    cd ~/.openclaw/extensions/memos-local-openclaw-plugin
    npm install --omit=dev
    npm rebuild better-sqlite3

### Q: macOS 提示 "xcrun: error: invalid active developer path"

需要安装 Xcode 命令行工具：

    xcode-select --install

安装完成后重新运行 `npm rebuild better-sqlite3`。

### Q: 升级后 Memory Viewer 显示异常

浏览器缓存了旧版本页面。强制刷新：`Ctrl+Shift+R`（macOS: `Cmd+Shift+R`）。

### Q: 我的数据在哪？安全吗？

所有记忆数据存储在 `~/.openclaw/memos-local/memos.db`（SQLite 文件），独立于插件安装目录。升级、重装插件都不会影响数据。

建议定期备份：

    cp ~/.openclaw/memos-local/memos.db ~/memos-backup-$(date +%Y%m%d).db

### Q: 如何确认插件版本？

    cat ~/.openclaw/extensions/memos-local-openclaw-plugin/package.json | grep version

### Q: 任务摘要/技能生成/去重 LLM 调用失败

所有 LLM 调用使用三级自动降级链：`skillSummarizer` → `summarizer` → OpenClaw 原生模型。

- 检查 gateway 日志中的 `failed` 和 `trying next` 信息
- 确认 API Key 和 Endpoint 配置正确
- 如果所有模型都失败，功能会降级为规则方法或跳过
- 可通过 Viewer → Settings 在线修改模型配置，保存后立即生效

### Q: 任务划分不准确（过度切分或不切分）

任务边界检测使用逐轮 LLM 话题判断：

- 确认 `summarizer` 模型已正确配置且可用
- 更强的 LLM 模型（如 GPT-4、Claude）会有更好的话题判断效果
- 如果判断效果不理想，可尝试配置 `skillSummarizer` 使用更强的模型
- 查看 gateway 日志中的 `Topic judge` 日志确认 LLM 是否被正确调用

### Q: duplicate plugin id detected 警告

同一个 plugin ID 被多个目录加载。检查是否有重复的插件目录：

    ls ~/.openclaw/extensions/ | grep memos

只保留 `memos-local-openclaw-plugin`，删除其他的：

    rm -rf ~/.openclaw/extensions/memos-local  # 如果存在