Skip to main content
If something feels broken, this page tells you where to look first.

​
What this means in practice

Common problems include:
  • bad or missing API keys
  • wrong backend or MCP URL
  • Docker or port conflicts in local Docker Convex mode
  • stale OpenClaw plugin installs
  • local environment files missing
  • public docs repo / mirror / Mintlify mismatch

​
How it actually works

The best operational troubleshooting sources are:
  • scripts/crystal-doctor.sh
  • README.md
  • mcp-server/README.md
  • packages/mcp-server/README.md

​
Commands / examples

openclaw plugins info crystal-memory confirms that OpenClaw can see and load the installed plugin. openclaw crystal_status and openclaw crystal_doctor are available after an install-script OpenClaw install. The npm run ... commands require running from a Memory Crystal source checkout.

​
Common mistakes

  • assuming every failure is a code bug instead of an environment issue
  • skipping the doctor script and debugging blind
  • forgetting that Mintlify/public-repo issues are deployment-source issues, not plugin/runtime issues

​
Source of truth

Primary files behind this page:
  • scripts/crystal-doctor.sh
  • README.md
  • .env.example
  • mcp-server/README.md
  • packages/mcp-server/README.md

​
Local-first checks

When local-first mode fails, check these before reinstalling:
  • Docker is installed and the daemon is running.
  • Ports 3210, 3211, and 6791 are free on 127.0.0.1.
  • The installed backend artifact under ~/.memorycrystal/local-backend/<version> has a passing doctor command:
  • The client config points to the local endpoint only for clients you accepted during install.
  • Hosted Memory Crystal auth/license validation still succeeds before local credential provisioning.
If a config mutation failed, restore the backup path printed by the installer and re-run the installer in cloud or local mode.