openclaw - 💡(How to fix) Fix Bug: Gateway false positive warnings about qmd collections in v2026.3.31 [1 participants]

Description

After upgrading to OpenClaw v2026.3.31 and installing qmd CLI as a backup memory backend, the Gateway continuously reports false positive warnings about qmd collections, even though no qmd collections actually exist in the system.

Environment

• OpenClaw Version: v2026.3.31
• OS: macOS 26.4 (arm64)
• Node: v25.8.2
• qmd Version: v2.0.1 (installed via bun install -g https://github.com/tobi/qmd)
• Memory Plugin: OpenViking (context engine slot, working normally)

Configuration

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "update": {
        "interval": "5m",
        "onBoot": true,
        "waitForBootSync": false
      }
    }
  },
  "plugins": {
    "slots": {
      "contextEngine": "openviking"
    },
    "entries": {
      "openviking": {
        "enabled": true,
        "config": {
          "mode": "remote",
          "baseUrl": "http://127.0.0.1:1933",
          "autoCapture": true,
          "autoRecall": true
        }
      }
    }
  }
}

Timeline

1. Initial Warning After Upgrade (14:51:47)

14:51:47+08:00 [memory] qmd binary unavailable (qmd); falling back to builtin: spawn qmd ENOENT

Root Cause: Gateway process doesn't load user's ~/.zshrc, so it couldn't find qmd even though it was installed and working in user shell.

Resolution: Added BUN_INSTALL environment variable and PATH configuration to ~/.zshrc:

export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

2. False Positive Collection Warning After Restart (16:26:21)

16:26:21 warn memory qmd collection add skipped for memory-alt-agent-codex: 
qmd collection add /Users/neoshi/.openclaw/workspace --name memory-alt-agent-codex --glob memory.md failed (code 1): 
A collection already exists for this path and pattern:
  Name: memory-root-agent-codex (qmd://memory-root-agent-codex/)
  Pattern: **/*.md

Use 'qmd update' to re-index it, or remove it first with 'qmd collection remove memory-root-agent-codex'

Investigation Results

✅ qmd CLI is Working Correctly

$ qmd --version
qmd 2.0.1

$ qmd collection list
No collections found. Run 'qmd collection add .' to create one.

$ cd ~/.openclaw && qmd collection list
No collections found. Run 'qmd collection add .' to create one.

$ cd ~/.openclaw/workspace && qmd collection list
No collections found. Run 'qmd collection add .' to create one.

$ find ~ -name ".qmd" -type d 2>/dev/null
(no results)

$ ls -la ~/.qmd/
ls: /Users/neoshi/.qmd/: No such file or directory

✅ No Actual qmd Collections Exist

• No global ~/.qmd/ configuration directory
• No local .qmd/ directories in ~/.openclaw or ~/.openclaw/workspace
• qmd collection list returns empty in all tested directories

❌ Gateway Still Reports "Collection Already Exists"

The warning persists even after:

1. ✅ qmd CLI installed and working (v2.0.1)
2. ✅ PATH properly configured in ~/.zshrc
3. ✅ Gateway restarted to inherit updated environment
4. ✅ Verified no collections exist via qmd collection list

Analysis

This appears to be a race condition or false positive in OpenClaw v2026.3.31's qmd integration:

1. Gateway startup sequence: When Gateway starts with memory.backend: "qmd", it attempts to create a qmd collection for the workspace
2. Possible duplicate creation attempt: The code may try to create the same collection twice during initialization
3. Error handling issue: The second attempt fails with "collection already exists", but this is reported as a warning even though no actual collection exists in qmd's state

Impact

• OpenViking functionality: ✅ Unaffected (uses plugin slot, independent of memory.backend)
• Auto-capture: ✅ Working normally (313 files indexed)
• Memory retrieval: ✅ Working normally
• User experience: ⚠️ Warning messages in logs (cosmetic only)

Suggested Fixes

1. Add existence check before collection creation: Verify if collection actually exists via qmd collection list before attempting to create
2. Improve error handling: Distinguish between actual duplicate collections and transient states
3. Add retry logic: If collection creation fails, verify actual state before reporting error
4. Consider Gateway environment: Ensure Gateway process inherits proper PATH or uses absolute paths for qmd binary

Workaround

Users can temporarily ignore this warning as it doesn't affect actual functionality when using OpenViking plugin. Alternatively, switch memory.backend to "builtin" to suppress qmd-related warnings.

Additional Context

• qmd is an external CLI tool (not built-in), requires separate installation
• OpenViking plugin operates independently via plugins.slots.contextEngine
• This issue appears specific to v2026.3.31's qmd integration code