Openclaw local plugin 20260408 (#1454)

## 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 #1422, #1425, #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 

- [x] Bug fix (non-breaking change which fixes an issue) 
- [x] 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? 

- [x] Unit Test 
- [x] 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 

- [x] I have performed a self-review of my own code | 我已自行检查了自己的代码 
- [x] I have commented my code in hard-to-understand areas |
我已在难以理解的地方对代码进行了注释
- [x] 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（如果适用）
- [x] 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 
- [x] closes #1430
- [x] closes #1425
- [x] closes #1422
- [ ] Made sure Checks passed 
- [ ] Tests have been provided

Author: Hun-ger

apps/memos-local-openclaw/index.ts

@@ -389,6 +389,15 @@ const memosLocalPlugin = {
     let currentAgentId = "main";
     const getCurrentOwner = () => `agent:${currentAgentId}`;
 
+    // Manage global singleton instance to prevent duplicate startups
+    // during OpenClaw hot-reloads or deferred re-registrations.
+    const globalRef = globalThis as any;
+
+    if (globalRef.__memosLocalPluginActiveService) {
+      api.logger.info("memos-local: Plugin is already running. Reusing the existing backend and returning early.");
+      return;
+    }
+
     // ─── Check allowPromptInjection policy ───
     // When allowPromptInjection=false, the prompt mutation fields (such as prependContext) in the hook return value
     // will be stripped by the framework. Skip auto-recall to avoid unnecessary LLM/embedding calls.
@@ -2383,7 +2392,19 @@ Groups: ${groupNames.length > 0 ? groupNames.join(", ") : "(none)"}`,
     let serviceStarted = false;
 
     const startServiceCore = async () => {
+      if (globalRef.__memosLocalPluginStopPromise) {
+        await globalRef.__memosLocalPluginStopPromise;
+        globalRef.__memosLocalPluginStopPromise = undefined;
+      }
       if (serviceStarted) return;
+      
+      // If another registration has occurred, we are no longer the active service.
+      // Abort starting to prevent orphan instances.
+      if (globalRef.__memosLocalPluginActiveService && globalRef.__memosLocalPluginActiveService !== service) {
+        api.logger.info("memos-local: aborting startServiceCore because a newer plugin instance is active.");
+        return;
+      }
+
       serviceStarted = true;
 
       if (hubServer) {
@@ -2425,27 +2446,43 @@ Groups: ${groupNames.length > 0 ? groupNames.join(", ") : "(none)"}`,
       );
     };
 
-    api.registerService({
+    const service = {
       id: "memos-local-openclaw-plugin",
       start: async () => { await startServiceCore(); },
       stop: async () => {
+        await viewer.stop();
+        if (globalRef.__memosLocalPluginActiveService === service) {
+          globalRef.__memosLocalPluginActiveService = undefined;
+        }
         await worker.flush();
         await telemetry.shutdown();
         await hubServer?.stop();
-        viewer.stop();
         store.close();
         api.logger.info("memos-local: stopped");
       },
-    });
+    };
+
+    api.registerService(service);
+    globalRef.__memosLocalPluginActiveService = service;
 
     // Fallback: OpenClaw may load this plugin via deferred reload after
     // startPluginServices has already run, so service.start() never fires.
