fix: openclaw doctor reports DuplicateOpenClawRuntimeError (false positive)

[yujunos]

Pre-submission checklist | 提交前检查

• I have searched existing issues and this hasn't been mentioned before | 我已搜索现有问题，确认此问题尚未被提及
• I have read the project documentation and confirmed this issue doesn't already exist | 我已阅读项目文档并确认此问题尚未存在
• This issue is specific to MemOS and not a general software issue | 该问题是针对 MemOS 的，而不是一般软件问题

Bug Description | 问题描述

Bug Description

When the OpenClaw gateway is running with memos-local-plugin v2.0.6, openclaw doctor always reports:

[plugins] memos-local: duplicate OpenClaw runtime blocked
[plugins] memos-local-plugin failed during register from .../dist/adapters/openclaw/index.js: DuplicateOpenClawRuntimeError: memos-local OpenClaw runtime is already active (pid=<gateway_pid>)

How to Reproduce | 如何重现

The plugin works perfectly in the gateway — onTurnStart, onTurnEnd, and all memory tools function normally. Only openclaw doctor (a separate process) fails.

Root Cause

openclaw doctor is an independent process that also loads plugins. The acquireOpenClawRuntimeLock() function in runtime-lock.js does not distinguish between:

1. A legitimate duplicate runtime instance (should be blocked)
2. The openclaw doctor diagnostic process (should be allowed or skipped)

Steps to Reproduce

1. Install @memtensor/memos-local-plugin via install.sh
2. Start OpenClaw gateway (openclaw gateway start)
3. Run openclaw doctor → plugin registration fails with DuplicateOpenClawRuntimeError

Expected Behavior

openclaw doctor should either:

• Skip memory plugin registration (read-only health check)
• Use a different lock namespace for diagnostic processes
• Report "plugin active (OK)" instead of "plugin failed"

Environment

• Plugin: @memtensor/memos-local-plugin@2.0.6
• OpenClaw: 2026.5.28
• Node.js: v24.15.0
• OS: Ubuntu Linux 6.8.0-117-generic
• Install method: curl -fsSL .../install.sh | bash

Workaround

The plugin actually works fine. The doctor error is a false positive and can be ignored.

Environment | 环境信息

• Plugin: @memtensor/memos-local-plugin@2.0.6
• OpenClaw: 2026.5.28
• Node.js: v24.15.0
• OS: Ubuntu Linux 6.8.0-117-generic
• Install method: curl -fsSL .../install.sh | bash

Additional Context | 其他信息

No response

Willingness to Implement | 实现意愿

• I'm willing to implement this myself | 我愿意自己解决
• I would like someone else to implement this | 我希望其他人来解决

[Memtensor-AI]

🤖 AutoDev has picked up this issue and started working on it.

Task ID: dc00ae027a76d7f1
Working branch: autodev/MemOS-1873
Target branch: main
Workflow: opsp (analysis → coding → testing → PR)

I will post the PR link here once done. If I need more information, I will ask in the comments.

[Memtensor-AI]

🚀 AutoDev task dc00ae027a76d7f1 pushed commit.

Summary: ## Summary

Successfully fixed the false positive DuplicateOpenClawRuntimeError reported by openclaw doctor when the OpenClaw gateway is running with memos-local-plugin.

Root Cause

The runtime lock mechanism in apps/memos-local-plugin/adapters/openclaw/runtime-lock.ts was designed to prevent duplicate OpenClaw gateway instances from running simultaneously. However, it didn't distinguish between:

• A legitimate duplicate gateway runtime (should be blocked)
• The openclaw doctor diagnostic process (should be allowed)

When openclaw doctor tried to load the plugin while the gateway was running, it attempted to acquire the same runtime lock and was blocked with a false positive error.

Solution Implemented

Added diagnostic mode detection that allows read-only processes like openclaw doctor to skip runtime lock acquisition:

1. Runtime Lock Enhancement: Added skipLock?: boolean parameter to AcquireOpenClawRuntimeLockOptions. When true, acquireOpenClawRuntimeLock() returns a no-op lock handle that doesn't create lock files or block.

2. Diagnostic Mode Detection: Added isDiagnosticMode() helper function that detects diagnostic processes via:

   • OPENCLAW_DIAGNOSTIC_MODE environment variable (set to "1" or "true")
   • Process title containing "doctor"
   • Process argv containing "doctor"

3. Plugin Registration Update: Modified the register() function to detect diagnostic mode and pass skipLock: true to lock acquisition, with appropriate logging.

