rol-websocket-channel 1.6.9 → 1.7.1

package/dist/index.js

@@ -249,19 +249,27 @@ const WebSocketChannel = {
         }),
     },
     outbound: {
+        // MQTT 是 topic-based 路由，不依赖 to 做地址解析
+        // 使用 "direct" 模式：AI reply 走 deliver 回调；message 工具走 sendText
         deliveryMode: "direct",
-        sendText: async ({ to, text }) => {
+        sendText: async ({ to, text, sessionKey }) => {
             const conn = ConnectionManager.getGlobalConnection();
             if (!conn || !conn.ws || !conn.ws.connected) {
                 return { ok: false, error: "No MQTT connection" };
             }
+            // 与 deliver 回调保持一致，使用 receiver 格式发布消息
             const message = JSON.stringify({
-                type: "message",
-                to,
-                content: text,
+                type: "receiver",
+                source: "ai",
+                data: { text },
                 timestamp: Date.now(),
             });
-            conn.ws.publish(conn.topic, message);
+            // 将 # 替换为 bot（outbound 不知道 source_type，默认 bot）
+            let targetTopic = conn.topic;
+            if (targetTopic.endsWith("#")) {
+                targetTopic = targetTopic.slice(0, -1) + "bot";
+            }
+            conn.ws.publish(targetTopic, message);
             return { ok: true };
         },
         sendMedia: async ({ to, text, mediaUrl }) => {
@@ -270,16 +278,75 @@ const WebSocketChannel = {
                 return { ok: false, error: "No MQTT connection" };
             }
             const message = JSON.stringify({
-                type: "media",
-                to,
-                content: text,
-                mediaUrl,
+                type: "receiver",
+                source: "ai",
+                data: { text, mediaUrl },
                 timestamp: Date.now(),
             });
-            conn.ws.publish(conn.topic, message);
+            let targetTopic = conn.topic;
+            if (targetTopic.endsWith("#")) {
+                targetTopic = targetTopic.slice(0, -1) + "bot";
+            }
+            conn.ws.publish(targetTopic, message);
             return { ok: true };
         },
     },
+    // ============================================
+    // messaging: 告知框架如何解析 target 地址
+    // MQTT 是 topic-based，任意非空字符串都是合法 target
+    // ============================================
+    messaging: {
+        // 接受任何非空字符串作为合法 target（MQTT 不做地址校验）
+        normalizeTarget: (raw) => {
+            const trimmed = raw?.trim();
+            return trimmed || undefined;
+        },
+        // 告知框架：deliver 目标就是原始字符串本身
+        targetResolver: {
+            looksLikeId: (_raw) => true,
+        },
+    },
+    // ============================================
+    // actions: 处理 message 工具的 send action
+    // 直接发布到 MQTT，完全绕过 target 解析
+    // ============================================
+    actions: {
+        describeMessageTool: () => ({
+            actions: ["send"],
+        }),
+        supportsAction: ({ action }) => action === "send",
+        handleAction: async (ctx) => {
+            const { action, params } = ctx;
+            if (action !== "send") {
+                throw new Error(`Unsupported action: ${action}`);
+            }
+            const text = typeof params.message === "string" ? params.message
+                : typeof params.text === "string" ? params.text
+                    : "";
+            const conn = ConnectionManager.getGlobalConnection();
+            if (!conn || !conn.ws || !conn.ws.connected) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ ok: false, error: "No MQTT connection" }) }],
+                    details: {},
+                };
+            }
+            const replyMessage = JSON.stringify({
+                type: "receiver",
+                source: "ai",
+                data: { text },
+                timestamp: Date.now(),
+            });
+            let targetTopic = conn.topic;
+            if (targetTopic.endsWith("#")) {
+                targetTopic = targetTopic.slice(0, -1) + "bot";
+            }
+            conn.ws.publish(targetTopic, replyMessage);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ ok: true }) }],
+                details: {},
+            };
+        },
+    },
     gateway: {
         startAccount: async (ctx) => {
             const { log, account, abortSignal, cfg } = ctx;
@@ -435,11 +502,13 @@ async function handleIncomingMessage(payload, account, cfg, runtime, log, mqttTo
         const resolvedAccountId = targetAgentId ?? route.accountId;
         const resolvedSessionKey = targetSessionId ?? route.sessionKey;
         // 构建消息上下文
+        // To 必须设置为 senderId：框架用它确定 message 工具的回复目标
+        // From 是发送方；To 是「这条对话的对端」（即 bot 应回复给谁）
         const ctxPayload = runtime.channel.reply.finalizeInboundContext({
             Body: normalizedMessage.text,
             BodyForAgent: normalizedMessage.text,
             From: normalizedMessage.senderId,
-            To: undefined,
+            To: normalizedMessage.senderId,
             SessionKey: resolvedSessionKey,
             AccountId: resolvedAccountId,
             ChatType: "direct",
@@ -451,46 +520,60 @@ async function handleIncomingMessage(payload, account, cfg, runtime, log, mqttTo
             Timestamp: Date.now(),
         });
         // 调度回复
-        await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-            ctx: ctxPayload,
-            cfg,
-            dispatcherOptions: {
-                deliver: async (payload) => {
-                    const conn = ConnectionManager.getGlobalConnection();
-                    if (!conn || !conn.ws || !conn.ws.connected) {
-                        throw new Error("No MQTT connection available");
-                    }
-                    const replyMessage = {
-                        type: "receiver",
-                        trace_id: traceId,
-                        source: "ai",
-                        meta: {
-                            'agentId': resolvedAccountId,
-                            'sessionKey': resolvedSessionKey
-                        },
-                        data: payload,
-                        timestamp: Date.now(),
-                    };
-                    // 根据 source_type 修改 topic 末尾的 #
-                    let targetTopic = mqttTopic;
-                    const sourceType = innerData?.source_type;
-                    if (targetTopic.endsWith("#")) {
-                        const replacement = sourceType === "device" ? "device" : "bot";
-                        targetTopic = targetTopic.slice(0, -1) + replacement;
-                    }
-                    conn.ws.publish(targetTopic, JSON.stringify(replyMessage));
-                },
-                onError: (err) => {
-                    log?.error(`[rol-websocket-channel] Delivery error: ${err.message}`);
-                },
+        // withReplyDispatcher({ dispatcher, run }) 是底层封装：
+        //   - dispatcher 由 createReplyDispatcherWithTyping 创建（负责 deliver 和分批发送）
+        //   - run 调用 dispatchReplyFromConfig（负责路由和 AI 回复逻辑）
+        //   - markComplete 由框架内部在 run 完成后自动调用，不需要外部传入
+        const { dispatcher, markRunComplete, markDispatchIdle } = runtime.channel.reply.createReplyDispatcherWithTyping({
+            deliver: async (payload) => {
+                const conn = ConnectionManager.getGlobalConnection();
+                if (!conn || !conn.ws || !conn.ws.connected) {
+                    throw new Error("No MQTT connection available");
+                }
+                const replyMessage = {
+                    type: "receiver",
+                    trace_id: traceId,
+                    source: "ai",
+                    meta: {
+                        'agentId': resolvedAccountId,
+                        'sessionKey': resolvedSessionKey
+                    },
+                    data: payload,
+                    timestamp: Date.now(),
+                };
+                // 根据 source_type 修改 topic 末尾的 #
+                let targetTopic = mqttTopic;
+                const sourceType = innerData?.source_type;
+                if (targetTopic.endsWith("#")) {
+                    const replacement = sourceType === "device" ? "device" : "bot";
+                    targetTopic = targetTopic.slice(0, -1) + replacement;
+                }
+                conn.ws.publish(targetTopic, JSON.stringify(replyMessage));
+            },
+            onError: (err) => {
+                log?.error(`[rol-websocket-channel] Delivery error: ${err.message} ${err.stack}`);
             },
         });
+        try {
+            await runtime.channel.reply.withReplyDispatcher({
+                dispatcher,
+                run: () => runtime.channel.reply.dispatchReplyFromConfig({
+                    ctx: ctxPayload,
+                    cfg,
+                    dispatcher,
+                }),
+            });
+        }
+        finally {
+            markRunComplete?.();
+            markDispatchIdle?.();
+        }
     }
     catch (err) {
         log?.error(`[rol-websocket-channel] Failed to process message: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-const immediateAckMessageTypes = new Set(["openclawUpdate", "pluginSelfUpdate"]);
+const immediateAckMessageTypes = new Set(["pluginSelfUpdate"]);
 export async function handleCustomMessageType(msgType, innerData, traceId, accountId, mqttTopic) {
     const isSkillInstallFlow = msgType === "skillsInstallFromClawHub" || msgType === "skillsUpdateFromClawHub";
     const response = {

package/dist/message-handler.js

@@ -18,7 +18,7 @@ import { uninstallSkill } from './src/admin/methods/skills-extended.js';
 import { toggleSkill } from './src/admin/methods/skills-toggle.js';
 import { listMemoryFiles, getMemoryFile, backupMemory, exportMemoryZip, getMemoryPresignedPost, createMemoryBackupRecord, importMemoryZip, } from './src/admin/methods/memory.js';
 import { getMem9Config, installMem9, reconnectMem9 } from './src/admin/methods/mem9.js';
-import { currentVersion, doctorFix, logs, openclawUpdate, pluginSelfUpdate, restart, stop } from './src/admin/methods/system.js';
+import { currentVersion, doctorFix, logs, pluginSelfUpdate, restart, stop } from './src/admin/methods/system.js';
 export class MessageHandler {
     /**
      * 示例方法：处理 ping 类型的消息
@@ -497,12 +497,7 @@ export class MessageHandler {
             return await logs(data, context);
         });
     }
-    async openclawUpdate(data) {
-        return wrapAdminCall(async () => {
-            const context = getContext();
-            return await openclawUpdate(data, context);
-        });
-    }
+    // OpenClaw core updates are managed outside this plugin.
     async pluginSelfUpdate(data) {
         return wrapAdminCall(async () => {
             const context = getContext();

package/dist/src/admin/lib/openclaw-bin.js

@@ -1,3 +1,21 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
 export function resolveOpenClawBin() {
-    return process.env.OPENCLAW_BIN || 'openclaw';
+    if (process.env.OPENCLAW_BIN) {
+        return process.env.OPENCLAW_BIN;
+    }
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA;
+        const candidates = [
+            appData ? path.join(appData, 'npm', 'openclaw.cmd') : null,
+            path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'openclaw.cmd')
+        ];
+        for (const candidate of candidates) {
+            if (candidate && fs.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return 'openclaw';
 }

package/dist/src/admin/lib/openclaw-bin.test.js

@@ -0,0 +1,37 @@
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveOpenClawBin } from './openclaw-bin.js';
+describe('resolveOpenClawBin', () => {
+    test('uses APPDATA npm shim on Windows when OPENCLAW_BIN is unset', { skip: process.platform !== 'win32' }, async () => {
+        const originalOpenClawBin = process.env.OPENCLAW_BIN;
+        const originalAppData = process.env.APPDATA;
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'openclaw-bin-'));
+        try {
+            const appData = path.join(root, 'Roaming');
+            const shim = path.join(appData, 'npm', 'openclaw.cmd');
+            await fs.mkdir(path.dirname(shim), { recursive: true });
+            await fs.writeFile(shim, '@echo off\r\n', 'utf8');
+            delete process.env.OPENCLAW_BIN;
+            process.env.APPDATA = appData;
+            assert.equal(resolveOpenClawBin(), shim);
+        }
+        finally {
+            if (originalOpenClawBin === undefined) {
+                delete process.env.OPENCLAW_BIN;
+            }
+            else {
+                process.env.OPENCLAW_BIN = originalOpenClawBin;
+            }
+            if (originalAppData === undefined) {
+                delete process.env.APPDATA;
+            }
+            else {
+                process.env.APPDATA = originalAppData;
+            }
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+});

package/dist/src/admin/methods/index.js

@@ -11,7 +11,7 @@ import { listSessions } from './sessions.js';
 import { getSession, prepareMessage, attachSkill } from './sessions-extended.js';
 import { installSkillFromClawHub, installSkillFromNpm, listInstalledSkills, searchClawHubSkills, updateSkillFromClawHub } from './skills.js';
 import { getInstalledSkill, uninstallSkill } from './skills-extended.js';
-import { currentVersion, doctorFix, logs, openclawUpdate, ping, pluginSelfUpdate, restart, stop } from './system.js';
+import { currentVersion, doctorFix, logs, ping, pluginSelfUpdate, restart, stop } from './system.js';
 import { getUsageBreakdown, getUsagePageSummary, getUsageSummary, getUsageTimeseries } from './usage.js';
 const methods = new Map([
     // System
@@ -20,7 +20,7 @@ const methods = new Map([
     ['system.stop', stop],
     ['system.doctorFix', doctorFix],
     ['system.logs', logs],
-    ['system.openclawUpdate', openclawUpdate],
+    // OpenClaw core updates are managed outside this plugin.
     ['system.pluginSelfUpdate', pluginSelfUpdate],
     ['system.currentVersion', currentVersion],
     // Agents

package/dist/src/admin/methods/mem9.js

@@ -1,6 +1,7 @@
 import { exec, execFile } from 'node:child_process';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import fs from 'node:fs';
 import { pathExists, readJsonFile, writeJsonFile } from '../lib/fs.js';
 import { resolveOpenClawBin } from '../lib/openclaw-bin.js';
 import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.js';
@@ -43,26 +44,48 @@ export async function installMem9(context) {
     const config = await ensureOpenClawConfigExists(context.openclawRoot);
     const currentState = readMem9State(config);
     const currentEntrypoint = await findMem9RuntimeEntrypoint(context.openclawRoot, config);
-    // Phase A: Plugin not installed → install only, then restart
+    // Phase A: Plugin not installed → install only, then write backend key if available, and restart
     if (!currentState.installed && !currentEntrypoint) {
         await ensureOpenClawCli();
         await ensureNodeRuntime();
         await installMem9Plugin(context.projectRoot);
+        const backendConfig = await fetchMem9KeyFromBackend(context.openclawRoot);
+        let updatedConfigs = [];
+        if (backendConfig) {
+            updatedConfigs = await writeMem9Config(context.openclawRoot, backendConfig.apiKey, backendConfig.apiUrl);
+        }
         const restart = await restartGateway(context.projectRoot);
         return {
             ok: true,
-            phase: 'installed',
+            phase: backendConfig ? 'configured' : 'installed',
             needsRestart: true,
             plugin: MEM9_PLUGIN_ID,
-            message: 'mem9 plugin installed. Gateway is restarting. Send mem9Install again to complete setup.',
+            apiKey: backendConfig?.apiKey ?? null,
+            apiUrl: backendConfig?.apiUrl ?? MEM9_API_URL,
+            updated: updatedConfigs.length > 0 ? updatedConfigs : null,
+            message: backendConfig
+                ? 'mem9 plugin installed and configured with backend key. Gateway is restarting.'
+                : 'mem9 plugin installed. Gateway is restarting. Send mem9Install again to complete setup.',
             restart
         };
     }
-    // Phase B: Installed but no key → create key, write config, restart
+    // Phase B: Installed but no key → fetch key from backend, fallback to creating a key, write config, restart
     if (!currentState.configured || !currentState.apiKey) {
         const runtimeEntrypoint = await ensureMem9RuntimeEntrypoint(context.openclawRoot, config);
-        const apiKey = await createMem9Key();
-        const updated = await writeMem9Config(context.openclawRoot, apiKey);
+        const backendConfig = await fetchMem9KeyFromBackend(context.openclawRoot);
+        let apiKey = backendConfig?.apiKey ?? null;
+        let apiUrl = backendConfig?.apiUrl ?? null;
+        let createdNewKey = false;
+        let reusedExistingKey = false;
+        if (!apiKey) {
+            apiKey = await createMem9Key();
+            apiUrl = MEM9_API_URL;
+            createdNewKey = true;
+        }
+        else {
+            reusedExistingKey = true;
+        }
+        const updated = await writeMem9Config(context.openclawRoot, apiKey, apiUrl);
         const restart = await restartGateway(context.projectRoot);
         return {
             ok: true,
@@ -70,11 +93,11 @@ export async function installMem9(context) {
             installed: true,
             alreadyInstalled: true,
             alreadyConfigured: false,
-            createdNewKey: true,
-            reusedExistingKey: false,
+            createdNewKey,
+            reusedExistingKey,
             plugin: MEM9_PLUGIN_ID,
             runtimeEntrypoint,
-            apiUrl: MEM9_API_URL,
+            apiUrl: apiUrl || MEM9_API_URL,
             apiKey,
             updated,
             restart
@@ -94,7 +117,7 @@ export async function installMem9(context) {
         reusedExistingKey: true,
         plugin: MEM9_PLUGIN_ID,
         runtimeEntrypoint,
-        apiUrl: MEM9_API_URL,
+        apiUrl: pickString(isRecord(config.plugins?.entries?.[MEM9_PLUGIN_ID]?.config) ? config.plugins.entries[MEM9_PLUGIN_ID].config.apiUrl : null) ?? MEM9_API_URL,
         apiKey: currentState.apiKey,
         updated,
         restart
@@ -158,7 +181,7 @@ async function ensureOpenClawConfigExists(openclawRoot) {
 async function ensureOpenClawCli() {
     const bin = resolveOpenClawBin();
     try {
-        await execFileAsync(bin, ['--version']);
+        await execAsync(`"${bin}" --version`);
     }
     catch (error) {
         throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `openclaw command is not available (tried: ${bin}). Configure the OpenClaw binary path for the Gateway service.`, { code: 'MEM9_OPENCLAW_NOT_FOUND', bin, detail: error instanceof Error ? error.message : String(error) });
@@ -166,8 +189,8 @@ async function ensureOpenClawCli() {
 }
 async function ensureNodeRuntime() {
     try {
-        await execFileAsync('node', ['--version']);
-        await execFileAsync('npm', ['--version']);
+        await execAsync('node --version');
+        await execAsync('npm --version');
     }
     catch (error) {
         throw new JsonRpcException(JSON_RPC_ERRORS.internalError, 'node or npm command is not available', { code: 'MEM9_NODE_NOT_FOUND', detail: error instanceof Error ? error.message : String(error) });
@@ -176,7 +199,7 @@ async function ensureNodeRuntime() {
 async function installMem9Plugin(cwd) {
     const bin = resolveOpenClawBin();
     try {
-        await execFileAsync(bin, ['plugins', 'install', MEM9_PLUGIN_SPEC], { cwd });
+        await execAsync(`"${bin}" plugins install ${MEM9_PLUGIN_SPEC} --force`, { cwd });
     }
     catch (error) {
         throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `${bin} plugins install ${MEM9_PLUGIN_SPEC} failed`, {
@@ -213,12 +236,20 @@ async function ensureMem9RuntimeEntrypoint(openclawRoot, config) {
             }
         }
     }
-    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, 'mem9 plugin is installed but missing compiled runtime output', {
+    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, 'mem9 runtime not found; config exists but compiled plugin output is missing', {
         code: 'MEM9_RUNTIME_OUTPUT_MISSING',
+        diagnosis: 'CONFIG_PRESENT_RUNTIME_MISSING',
+        summary: 'Mem9 is configured in openclaw.json, but no compiled JavaScript runtime was found under OpenClaw install paths.',
         expected: FALLBACK_ENTRYPOINTS.map((item) => `./${item.replace(/\\/g, '/')}`),
         checkedPackageRoots,
         checkedEntrypoints,
-        installRecord
+        installRecord,
+        installState: describeMem9InstallState(openclawRoot, config),
+        suggestions: [
+            'Ensure OpenClaw has extensions/mem9 pointing to the installed @mem9/mem9 package.',
+            'If extensions/mem9 is missing or broken, run: openclaw plugins install @mem9/mem9 --force',
+            'If plugins.entries.mem9 exists but no runtime path exists, treat it as stale config residue rather than a complete install.'
+        ]
     });
 }
 async function readPluginManifest(packageRoot) {
@@ -295,15 +326,35 @@ function collectEntrypointCandidates(packageRoot, manifest) {
 }
 function resolveMem9RuntimePackageRoots(openclawRoot, config) {
     const roots = [];
+    const pushRoot = (root) => {
+        if (!roots.includes(root))
+            roots.push(root);
+    };
     const installPath = pickString(readMem9InstallRecord(config)?.installPath);
     if (installPath) {
-        roots.push(path.isAbsolute(installPath) ? installPath : path.resolve(openclawRoot, installPath));
+        pushRoot(path.isAbsolute(installPath) ? installPath : path.resolve(openclawRoot, installPath));
     }
-    for (const fallbackRoot of MEM9_PACKAGE_ROOTS.map((item) => path.join(openclawRoot, item))) {
-        if (!roots.includes(fallbackRoot)) {
-            roots.push(fallbackRoot);
+    pushRoot(path.join(openclawRoot, 'extensions', MEM9_PLUGIN_ID));
+    const projectsDir = path.join(openclawRoot, 'npm', 'projects');
+    try {
+        if (fs.existsSync(projectsDir)) {
+            const projects = fs.readdirSync(projectsDir);
+            for (const project of projects) {
+                const candidate1 = path.join(projectsDir, project, 'node_modules', '@mem9', 'mem9');
+                const candidate2 = path.join(projectsDir, project, 'node_modules', 'mem9');
+                if (fs.existsSync(candidate1))
+                    pushRoot(candidate1);
+                if (fs.existsSync(candidate2))
+                    pushRoot(candidate2);
+            }
         }
     }
+    catch (err) {
+        console.warn('[Mem9] Failed to scan npm/projects:', err);
+    }
+    for (const fallbackRoot of MEM9_PACKAGE_ROOTS.map((item) => path.join(openclawRoot, item))) {
+        pushRoot(fallbackRoot);
+    }
     return roots;
 }
 async function createMem9Key() {
@@ -333,7 +384,79 @@ async function createMem9Key() {
 // ---------------------------------------------------------------------------
 // Config writers
 // ---------------------------------------------------------------------------
-async function writeMem9Config(openclawRoot, apiKey) {
+async function resolveApiCoreBotEndpoint(openclawRoot, overrideBaseUrl, overrideAuthToken) {
+    const config = await readJsonFile(path.join(openclawRoot, 'openclaw.json'));
+    const pluginConfig = config.plugins?.entries?.['rol-websocket-channel']?.config?.apiCoreBot ?? {};
+    const baseUrl = (overrideBaseUrl && overrideBaseUrl.trim()) || pluginConfig.baseUrl;
+    if (!baseUrl || !baseUrl.trim()) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'apiCoreBot.baseUrl is not configured');
+    }
+    const authToken = (overrideAuthToken && overrideAuthToken.trim()) || pluginConfig.authToken;
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        authToken
+    };
+}
+async function postJson(url, body, authToken) {
+    const headers = {
+        'Content-Type': 'application/json'
+    };
+    if (authToken && authToken.trim()) {
+        headers.Authorization = `Bearer ${authToken.trim()}`;
+    }
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body)
+    });
+    const payload = await response.json().catch(async () => await response.text());
+    if (!response.ok) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `Request failed: ${response.status}`, {
+            url,
+            status: response.status,
+            payload
+        });
+    }
+    return payload;
+}
+async function fetchMem9KeyFromBackend(openclawRoot) {
+    try {
+        const endpointConfig = await resolveApiCoreBotEndpoint(openclawRoot);
+        if (!endpointConfig.baseUrl) {
+            return null;
+        }
+        const response = await postJson(`${endpointConfig.baseUrl}/api-core-bot/front/mem9/key`, {}, endpointConfig.authToken);
+        const responseRecord = response;
+        const root = isRecord(responseRecord.data) ? responseRecord.data : responseRecord;
+        // Check nested structures (e.g. plugins.entries.mem9.config.apiKey)
+        let key = null;
+        let apiUrl = null;
+        if (isRecord(root.plugins?.entries?.mem9?.config)) {
+            key = pickString(root.plugins.entries.mem9.config.apiKey);
+            apiUrl = pickString(root.plugins.entries.mem9.config.apiUrl);
+        }
+        else if (isRecord(root.config)) {
+            key = pickString(root.config.apiKey);
+            apiUrl = pickString(root.config.apiUrl);
+        }
+        // Fallback to direct properties
+        if (!key) {
+            key = pickString(root.apiKey) ?? pickString(root.key) ?? pickString(root.id);
+        }
+        if (!apiUrl) {
+            apiUrl = pickString(root.apiUrl) ?? pickString(root.url);
+        }
+        if (!key) {
+            return null;
+        }
+        return { apiKey: key, apiUrl };
+    }
+    catch (error) {
+        console.warn('[Mem9] Failed to fetch key from apiCoreBot backend, will fallback to Mem9 official API:', error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}
+async function writeMem9Config(openclawRoot, apiKey, apiUrl) {
     const configPath = path.join(openclawRoot, 'openclaw.json');
     const config = await readJsonFile(configPath);
     if (!config.plugins)
@@ -354,7 +477,7 @@ async function writeMem9Config(openclawRoot, apiKey) {
         },
         config: {
             ...existingPluginConfig,
-            apiUrl: MEM9_API_URL,
+            apiUrl: apiUrl || pickString(existingPluginConfig.apiUrl) || MEM9_API_URL,
             apiKey
         }
     };
@@ -413,7 +536,7 @@ function ensurePluginsAllow(config) {
 async function restartGateway(cwd) {
     const attempts = [];
     const bin = resolveOpenClawBin();
-    const restartCmd = `${bin} gateway restart`;
+    const restartCmd = `"${bin}" gateway restart`;
     try {
         const { stdout, stderr } = await execAsync(restartCmd, { cwd });
         return {
@@ -479,6 +602,25 @@ function readMem9InstallRecord(config) {
     const record = config?.plugins?.installs?.[MEM9_PLUGIN_ID];
     return isRecord(record) ? record : null;
 }
+function describeMem9InstallState(openclawRoot, config) {
+    const installRecord = readMem9InstallRecord(config);
+    const entry = isRecord(config?.plugins?.entries?.[MEM9_PLUGIN_ID]) ? config?.plugins?.entries?.[MEM9_PLUGIN_ID] : {};
+    const pluginConfig = isRecord(entry.config) ? entry.config : {};
+    const allow = config?.plugins?.allow;
+    const extensionsMem9Path = path.join(openclawRoot, 'extensions', MEM9_PLUGIN_ID);
+    return {
+        hasInstallRecord: Boolean(installRecord),
+        installPath: pickString(installRecord?.installPath),
+        hasEntry: isRecord(config?.plugins?.entries?.[MEM9_PLUGIN_ID]),
+        entryEnabled: entry.enabled === true,
+        hasApiKey: Boolean(pickString(pluginConfig.apiKey)),
+        apiUrl: pickString(pluginConfig.apiUrl),
+        allowContainsMem9: Array.isArray(allow) && allow.includes(MEM9_PLUGIN_ID),
+        memorySlot: typeof config?.plugins?.slots?.memory === 'string' ? config.plugins.slots.memory : null,
+        extensionsMem9Path,
+        extensionsMem9Exists: fs.existsSync(extensionsMem9Path)
+    };
+}
 function readMem9State(config) {
     const installed = Boolean((config.plugins?.installs && typeof config.plugins.installs === 'object' && MEM9_PLUGIN_ID in config.plugins.installs)
         || (config.plugins?.entries && typeof config.plugins.entries === 'object' && MEM9_PLUGIN_ID in config.plugins.entries));