MemOS Local Plugin 安装排查MemOS Local Plugin Troubleshooting

1. 快速诊断1. Quick Check

先跑下面的命令，确认安装目录、数据库、Viewer 和核心依赖状态。Run the following commands to verify install directory, database, Viewer, and core dependencies.

# Host homes
test -d ~/.openclaw && echo "OpenClaw home OK"
test -d ~/.hermes && echo "Hermes home OK"

# OpenClaw install/runtime
ls ~/.openclaw/extensions/memos-local-plugin 2>/dev/null
ls ~/.openclaw/memos-plugin 2>/dev/null

# Hermes runtime/package
ls ~/.hermes/memos-plugin 2>/dev/null
ls ~/.hermes/memos-plugin/adapters/hermes 2>/dev/null

# Viewer health
curl -fsS http://127.0.0.1:18799/api/v1/health || true
curl -fsS http://127.0.0.1:18800/api/v1/health || true

2. 安装器没有检测到宿主2. Installer Cannot Detect Host

安装器根据 ~/.openclaw 与 ~/.hermes 判断宿主是否存在。交互式安装时可以手动选择；非交互环境会自动安装到检测到的宿主。The installer detects hosts via ~/.openclaw and ~/.hermes. Interactive runs let you pick manually; non-interactive runs install into whatever is detected.

# Re-run from repository checkout
cd apps/memos-local-plugin
bash install.sh

# Show installer help
bash install.sh --help

3. Node.js / better-sqlite3

插件要求 Node.js 20+。Node 25+ 往往没有 better-sqlite3 预编译二进制，会走源码编译；如果失败，建议切换 Node LTS。Plugin requires Node.js 20+. Node 25+ often lacks better-sqlite3 prebuilt binaries and falls back to building from source; if that fails, switch to Node LTS.

node -v

# OpenClaw package check
cd ~/.openclaw/extensions/memos-local-plugin
node -e "require('better-sqlite3'); console.log('better-sqlite3 OK')"

# Hermes package check
cd ~/.hermes/memos-plugin
node -e "require('better-sqlite3'); console.log('better-sqlite3 OK')"

更多平台细节见 better-sqlite3 官方排查文档。For platform details, see the official better-sqlite3 troubleshooting docs.

4. OpenClaw 插件未加载4. OpenClaw Plugin Not Loading

OpenClaw 安装流程会部署包、生成 openclaw.plugin.json，并 patch ~/.openclaw/openclaw.json 的 memory slot。OpenClaw install deploys the package, writes openclaw.plugin.json, and patches the memory slot in ~/.openclaw/openclaw.json.

test -f ~/.openclaw/extensions/memos-local-plugin/openclaw.plugin.json
test -f ~/.openclaw/extensions/memos-local-plugin/dist/adapters/openclaw/index.js

修改后重启 OpenClaw gateway：Restart the OpenClaw gateway after changes:

openclaw gateway stop
openclaw gateway start

5. Hermes provider / bridge 问题5. Hermes Provider / Bridge Issues

Hermes 适配器由 Python provider 加载，再启动或连接 bridge.cts。最常见问题是 provider symlink 没建立、Hermes Python 环境不一致、bridge 旧进程占用端口。The Hermes adapter is loaded by a Python provider that starts or connects to bridge.cts. Common failures: missing provider symlink, mismatched Hermes Python env, or stale bridge holding the port.

ls ~/.hermes/memos-plugin/adapters/hermes/memos_provider
test -f ~/.hermes/memos-plugin/bridge.cts
pgrep -af "bridge.cts" || true
lsof -nP -iTCP:18800 -sTCP:LISTEN || true

如需重启 Hermes bridge，优先重新运行安装器；它会停止旧 bridge、重新部署 provider 并等待 Viewer。To restart the Hermes bridge, prefer rerunning the installer: it stops the old bridge, redeploys the provider, and waits for Viewer.

6. Viewer 无法访问6. Viewer Unreachable

7. 配置与 API key7. Config and API Keys

config.yaml 是唯一运行时配置文件。OpenClaw 默认可使用 llm.provider: host 复用宿主模型；Hermes 没有 host LLM，通常需要配置真实 LLM provider 与 API key。config.yaml is the only runtime config. OpenClaw can default to llm.provider: host and reuse the host model; Hermes has no host LLM and usually needs a real LLM provider plus API key.

sed -n '1,120p' ~/.openclaw/memos-plugin/config.yaml
sed -n '1,120p' ~/.hermes/memos-plugin/config.yaml

8. 日志位置8. Log Locations

rg -i "error|fail|warn" ~/.openclaw/memos-plugin/logs ~/.hermes/memos-plugin/logs

9. 升级与旧插件9. Upgrade and Legacy Plugins

旧版包名和插件 ID 包含 memos-local-openclaw-plugin，新版统一为 @memtensor/memos-local-plugin / memos-local-plugin。升级时安装器会清理 OpenClaw 配置里的旧 ID，防止两个记忆插件争用 memory slot。Legacy package and plugin IDs use memos-local-openclaw-plugin; the current name is @memtensor/memos-local-plugin / memos-local-plugin. The installer cleans legacy IDs from OpenClaw config to prevent two memory plugins competing for the same slot.

curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh | bash
rg "memos-local-openclaw-plugin|memos-lite" ~/.openclaw/openclaw.json || true

10. 安全重装10. Safe Reinstall

安全重装只删除代码包和 provider 链接，不删除数据库、技能、日志和配置。A safe reinstall removes only code packages and provider symlinks; databases, skills, logs, and config stay intact.

rm -rf ~/.openclaw/extensions/memos-local-plugin
cp -a ~/.hermes/memos-plugin ~/.hermes/memos-plugin.backup.$(date +%Y%m%d-%H%M%S)
cd apps/memos-local-plugin
bash install.sh