Changes Made

Modified Files:

• apps/memos-local-plugin/adapters/openclaw/runtime-lock.ts: Added skipLock parameter and no-op lock handling
• apps/memos-local-plugin/adapters/openclaw/index.ts: Added diagnostic mode detection and integration
• apps/memos-local-plugin/tests/unit/adapters/openclaw-runtime-lock.test.ts: Added unit tests for skipLock behavior
• apps/memos-local-plugin/tests/integration/diagnostic-mode.test.ts: New integration test verifying doctor can run alongside gateway

Test Coverage:

• Unit tests verify that skipLock returns no-op lock handles
• Integration tests confirm doctor process can run while gateway holds lock
• Existing tests ensure normal gateway lock behavior is unchanged

Verification

The fix is backward compatible and maintains all existing security properties:

• Normal gateway instances still block duplicate runtimes
• Diagnostic mode only activates when explicitly detected
• No lock files are created in diagnostic mode
• Gateway lock cleanup remains unchanged

Usage

Users can now run openclaw doctor while the gateway is active. The diagnostic process will automatically detect it's running in diagnostic mode and skip lock acquisition. Alternatively, users can explicitly set OPENCLAW_DIAGNOSTIC_MODE=1 to force diagnostic mode.

Base branch: main
Branch: autodev/MemOS-1873
Commit: bee2c8c

I will create the PR next and post the PR link here.

[Memtensor-AI]

✅ AutoDev task dc00ae027a76d7f1 completed.

Summary: ## Summary

Successfully fixed the false positive DuplicateOpenClawRuntimeError reported by openclaw doctor when the OpenClaw gateway is running with memos-local-plugin.

Root Cause

The runtime lock mechanism in apps/memos-local-plugin/adapters/openclaw/runtime-lock.ts was designed to prevent duplicate OpenClaw gateway instances from running simultaneously. However, it didn't distinguish between:

• A legitimate duplicate gateway runtime (should be blocked)
• The openclaw doctor diagnostic process (should be allowed)

When openclaw doctor tried to load the plugin while the gateway was running, it attempted to acquire the same runtime lock and was blocked with a false positive error.

Solution Implemented

Added diagnostic mode detection that allows read-only processes like openclaw doctor to skip runtime lock acquisition:

1. Runtime Lock Enhancement: Added skipLock?: boolean parameter to AcquireOpenClawRuntimeLockOptions. When true, acquireOpenClawRuntimeLock() returns a no-op lock handle that doesn't create lock files or block.

2. Diagnostic Mode Detection: Added isDiagnosticMode() helper function that detects diagnostic processes via:

   • OPENCLAW_DIAGNOSTIC_MODE environment variable (set to "1" or "true")
   • Process title containing "doctor"
   • Process argv containing "doctor"

3. Plugin Registration Update: Modified the register() function to detect diagnostic mode and pass skipLock: true to lock acquisition, with appropriate logging.

Changes Made

Modified Files:

• apps/memos-local-plugin/adapters/openclaw/runtime-lock.ts: Added skipLock parameter and no-op lock handling
• apps/memos-local-plugin/adapters/openclaw/index.ts: Added diagnostic mode detection and integration
• apps/memos-local-plugin/tests/unit/adapters/openclaw-runtime-lock.test.ts: Added unit tests for skipLock behavior
• apps/memos-local-plugin/tests/integration/diagnostic-mode.test.ts: New integration test verifying doctor can run alongside gateway

Test Coverage:

• Unit tests verify that skipLock returns no-op lock handles
• Integration tests confirm doctor process can run while gateway holds lock
• Existing tests ensure normal gateway lock behavior is unchanged

Verification

The fix is backward compatible and maintains all existing security properties:

• Normal gateway instances still block duplicate runtimes
• Diagnostic mode only activates when explicitly detected
• No lock files are created in diagnostic mode
• Gateway lock cleanup remains unchanged

Usage

Users can now run openclaw doctor while the gateway is active. The diagnostic process will automatically detect it's running in diagnostic mode and skip lock acquisition. Alternatively, users can explicitly set OPENCLAW_DIAGNOSTIC_MODE=1 to force diagnostic mode.

Base branch: main
Branch: autodev/MemOS-1873
Commit: bee2c8c
PR: #1874
Assigned to: @MatthewZhuang, @CarltonXiang, @syzsunshine219
Reviewers: @MatthewZhuang, @CarltonXiang, @syzsunshine219