bug fix: Node.js v24 has a breaking change

[jdanjohnson]

Before You Start

Use Node.js v22 LTS (not v24)

This is the most important step. Node.js v24 has a breaking change (DEP0190) that crashes the QMD memory backend on startup. If you see red qmd collection add failed (code 1) errors when running openclaw gateway, your Node version is the issue.
Fix:

# Using nvm (macOS/Linux):
nvm install 22
nvm use 22
# Using nvm-windows:
nvm install 22
nvm use 22

Verify: node --version should show v22.x.x.

Install OpenClaw

npm install -g openclaw@latest
openclaw --version   # should be v2026.2.19 or later

---

Setup Steps

1. Clone the repo:

   git clone https://github.com/jdanjohnson/Openclaw-AI-Assistant-Project.git
   cd Openclaw-AI-Assistant-Project

2. Configure environment:

   cp .env.example .env

   Edit .env — at minimum you need:
   • GOOGLE_API_KEY — get a free key from Google AI Studio
   • VAULT_PATH — path to your Obsidian vault (e.g., C:\Users\you\Documents\MyVault on Windows)
   • Gmail credentials are optional for now — you can add those later for email management
3. Install plugin dependencies:

   cd agent/plugins/core
   npm install

4. Start the gateway:

   cd agent
   openclaw gateway

   Wait for listening on ws://... before opening the dashboard.

   Note: OpenClaw reads openclaw.json from the current directory. There is no --config flag. Always cd agent first.

5. Start the dashboard (optional):

   cd dashboard
   npm install
   npm run dev

   Open http://localhost:5173
6. Verify:

   openclaw doctor

---

Windows-Specific Tips

• Terminal encoding: If you see garbled characters in error output, run chcp 65001 before starting the gateway.
• Paths: Avoid spaces in your project path (use C:\Projects\Openclaw-AI-Assistant-Project, not C:\My Projects\...).
• IPv6 issues: If the dashboard can't connect, try changing ws://localhost:18789 to ws://127.0.0.1:18789 in dashboard/.env.

---

Common Issues

What you see	What's wrong	Fix
qmd collection add failed (code 1)	Node.js v24+	Downgrade to Node.js v22 LTS
WebSocket drops immediately	QMD failed to start	Fix QMD errors first (Node version)
TypeError: Cannot read properties of undefined	Cascading from QMD	Same — fix Node version
DeprecationWarning [DEP0190]	Node.js v24 deprecation	Downgrade to Node.js v22
Dashboard shows "Disconnected"	Gateway not running yet	Start gateway first, wait for "listening on"
GOOGLE_API_KEY is not set	Missing .env	Copy .env.example to .env, add your key

---

What You Can Test Without Gmail

Even without Gmail OAuth set up, you can:

• Chat with the agent (requires GOOGLE_API_KEY)
• Create and manage tasks (requires VAULT_PATH)
• Use the dashboard UI
  Email triage, follow-ups, and drafting require Gmail credentials — see the README for OAuth setup instructions when you're ready.

---

Need Help?

Open an issue on the GitHub repo with:

• Steps to reproduce
• Expected vs actual behavior
• Your environment (Node version, OS, OpenClaw version)
  Happy building!