OpenClaw + Hermes · Troubleshooting

# MemOS Local Plugin 安装排查 MemOS Local Plugin Troubleshooting

新版插件同时支持 OpenClaw 和 Hermes。排查时先确认你正在检查的是哪个宿主、哪个运行时目录、哪个 Viewer 端口。The current plugin supports both OpenClaw and Hermes. When debugging, first confirm which host, which runtime directory, and which Viewer port you are inspecting.

## 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

### OpenClaw

代码在 `~/.openclaw/extensions/memos-local-plugin/`，数据在 `~/.openclaw/memos-plugin/`，Viewer 是 `:18799`。Code lives at `~/.openclaw/extensions/memos-local-plugin/`, data at `~/.openclaw/memos-plugin/`, Viewer at `:18799`.

### Hermes

包和运行时在 `~/.hermes/memos-plugin/`，Python provider 通过 symlink 接入 Hermes，Viewer 是 `:18800`。Package and runtime live at `~/.hermes/memos-plugin/`; the Python provider attaches via symlink, Viewer at `:18800`.

## 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

没有 `--port` 参数。No `--port` flag. 新版端口固定：OpenClaw `18799`，Hermes `18800`。如果端口被占用，请先停掉旧进程，而不是给安装器传端口。The new ports are fixed: OpenClaw `18799`, Hermes `18800`. If a port is busy, kill the stale process instead of passing a port to the installer.

## 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

旧 ID 冲突：Legacy ID conflict: 如果看到 `memos-local-openclaw-plugin` 或 `memos-lite-openclaw-plugin`，它们是旧版单适配插件。新版安装器会从配置中移除旧 ID，但不会删除旧数据。If you see `memos-local-openclaw-plugin` or `memos-lite-openclaw-plugin`, those are legacy single-adapter plugins. The new installer removes legacy IDs from config but never deletes legacy data.

## 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

Viewer | URL | Health | 常见原因 Common Causes
--- | --- | --- | ---
OpenClaw | `http://127.0.0.1:18799` | `/api/v1/health` | gateway 未启动、插件未加载、端口被旧进程占用。Gateway not started, plugin not loaded, or port held by stale process.
Hermes | `http://127.0.0.1:18800` | `/api/v1/health` | bridge 未启动、provider 未加载、Hermes LLM 配置缺失。Bridge not started, provider not loaded, or missing Hermes LLM config.

## 7. 配置与 API key 7. 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

排障时不要把完整 API key 贴到 issue 或聊天里。Viewer 与日志会做脱敏，但终端命令输出不会自动脱敏。Do not paste full API keys into issues or chats. Viewer and logs redact secrets, but raw terminal output does not.

## 8. 日志位置 8. Log Locations

Agent | MemOS logs | Host logs
--- | --- | ---
OpenClaw | `~/.openclaw/memos-plugin/logs/` | `/tmp/openclaw/openclaw-*.log`, `/tmp/openclaw-memos-gateway.log`
Hermes | `~/.hermes/memos-plugin/logs/` | `~/.hermes/` 下的 Hermes 自身日志，视安装方式而定 Hermes' own logs under `~/.hermes/`, depending on install method

    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

不要直接删除 `~/.hermes/memos-plugin`，Do not delete `~/.hermes/memos-plugin` directly, 除非你已经备份并确认可以同时移除 Hermes 的 MemOS 数据库、配置、日志和技能包。unless you have backed up and intentionally want to remove Hermes' MemOS database, config, logs, and skills together.