-    // Start on the next tick instead of waiting several seconds; the
-    // serviceStarted guard still prevents duplicate startup if the host calls
-    // service.start() immediately after registration.
-    const SELF_START_DELAY_MS = 0;
+    // Start on a delay instead of next tick so the host has time to call
+    // service.start() during normal startup if this is a fresh launch.
+    const SELF_START_DELAY_MS = 2000;
     setTimeout(() => {
-      if (!serviceStarted) {
+      const args = process.argv.map(arg => String(arg || "").toLowerCase());
+      const gatewayIndex = args.lastIndexOf("gateway");
+      let shouldStart = false;
+
+      if (gatewayIndex !== -1) {
+        const nextArg = args[gatewayIndex + 1];
+        if (!nextArg || nextArg.startsWith("-") || nextArg === "start" || nextArg === "restart") {
+          shouldStart = true;
+        }
+      }
+
+      if (!serviceStarted && shouldStart) {
         api.logger.info("memos-local: service.start() not called by host, self-starting viewer...");
         startServiceCore().catch((err) => {
           api.logger.warn(`memos-local: self-start failed: ${err}`);

apps/memos-local-openclaw/scripts/start-viewer.ts

@@ -71,8 +71,9 @@ async function main() {
   console.log(`\x1b[90m  Reset token: ${viewer.getResetToken()}\x1b[0m`);
   console.log(`\x1b[90m  Press Ctrl+C to stop\x1b[0m`);
 
-  process.on("SIGINT", () => {
-    viewer.stop();
+  process.on("SIGINT", async () => {
+    console.log("Shutting down viewer...");
+    await viewer.stop();
     store.close();
     process.exit(0);
   });

apps/memos-local-openclaw/src/viewer/html.ts

@@ -124,7 +124,7 @@ input,textarea,select{font-family:inherit;font-size:inherit}
 .topbar-center{flex:1;display:flex;justify-content:center}
 .topbar .actions{display:flex;align-items:center;gap:6px;flex-shrink:0}
 
-.main-content{display:flex;flex:1;max-width:1400px;margin:0 auto;width:100%;padding:28px 32px;gap:28px}
+.main-content{display:grid;grid-template-columns:260px 1fr;grid-template-rows:auto 1fr;flex:1;max-width:1400px;margin:0 auto;width:100%;padding:28px 32px;gap:28px}
 
 /* ─── Sidebar ─── */
 .sidebar{width:260px;min-width:260px;flex-shrink:0;position:sticky;top:84px;max-height:calc(100vh - 112px);display:flex;flex-direction:column}
@@ -1500,6 +1500,16 @@ input,textarea,select{font-family:inherit;font-size:inherit}
             </div>
           </div>
           <div class="settings-card-body">
+            <div class="emb-banner warning" id="settingsWarningBanner" style="margin: 0 0 24px 0; display: block; border-left: 4px solid #f59e0b; position: relative;">
+              <button onclick="document.getElementById('settingsWarningBanner').style.display='none'" style="position: absolute; right: 12px; top: 12px; background: none; border: none; cursor: pointer; color: var(--text-muted); font-size: 16px; opacity: 0.7; transition: opacity 0.2s;" onmouseover="this.style.opacity=1" onmouseout="this.style.opacity=0.7" title="关闭" aria-label="关闭">\u2715</button>
+              <div style="font-weight: 700; margin-bottom: 8px; font-size: 14px; color: #d97706;">\u{1F514} 模型配置重要提醒</div>
+              <ul style="margin: 0; padding-left: 20px; line-height: 1.7; color: var(--text-sec); font-size: 13px;">
+                <li><strong>嵌入模型 (Embedding)：</strong>插件内置模型规模较小。为获得更精准的记忆检索体验，强烈建议配置 <code>bge-m3</code> 等专业嵌入模型。</li>
+                <li><strong>摘要模型 (Summarizer)：</strong>此项为<strong>必填项</strong>，否则无法自动提取记忆摘要。建议配置<strong>非思考型</strong>大模型，以保障处理速度和流畅度。</li>
+                <li><strong>技能模型 (Skill Evolution)：</strong>用于自动提取可复用技能。建议配置<strong>非思考型</strong>大模型，以获得最佳的生成效果和稳定性。</li>
+              </ul>
+            </div>
+
             <!-- Embedding Model section -->
             <div class="settings-card-subtitle">\u{1F4E1} <span data-i18n="settings.embedding">Embedding Model</span></div>
             <div class="field-hint" style="margin-bottom:10px" data-i18n="settings.embedding.desc">Vector embedding model for memory search and retrieval</div>
@@ -2126,6 +2136,7 @@ const I18N={
     'skills.search.placeholder':'Search skills...',
     'skills.search.local':'Local',
     'skills.search.noresult':'No matching skills found',
+
     'skills.load.error':'Failed to load skills',
     'skills.hub.title':'\u{1F310} Team Skills',
     'skills.hub.empty':'No extra team skills to list here — either the hub has none yet, or every hub skill already appears in your local list above (same source skill).',
@@ -2273,7 +2284,10 @@ const I18N={
     'confirm.clearall2':'Are you absolutely sure?',
     'embed.on':'Embedding: ',
     'embed.off':'No embedding model',
-    'embed.warn.local':'Using built-in mini model (384d). Search quality is limited — configure an embedding model in Settings for best results.',
+    'embed.warn.local':'<strong>Embedding</strong>: Using built-in mini model (384d). Search quality is limited. It is highly recommended to configure a dedicated Embedding model (like bge-m3) in Settings for best results.',
+    'fallback.banner.sum': '<strong>Summarizer</strong>: Summarizer model is not configured, automatic memory summarization is paused. A fast, non-reasoning model is recommended for best performance.',
+    'fallback.banner.skill': '<strong>Skill Evolution</strong>: Skill Evolution model is not configured. A fast, non-reasoning model is recommended for best stability and generation quality.',
+    'fallback.banner.goto': 'Configure models',
     'embed.err.fail':'Embedding model error detected. Check Settings → Model Health.',
     'embed.banner.goto':'Go to Settings',
     'lang.switch':'中',
@@ -2899,6 +2913,7 @@ const I18N={
     'skills.search.placeholder':'搜索技能...',
     'skills.search.local':'本地',
     'skills.search.noresult':'未找到匹配的技能',
+
     'skills.load.error':'加载技能失败',
     'skills.hub.title':'\u{1F310} 团队共享技能',
     'skills.hub.empty':'下方只列出「Hub 上有、但上方本机列表尚未包含」的技能；若 Hub 条目已与本机同源同步，则只会在上方显示，此处为空属正常。',
@@ -3046,7 +3061,10 @@ const I18N={
     'confirm.clearall2':'你真的确定吗？',
     'embed.on':'嵌入模型：',
     'embed.off':'无嵌入模型',
-    'embed.warn.local':'当前使用内置迷你模型（384维），搜索效果有限。强烈建议在「设置」中配置专用 Embedding 模型以获得最佳效果。',
+    'embed.warn.local':'<strong>嵌入模型 (Embedding)</strong>：当前使用内置迷你模型（384维），搜索效果有限。强烈建议在「设置」中配置专用 Embedding 模型（如bge-m3等模型）以获得最佳效果。',
+    'fallback.banner.sum': '<strong>摘要模型 (Summarizer)</strong>：摘要模型未配置，无法自动提取记忆摘要。建议配置非思考型大模型，以保障处理速度和流畅度。',
+    'fallback.banner.skill': '<strong>技能模型 (Skill Evolution)</strong>：技能模型未配置，建议配置非思考型大模型，以获得最佳的生成效果和稳定性。',
+    'fallback.banner.goto': '前往配置',
     'embed.err.fail':'Embedding 模型调用异常，请前往「设置 → 模型健康」检查。',
     'embed.banner.goto':'前往设置',
     'lang.switch':'EN',
@@ -3647,7 +3665,15 @@ function applyI18n(){
   const step2=document.getElementById('resetStep2Desc');
   if(step2) step2.innerHTML=t('reset.step2.desc.pre')+'<span style="font-family:monospace;font-size:12px;color:var(--pri)">password reset token: <strong>a1b2c3d4e5f6...</strong></span>'+t('reset.step2.desc.post');
   document.title=t('title')+' - OpenClaw';
-  if(typeof loadStats==='function' && document.getElementById('app').style.display==='flex'){loadStats();}
+  if(typeof loadStats==='function' && document.getElementById('app').style.display==='flex'){
+    _embeddingWarningShown = false;
+    _fallbackWarningShown = false;
+    _lastStatsFp = '';
+    const embB = document.getElementById('embBanner'); if (embB) embB.remove();
+    const fSumB = document.getElementById('fallbackBannerSum'); if (fSumB) fSumB.remove();
+    const fSkillB = document.getElementById('fallbackBannerSkill'); if (fSkillB) fSkillB.remove();
+    loadStats();
+  }
   if(document.querySelector('.analytics-view.show') && typeof loadMetrics==='function'){loadMetrics();}
 }
 
@@ -8263,6 +8289,7 @@ async function loadAll(){
 }
 
 var _lastStatsFp='';
+var _fallbackWarningShown=false;
 async function loadStats(ownerFilter){
   let d;
   try{
@@ -8312,6 +8339,19 @@ async function loadStats(ownerFilter){
     }).catch(()=>{});
   }
 
+  if(!_fallbackWarningShown){
+    _fallbackWarningShown=true;
+    var sumWarn = (d.summarizerProvider === 'none') ? t('fallback.banner.sum') : '';
+    var skillWarn = (d.skillEvolutionProvider === 'none') ? t('fallback.banner.skill') : '';
+    
+    if (sumWarn) {
+      showFallbackBanner('fallbackBannerSum', '<div>'+sumWarn+'</div>', 'warning');
+    }
+    if (skillWarn) {
+      showFallbackBanner('fallbackBannerSkill', '<div>'+skillWarn+'</div>', 'warning');
+    }
+  }
+
   const memorySessions=d.sessions||[];
   const taskSessions=d.taskSessions||[];
   const skillSessions=d.skillSessions||[];
@@ -9623,7 +9663,22 @@ function showEmbeddingBanner(msg,type){
   var el=document.createElement('div');
   el.id='embBanner';
   el.className=cls;
-  el.innerHTML=icon+' <span>'+esc(msg)+'</span>'+btn+close;
+  el.innerHTML=icon+' <span>'+msg+'</span>'+btn+close;
+  var mc=document.querySelector('.main-content');
+  if(mc) mc.parentElement.insertBefore(el,mc);
+}
+
+/* ─── Fallback Banner ─── */
+function showFallbackBanner(id, msgHtml,type){
+  if(document.getElementById(id)) return;
+  var cls=type==='error'?'emb-banner error':'emb-banner warning';
+  var icon=type==='error'?'\\u274C':'\\u26A0\\uFE0F';
+  var btn='<button class="emb-banner-btn" onclick="switchView(\\'settings\\');this.parentElement.remove()" style="margin-left:auto;">'+t('fallback.banner.goto')+'</button>';
+  var close='<button class="emb-banner-close" onclick="this.parentElement.remove()">&times;</button>';
+  var el=document.createElement('div');
+  el.id=id;
+  el.className=cls;
+  el.innerHTML=icon+' <div style="line-height:1.5;flex:1;">'+msgHtml+'</div>'+btn+close;
   var mc=document.querySelector('.main-content');
   if(mc) mc.parentElement.insertBefore(el,mc);
 }

apps/memos-local-openclaw/src/viewer/server.ts

@@ -211,13 +211,24 @@ export class ViewerServer {
     }
   }
 
-  stop(): void {
-    this.stopHubHeartbeat();
-    this.stopNotifPoll();
-    for (const c of this.notifSSEClients) { try { c.end(); } catch {} }
-    this.notifSSEClients = [];
-    this.server?.close();
-    this.server = null;
+  stop(): Promise<void> {
+    return new Promise((resolve) => {
+      this.stopHubHeartbeat();
+      this.stopNotifPoll();
+      for (const c of this.notifSSEClients) { try { c.end(); } catch {} }
+      this.notifSSEClients = [];
+      if (this.server) {
+        if ("closeAllConnections" in this.server) {
+          (this.server as any).closeAllConnections();
+        }
+        this.server.close(() => {
+          this.server = null;
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
   }
 
   getResetToken(): string {
@@ -904,6 +915,9 @@ export class ViewerServer {
         totalMemories: total.count, totalSessions: sessions.count, totalEmbeddings: embCount,
         totalSkills: skillCount, totalTasks: taskCount,
         embeddingProvider: this.embedder.provider,
+        summarizerProvider: this.ctx?.config?.summarizer?.provider ?? "none",
+        skillEvolutionProvider: this.ctx?.config?.skillEvolution?.enabled ? (this.ctx?.config?.summarizer?.provider ?? "none") : "none",
+        isSummarizerDegraded: this.ctx ? !this.hasUsableSummarizerProvider(this.ctx.config) : false,
         dedupBreakdown,
         timeRange: { earliest: timeRange.earliest, latest: timeRange.latest },
         sessions: sessionList,