安装 C/C++ 编译工具
遇到安装问题？按以下步骤逐一排查
在终端依次运行以下命令，快速判断问题所在：
# 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
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!
缺少依赖通常是网络问题。手动安装：
cd ~/.openclaw/extensions/memos-local-openclaw-plugin npm install --omit=dev
better-sqlite3 编译失败，参见下一节。
这是最常见的安装问题。better-sqlite3 是一个需要 C/C++ 编译的原生 Node.js 模块。
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
...
安装 C/C++ 编译工具
# macOS xcode-select --install # Ubuntu / Debian sudo apt install build-essential python3 # Windows npm install -g windows-build-tools
重新编译 better-sqlite3
cd ~/.openclaw/extensions/memos-local-openclaw-plugin npm rebuild better-sqlite3
验证是否成功
node -e "require('better-sqlite3'); console.log('✔ OK')"
重启 gateway
openclaw gateway stop && openclaw gateway start
如果使用非 LTS 版本的 Node.js（如 v25.x），better-sqlite3 可能没有预编译的二进制文件，必须从源码编译。确保已安装上述编译工具。
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 脚本自动迁移。
error [plugins] memos-local-openclaw-plugin failed during register:
Error: Could not locate the bindings file.
这几乎都是 better-sqlite3 的问题，按照第 3 节的步骤修复即可。
插件内置了自愈机制——启动时会自动尝试 npm rebuild better-sqlite3，但如果系统没有编译工具，自愈也会失败。
通常是新安装时数据库为空或 store 未初始化。升级到最新版本即可解决：
openclaw plugins update memos-local-openclaw-plugin
尝试强制刷新浏览器缓存：Ctrl+Shift+R（macOS: Cmd+Shift+R）
openclaw plugins update memos-local-openclaw-plugin
升级过程会自动运行 postinstall 脚本，处理依赖安装、旧版清理和原生模块编译。
# 必须先删除旧目录，否则 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，独立于插件目录。
openclaw gateway stop && openclaw gateway start
# 查看当天完整日志 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 发给开发者排查。
cd ~/.openclaw/extensions/memos-local-openclaw-plugin node scripts/postinstall.cjs 2>&1 | tee /tmp/postinstall-debug.log
如果以上方法都无法解决，可以完全重装（不会丢失记忆数据）：
# 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，不在插件目录内，重装不会影响。
这通常是 better-sqlite3 正在编译。首次编译可能需要 30-60 秒，取决于网络和机器性能。如果超过 2 分钟，按 Ctrl+C 中断，然后手动运行：
cd ~/.openclaw/extensions/memos-local-openclaw-plugin npm install --omit=dev npm rebuild better-sqlite3
需要安装 Xcode 命令行工具：
xcode-select --install
安装完成后重新运行 npm rebuild better-sqlite3。
浏览器缓存了旧版本页面。强制刷新：Ctrl+Shift+R（macOS: Cmd+Shift+R）。
所有记忆数据存储在 ~/.openclaw/memos-local/memos.db（SQLite 文件），独立于插件安装目录。升级、重装插件都不会影响数据。
建议定期备份：
cp ~/.openclaw/memos-local/memos.db ~/memos-backup-$(date +%Y%m%d).db
cat ~/.openclaw/extensions/memos-local-openclaw-plugin/package.json | grep version
同一个 plugin ID 被多个目录加载。检查是否有重复的插件目录：
ls ~/.openclaw/extensions/ | grep memos
只保留 memos-local-openclaw-plugin，删除其他的：
rm -rf ~/.openclaw/extensions/memos-local # 如果存在