Skip to main content
If something isn’t working, start with the doctor command — it checks your installation and reports what’s misconfigured: 
npm run crystal:doctor
For a quick end-to-end health check: 
npm run test:smoke
If those don’t surface the issue, find your problem below.
The plugin fails to load if the extension directory or entry point is missing.Check:
  1. Confirm the extensions directory exists: 
    ls ~/.openclaw/extensions/crystal-memory/
  2. Confirm index.js is present in that directory.
  3. Confirm the plugin is enabled in ~/.openclaw/openclaw.json: 
    {
  "plugins": {
    "entries": {
      "crystal-memory": {
        "enabled": true
      }
    }
  }
}
Fix: Re-run the bootstrap to reinstall plugin files and repair wiring:
npm run crystal:bootstrap
Conversations are not being captured to memory.Check:
  1. Confirm plugins.allow in ~/.openclaw/openclaw.json includes "crystal-capture": 
    {
  "plugins": {
    "allow": ["crystal-capture"]
  }
}
  2. Confirm you restarted the OpenClaw gateway after making config changes.
Fix: Add "crystal-capture" to plugins.allow and restart the gateway:
openclaw gateway restart
Do not restart the gateway from within an active OpenClaw session — it will terminate the session.
The gateway logs a message like “config reload skipped” or “invalid config”.Cause: You have an unrecognized key in plugins.entries. Valid plugin entry fields are enabled and config only. The keys source and path are not valid and will cause the config to be rejected.Fix: Remove any source or path keys from the plugin entry:
{
  "plugins": {
    "entries": {
      "crystal-memory": {
        "enabled": true
      }
    }
  }
}
Validate after editing:
jq empty ~/.openclaw/openclaw.json && echo "JSON valid"
Memory Crystal returns authentication errors or rejects your API key.Check:
  • Your key starts with the correct prefix (not a placeholder like your-api-key-here)
  • You’re using MEMORY_CRYSTAL_API_KEY or CRYSTAL_API_KEY — both are accepted
  • The key hasn’t been revoked in the dashboard
Fix: Generate a new key from the dashboard and update it in your config or environment.
You’re seeing 401 errors but you set your API key to "local".Cause: Using "local" as the API key activates local-only mode. In this mode, the plugin uses a local SQLite store and does not connect to the remote backend. Remote features — including cloud recall, dashboard sync, and cross-session memory — are unavailable.This is expected behavior, not a misconfiguration. If you want remote memory, set a real API key from the dashboard.
Local mode is useful for offline use or privacy-sensitive environments where you don’t want any data leaving your machine.
The doctor command checks your full installation — env vars, plugin files, wiring, and backend connectivity.
npm run crystal:doctor
For a lighter smoke test:
npm run test:smoke
Both commands report what’s missing or misconfigured with actionable output.
If your installation is in a broken or partial state, re-running bootstrap will repair it.
npm run crystal:bootstrap
Bootstrap re-initializes your .env, reinstalls dependencies, rebuilds the MCP server, re-wires the plugin, and runs a final verification check. It’s safe to run multiple times.

​
Still stuck?

If none of the above resolves your issue, check the gateway log for plugin registration messages and error output. The gateway log is the most reliable source of truth for what happened at startup.