Openclaw local plugin 20260408

[Hun-ger]

Description

This PR introduces UX enhancements for model configurations, improves the server shutdown lifecycle, and fixes a critical issue where multiple Viewer instances were being spawned concurrently due to OpenClaw lifecycle mismatch.

Key Changes:

1. Multiple Viewer Instances Fix (Fixes [Bug] Memory Viewer starts twice on OpenClaw startup (port 18799 → 18800 fallback) #1422, [memos-local] Viewer self-starts multiple times — duplicate instances on every gateway start #1425, memos-local-openclaw-plugin@1.0.8 self-start viewer repeats under host lifecycle mismatch, causing port drift (18799→18800+), Memory unavailable #1430):
   • The Problem: Previously, the plugin's Viewer could self-start multiple times during OpenClaw's initialization or hot-reloads. This led to duplicate instances, port drifting (e.g., 18799 → 18800+), resource waste, and occasionally caused the Memory service to be reported as unavailable despite a fixed port configuration.
   • The Solution: Introduced a global singleton state (globalRef.__memosLocalPluginActiveService) to ensure the service startup is idempotent across repeated register/init cycles. The self-start fallback logic was also refactored to conditionally trigger based on process.argv arguments (ensuring it only auto-starts for gateway, start, or restart commands), completely preventing orphan instances and port accumulation.
2. Model Configuration Warnings: Added visual warning banners in the Viewer UI (Settings and Main view) to alert users when critical models (Embedding, Summarizer, Skill Evolution) are missing or using the built-in mini model. This helps prevent degraded memory retrieval and processing experiences.
3. Graceful Shutdown: Refactored ViewerServer.stop() to be asynchronous, utilizing server.closeAllConnections() to ensure all active connections are properly closed and releasing the singleton lock before shutting down the process.

Related Issue (Required): Fixes #1430, Fixes #1425, Fixes #1422

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactor (does not change functionality, e.g. code style improvements, linting)
• Documentation update

How Has This Been Tested?

• Unit Test
• Test Script Or Test Steps (please provide)
  • Multiple Instances Fix: Started OpenClaw gateway and verified that the Viewer only starts once on the configured port. Triggered OpenClaw hot-reloads and confirmed the singleton lock prevents duplicate Viewer instances and port drift.
  • Shutdown Lifecycle: Started the viewer using start-viewer.ts and triggered SIGINT to verify the asynchronous graceful shutdown works as expected without leaving hanging processes.
  • UI Warnings: Verified the UI fallback warning banners correctly render and disappear across both English and Chinese locales when model configurations are absent.
  • Ran integration and unit tests (pnpm test) to ensure everything works correctly.
• Pipeline Automated API Test (please provide)

Checklist

• I have performed a self-review of my own code | 我已自行检查了自己的代码
• I have commented my code in hard-to-understand areas | 我已在难以理解的地方对代码进行了注释
• I have added tests that prove my fix is effective or that my feature works | 我已添加测试以证明我的修复有效或功能正常
• I have created related documentation issue/PR in https://github.com/MemTensor/MemOS-Docs (if applicable) | 我已在 https://github.com/MemTensor/MemOS-Docs 中创建了相关的文档 issue/PR（如果适用）
• I have linked the issue to this PR (if applicable) | 我已将 issue 链接到此 PR（如果适用）
• I have mentioned the person who will review this PR | 我已提及将审查此 PR 的人

Reviewer Checklist

• closes memos-local-openclaw-plugin@1.0.8 self-start viewer repeats under host lifecycle mismatch, causing port drift (18799→18800+), Memory unavailable #1430
• closes [memos-local] Viewer self-starts multiple times — duplicate instances on every gateway start #1425
• closes [Bug] Memory Viewer starts twice on OpenClaw startup (port 18799 → 18800 fallback) #1422
• Made sure Checks passed
• Tests have been provided