@openviking/openclaw-plugin 2026.9.8 → 2026.9.10-1

package/README.md

@@ -23,7 +23,7 @@ The agent runs install → setup → restart → verify automatically. See [INST
 
 | Stage | What happens |
 |-------|-------------|
-| **Every turn** (`afterTurn`) | New messages are appended to an OpenViking session; commit/extraction is threshold-triggered |
+| **Every turn** (`afterTurn` or `commitTurn`, depending on host/runner) | New messages are appended to an OpenViking session; commit/extraction is threshold-triggered |
 | **Explicit remember** (`memory_store`) | Important long-term facts can be written and committed immediately |
 | **On `/compact`** (`compact`) | Pending session messages are committed and extracted into long-term memories |
 | **Before each reply** (`assemble`) | Relevant memories are auto-retrieved and injected into context |
@@ -202,6 +202,17 @@ That means OpenClaw sees "compressed history summary + archive index + active me
 
 `afterTurn()` has a narrower job: append only the new turn into the OpenViking session.
 
+Capture ownership depends on the **host** version from `api.runtime.version`:
+
+- Before OpenClaw 2026.9.3, `afterTurn` captures messages; `commitTurn` only acknowledges the turn to avoid writing those messages twice.
+- Starting with 2026.9.3, admitted/deferred turns are captured inside `commitTurn` before acknowledgment. Standalone runners still capture via `afterTurn`.
+- The minimum supported OpenClaw version remains 2026.5.27. Missing/unparseable versions and ambiguous 2026.9.3 prereleases reject `commitTurn` rather than silently discarding queued messages; `afterTurn` remains available. Numeric packaging revisions such as `2026.9.3-1` use the 9.3 behavior.
+
+Durable capture propagates client/write/commit failures to the host for retry and shares one in-flight write between concurrent deliveries of the same advancement key. Disabled capture, heartbeats, bypassed sessions, and empty turns are intentional skips. The legacy `afterTurn` callback retains best-effort error handling.
+
+The host's durable delivery does not supply the model token budget or sender runtime context: this path uses the 128,000-token fallback and cannot attach the runtime sender ID to user messages. Message writes remain non-transactional: replay after partial writes or a process crash can duplicate messages. The in-memory advancement-key cache does not provide server-side exactly-once delivery.
+
+
 - it slices only the newly added messages
 - it keeps only `user` / `assistant` capture text
 - it preserves `toolCall` / `toolResult` content in the serialized turn text
@@ -214,7 +225,7 @@ After that, the plugin checks `pending_tokens`. Once it reaches `commitTokenThre
 - the current turn is not blocked waiting for extraction
 - if `logFindRequests` is enabled, the logs include the task id and follow-up extraction detail
 
-This automatic path is best-effort and commit-dependent. Short but important facts can stay only in the live session until a threshold commit, `/compact`, or an explicit store happens.
+Memory extraction on this automatic path is commit-dependent. Short but important facts can stay only in the live session until a threshold commit, `/compact`, or an explicit store happens.
 
 ### Explicit long-term memory writes
 

package/auto-recall.ts

@@ -331,6 +331,7 @@ export async function buildAutoRecallContext(params: {
   rawUserTextPreview?: string;
   queryTruncated?: boolean;
   resourceTypes?: RecallResourceType[];
+  dedupTurns?: number;
 }): Promise<{ block?: string; memoryCount: number; estimatedTokens: number }> {
   const { cfg, client, agentId, actorPeerId, queryText, logger, verbose } = params;
   const queryConfig = params.queryConfig;
@@ -373,7 +374,7 @@ export async function buildAutoRecallContext(params: {
           queryExpansion: "auto",
           maxTokens,
           detail: recallPreferAbstract ? "abstract" : undefined,
-          dedupTurns: params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined,
+          dedupTurns: params.dedupTurns ?? (params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined),
           peerScope: "actor",
           actorPeerId,
           requestTimeoutMs: cfg.autoRecallTimeoutMs,

package/client.ts

@@ -508,6 +508,7 @@ export class OpenVikingClient {
     };
     const body = {
       ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
+      ...(options.dedupTurns === 0 ? { dedup_turns: 0 } : {}),
       query,
       ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
       ...(options.detail !== undefined ? { detail: options.detail } : {}),

package/commands/setup.ts

@@ -6,9 +6,13 @@ import { fileURLToPath } from "node:url";
 import { getEnv } from "../runtime-utils.js";
 import {
   cleanOpenVikingRequestHeaders,
-  resolveOpenVikingRequestHeaders,
   type OpenVikingRequestHeaders,
 } from "../request-headers.js";
+import {
+  createSetupNetworkProbes,
+  type SetupApiKeyProbeResult,
+  type SetupHealthResult,
+} from "../services/setup/probe-service.js";
 
 const HOME = os.homedir();
 const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
@@ -269,14 +273,7 @@ function ask(rl: readline.Interface, prompt: string, defaultValue = ""): Promise
 
 type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
 
-type HealthResult = {
-  ok: boolean;
-  version: string;
-  error: string;
-  compatibility: VersionCompatibility;
-  pluginVersion: string;
-  compatRange: string;
-};
+type HealthResult = SetupHealthResult;
 
 function parseVersionTuple(v: string): number[] | null {
   const cleaned = v.replace(/^v/i, "").split("-")[0];
@@ -317,132 +314,13 @@ function formatCompatRange(): string {
   return "any";
 }
 
-type ApiKeyProbeResult = {
-  keyType: "user_key" | "root_key" | "no_key" | "unknown";
-  needsAccountId: boolean;
-  needsUserId: boolean;
-  detail: string;
-};
-
-async function probeApiKeyType(
-  baseUrl: string,
-  apiKey?: string,
-  configuredHeaders?: OpenVikingRequestHeaders,
-): Promise<ApiKeyProbeResult> {
-  if (!apiKey) return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
-
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 10_000);
-  const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
-  try {
-    const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-    const headers: Record<string, string> = {};
-    headers["X-API-Key"] = apiKey;
-    Object.assign(headers, configuredRequestHeaders);
-    const response = await fetch(sessionsUrl, {
-      headers,
-      signal: controller.signal,
-    });
-
-    if (response.ok) {
-      return { keyType: "user_key", needsAccountId: false, needsUserId: false, detail: "API key has full user context" };
-    }
-
-    // Server raises InvalidArgumentError (-> HTTP 400) when a ROOT key calls
-    // tenant-scoped endpoints without X-OpenViking-Account / X-OpenViking-User.
-    // 401/403 may also be returned by older versions, FastAPI validation can
-    // surface as 422. Treat all four as candidates for tenant-context errors.
-    if ([400, 401, 403, 422].includes(response.status)) {
-      let body = "";
-      try {
-        body = await response.text();
-      } catch { /* ignore parse errors */ }
-      const lower = body.toLowerCase();
-      const needsAccount = /x-openviking-account|account[_ ]?id|account context|tenant/.test(lower);
-      const needsUser = /x-openviking-user|user[_ ]?id|user context|user key/.test(lower);
-      if (needsAccount || needsUser) {
-        return {
-          keyType: "root_key",
-          needsAccountId: needsAccount,
-          needsUserId: needsUser,
-          detail: body.slice(0, 200),
-        };
-      }
-
-      // Body did not name account/user/tenant explicitly (custom auth middleware,
-      // localized message, etc.). Re-probe with placeholder tenant headers; if
-      // the failure was due to missing tenant headers the response will change.
-      try {
-        const probeHeaders: Record<string, string> = {
-          "X-API-Key": apiKey,
-          "X-OpenViking-Account": "__probe__",
-          "X-OpenViking-User": "__probe__",
-          ...configuredRequestHeaders,
-        };
-        const probe2 = await fetch(sessionsUrl, {
-          headers: probeHeaders,
-          signal: controller.signal,
-        });
-        if (probe2.status !== response.status) {
-          return {
-            keyType: "root_key",
-            needsAccountId: true,
-            needsUserId: true,
-            detail: body.slice(0, 200) || `HTTP ${response.status} -> ${probe2.status} after adding tenant headers`,
-          };
-        }
-      } catch { /* ignore probe errors, fall through to unknown */ }
-
-      if (response.status === 401 || response.status === 403) {
-        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status} - authentication failed, verify your API key` };
-      }
-      return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}${body ? ` - ${body.slice(0, 160)}` : ""}` };
-    }
-
-    return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}` };
-  } catch (err) {
-    return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: String(err instanceof Error ? err.message : err) };
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
+type ApiKeyProbeResult = SetupApiKeyProbeResult;
 
-async function checkServiceHealth(
-  baseUrl: string,
-  apiKey?: string,
-  configuredHeaders?: OpenVikingRequestHeaders,
-): Promise<HealthResult> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 10_000);
-  try {
-    const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-    const headers: Record<string, string> = {};
-    if (apiKey) {
-      headers["X-API-Key"] = apiKey;
-    }
-    Object.assign(headers, configuredRequestHeaders);
-    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
-      headers,
-      signal: controller.signal,
-    });
-    if (response.ok) {
-      try {
-        const data = await response.json() as Record<string, unknown>;
-        const result = (data.result ?? data) as Record<string, unknown>;
-        const version = String(result.version ?? data.version ?? "");
-        const compatibility = checkVersionCompatibility(version);
-        return { ok: true, version, error: "", compatibility, pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-      } catch {
-        return { ok: true, version: "", error: "", compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-      }
-    }
-    return { ok: false, version: "", error: `HTTP ${response.status}`, compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-  } catch (err) {
-    return { ok: false, version: "", error: String(err instanceof Error ? err.message : err), compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
+const setupProbes = createSetupNetworkProbes({
+  pluginVersion: PLUGIN_VERSION,
+  compatRange: formatCompatRange(),
+  checkVersionCompatibility,
+});
 
 function readOpenClawConfig(configPath: string): Record<string, unknown> {
   if (!fs.existsSync(configPath)) return {};
@@ -813,7 +691,7 @@ async function runRemoteCheck(
   const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
   const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
   console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-  const health = await checkServiceHealth(baseUrl, apiKey, headers);
+  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
   if (health.ok) {
     const ver = health.version ? ` (version: ${health.version})` : "";
     console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -847,7 +725,7 @@ async function setupNonInteractive(
     }
 
     // Phase 1: validate connectivity and key type BEFORE writing config
-    const health = await checkServiceHealth(baseUrl, apiKey);
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey);
 
     if (!health.ok && !allowOffline) {
       return {
@@ -860,7 +738,7 @@ async function setupNonInteractive(
       };
     }
 
-    const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+    const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey) : undefined;
 
     if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
       const missing: string[] = [];
@@ -996,8 +874,8 @@ async function getStatus(configPath: string): Promise<StatusResult> {
   const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
   const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
   const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
-  const health = await checkServiceHealth(baseUrl, apiKey, headers);
-  const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey, headers) : undefined;
+  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
+  const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey, headers) : undefined;
 
   const peerPrefix = resolveExistingPeerPrefix(existing);
   return {
@@ -1119,7 +997,7 @@ async function setupRemote(
 
   if (apiKey) {
     console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
-    const probe = await probeApiKeyType(baseUrl, apiKey, headers);
+    const probe = await setupProbes.probeApiKeyType(baseUrl, apiKey, headers);
     if (probe.keyType === "root_key") {
       console.log(tr(zh,
         "  ⚠ Root API key detected. accountId and userId are required.",
@@ -1140,7 +1018,7 @@ async function setupRemote(
   console.log("");
 
   console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-  const health = await checkServiceHealth(baseUrl, apiKey || undefined, headers);
+  const health = await setupProbes.checkServiceHealth(baseUrl, apiKey || undefined, headers);
   if (health.ok) {
     const ver = health.version ? ` (version: ${health.version})` : "";
     console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -1204,7 +1082,6 @@ export const __test__ = {
   checkVersionCompatibility,
   parseVersionTuple,
   compareVersions,
-  probeApiKeyType,
   ensureInstallRecord,
   findPluginPackageRoot,
   readCompatRangeFromManifest,

package/context-engine.ts

@@ -245,10 +245,34 @@ function validTokenBudget(raw: unknown): number | undefined {
   return undefined;
 }
 
+// OpenClaw 9.1/9.2 still capture via afterTurn even when commitTurn exists.
+// 9.3 (#140024) defers admitted turns to commitTurn; standalone runners keep
+// afterTurn. The registration API's runtime.version is the HOST version.
+function usesDeferredTurnCapture(version: string | undefined): boolean | undefined {
+  const match = version?.trim().match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/,
+  );
+  if (!match) return undefined;
+  const parts = match.slice(1, 4).map(Number);
+  if (!parts.every(Number.isSafeInteger)) return undefined;
+  const [year, month, day] = parts;
+  // OpenClaw uses 0.0.0 when version metadata cannot be resolved. More generally,
+  // versions outside our supported range cannot prove who owns capture.
+  if (year < 2026 || (year === 2026 && (month < 5 || (month === 5 && day < 27)))) {
+    return undefined;
+  }
+  const boundary = year === 2026 && month === 9 && day === 3;
+  // The 9.3 prerelease train can straddle the host change. Numeric packaging
+  // revisions (-1, -2, ...) refer to the stable release; do not guess for betas.
+  if (boundary && match[4] && !/^\d+$/.test(match[4])) return undefined;
+  return year > 2026 || (year === 2026 && (month > 9 || (month === 9 && day >= 3)));
+}
+
 export function createMemoryOpenVikingContextEngine(params: {
   id: string;
   name: string;
   version?: string;
+  hostVersion?: string;
   cfg: ParsedMemoryOpenVikingConfig;
   logger: Logger;
   getClient: () => Promise<OpenVikingClient>;
@@ -333,6 +357,8 @@ export function createMemoryOpenVikingContextEngine(params: {
   }
 
   const committedTurnKeys = new Set<string>();
+  const inFlightTurns = new Map<string, Promise<void>>();
+  const deferredTurnCapture = usesDeferredTurnCapture(params.hostVersion);
 
   return {
     info: {
@@ -368,6 +394,7 @@ export function createMemoryOpenVikingContextEngine(params: {
         sessionId: assembleParams.sessionId,
         sessionKey: resolveSessionKey(assembleParams),
         messages: assembleParams.messages,
+        prompt: assembleParams.prompt,
         tokenBudget,
         runtimeContext: assembleParams.runtimeContext,
         isMainAssemble,
@@ -388,20 +415,56 @@ export function createMemoryOpenVikingContextEngine(params: {
       });
     },
 
-    // Capture still happens in afterTurn (host calls it per LLM call + on finalize);
-    // commitTurn only acknowledges the accepted turn so OpenClaw drains its outbox.
-    // ponytail: in-memory key set, not durable across restarts — the host outbox is.
-    async commitTurn({ advancementKey, sessionId }): Promise<{ status: "committed" | "duplicate" }> {
+    async commitTurn(commitParams): Promise<{ status: "committed" | "duplicate" }> {
+      const { advancementKey, sessionId } = commitParams;
+      if (deferredTurnCapture === undefined) {
+        // ACKing with an unknown capture owner can discard the only copy in the
+        // host outbox. Reject instead; legacy afterTurn remains available.
+        throw new Error(`openviking: cannot select turn capture for OpenClaw version ${params.hostVersion ?? "(missing)"}`);
+      }
       if (committedTurnKeys.has(advancementKey)) {
         diag("commitTurn_duplicate", sessionId, { advancementKey });
         return { status: "duplicate" };
       }
-      committedTurnKeys.add(advancementKey);
-      if (committedTurnKeys.size > 1024) {
-        committedTurnKeys.delete(committedTurnKeys.values().next().value as string);
+      const pending = inFlightTurns.get(advancementKey);
+      if (pending) {
+        await pending;
+        return { status: "duplicate" };
+      }
+      // Publish the promise before capture begins so concurrent deliveries share
+      // both success and failure. Completion keys are intentionally process-local.
+      const capture = Promise.resolve().then(async () => {
+        if (deferredTurnCapture) {
+          await afterTurnOpenVikingSession({
+            sessionId,
+            sessionKey: resolveSessionKey(commitParams),
+            messages: commitParams.messages,
+            prePromptMessageCount: 0, // Host already supplies the closed-turn range.
+            isHeartbeat: commitParams.isHeartbeat,
+            tokenBudget: 128_000, // Durable delivery does not carry a token budget.
+            throwOnError: true,
+            cfg,
+            getClient,
+            logger,
+            resolveAgentId,
+            rememberSessionAgentId,
+            isBypassedSession,
+            diag,
+          });
+        }
+        committedTurnKeys.add(advancementKey);
+        if (committedTurnKeys.size > 1024) {
+          committedTurnKeys.delete(committedTurnKeys.values().next().value as string);
+        }
+        diag("commitTurn", sessionId, { advancementKey, deferredTurnCapture });
+      });
+      inFlightTurns.set(advancementKey, capture);
+      try {
+        await capture;
+        return { status: "committed" };
+      } finally {
+        inFlightTurns.delete(advancementKey);
       }
-      diag("commitTurn", sessionId, { advancementKey });
-      return { status: "committed" };
     },
 
     async afterTurn(afterTurnParams): Promise<void> {

package/dist/auto-recall.js

@@ -244,7 +244,7 @@ export async function buildAutoRecallContext(params) {
                 queryExpansion: "auto",
                 maxTokens,
                 detail: recallPreferAbstract ? "abstract" : undefined,
-                dedupTurns: params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined,
+                dedupTurns: params.dedupTurns ?? (params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined),
                 peerScope: "actor",
                 actorPeerId,
                 requestTimeoutMs: cfg.autoRecallTimeoutMs,

package/dist/client.js

@@ -205,6 +205,7 @@ export class OpenVikingClient {
         };
         const body = {
             ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
+            ...(options.dedupTurns === 0 ? { dedup_turns: 0 } : {}),
             query,
             ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
             ...(options.detail !== undefined ? { detail: options.detail } : {}),

package/dist/commands/setup.js

@@ -4,7 +4,8 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { getEnv } from "../runtime-utils.js";
-import { cleanOpenVikingRequestHeaders, resolveOpenVikingRequestHeaders, } from "../request-headers.js";
+import { cleanOpenVikingRequestHeaders, } from "../request-headers.js";
+import { createSetupNetworkProbes, } from "../services/setup/probe-service.js";
 const HOME = os.homedir();
 const OPENCLAW_DIR = getEnv("OPENCLAW_STATE_DIR") || path.join(HOME, ".openclaw");
 const DEFAULT_REMOTE_URL = "http://127.0.0.1:1933";
@@ -247,118 +248,11 @@ function formatCompatRange() {
         return `<= ${COMPATIBLE_SERVER_MAX}`;
     return "any";
 }
-async function probeApiKeyType(baseUrl, apiKey, configuredHeaders) {
-    if (!apiKey)
-        return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 10_000);
-    const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
-    try {
-        const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-        const headers = {};
-        headers["X-API-Key"] = apiKey;
-        Object.assign(headers, configuredRequestHeaders);
-        const response = await fetch(sessionsUrl, {
-            headers,
-            signal: controller.signal,
-        });
-        if (response.ok) {
-            return { keyType: "user_key", needsAccountId: false, needsUserId: false, detail: "API key has full user context" };
-        }
-        // Server raises InvalidArgumentError (-> HTTP 400) when a ROOT key calls
-        // tenant-scoped endpoints without X-OpenViking-Account / X-OpenViking-User.
-        // 401/403 may also be returned by older versions, FastAPI validation can
-        // surface as 422. Treat all four as candidates for tenant-context errors.
-        if ([400, 401, 403, 422].includes(response.status)) {
-            let body = "";
-            try {
-                body = await response.text();
-            }
-            catch { /* ignore parse errors */ }
-            const lower = body.toLowerCase();
-            const needsAccount = /x-openviking-account|account[_ ]?id|account context|tenant/.test(lower);
-            const needsUser = /x-openviking-user|user[_ ]?id|user context|user key/.test(lower);
-            if (needsAccount || needsUser) {
-                return {
-                    keyType: "root_key",
-                    needsAccountId: needsAccount,
-                    needsUserId: needsUser,
-                    detail: body.slice(0, 200),
-                };
-            }
-            // Body did not name account/user/tenant explicitly (custom auth middleware,
-            // localized message, etc.). Re-probe with placeholder tenant headers; if
-            // the failure was due to missing tenant headers the response will change.
-            try {
-                const probeHeaders = {
-                    "X-API-Key": apiKey,
-                    "X-OpenViking-Account": "__probe__",
-                    "X-OpenViking-User": "__probe__",
-                    ...configuredRequestHeaders,
-                };
-                const probe2 = await fetch(sessionsUrl, {
-                    headers: probeHeaders,
-                    signal: controller.signal,
-                });
-                if (probe2.status !== response.status) {
-                    return {
-                        keyType: "root_key",
-                        needsAccountId: true,
-                        needsUserId: true,
-                        detail: body.slice(0, 200) || `HTTP ${response.status} -> ${probe2.status} after adding tenant headers`,
-                    };
-                }
-            }
-            catch { /* ignore probe errors, fall through to unknown */ }
-            if (response.status === 401 || response.status === 403) {
-                return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status} - authentication failed, verify your API key` };
-            }
-            return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}${body ? ` - ${body.slice(0, 160)}` : ""}` };
-        }
-        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}` };
-    }
-    catch (err) {
-        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: String(err instanceof Error ? err.message : err) };
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
-async function checkServiceHealth(baseUrl, apiKey, configuredHeaders) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 10_000);
-    try {
-        const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
-        const headers = {};
-        if (apiKey) {
-            headers["X-API-Key"] = apiKey;
-        }
-        Object.assign(headers, configuredRequestHeaders);
-        const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
-            headers,
-            signal: controller.signal,
-        });
-        if (response.ok) {
-            try {
-                const data = await response.json();
-                const result = (data.result ?? data);
-                const version = String(result.version ?? data.version ?? "");
-                const compatibility = checkVersionCompatibility(version);
-                return { ok: true, version, error: "", compatibility, pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-            }
-            catch {
-                return { ok: true, version: "", error: "", compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-            }
-        }
-        return { ok: false, version: "", error: `HTTP ${response.status}`, compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-    }
-    catch (err) {
-        return { ok: false, version: "", error: String(err instanceof Error ? err.message : err), compatibility: "unknown", pluginVersion: PLUGIN_VERSION, compatRange: formatCompatRange() };
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
+const setupProbes = createSetupNetworkProbes({
+    pluginVersion: PLUGIN_VERSION,
+    compatRange: formatCompatRange(),
+    checkVersionCompatibility,
+});
 function readOpenClawConfig(configPath) {
     if (!fs.existsSync(configPath))
         return {};
@@ -624,7 +518,7 @@ async function runRemoteCheck(zh, existing) {
     const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
     const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
     console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-    const health = await checkServiceHealth(baseUrl, apiKey, headers);
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
     if (health.ok) {
         const ver = health.version ? ` (version: ${health.version})` : "";
         console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -644,7 +538,7 @@ async function setupNonInteractive(configPath, params) {
             throw new Error("peer_prefix may only contain letters, digits, underscores, and hyphens, or be empty");
         }
         // Phase 1: validate connectivity and key type BEFORE writing config
-        const health = await checkServiceHealth(baseUrl, apiKey);
+        const health = await setupProbes.checkServiceHealth(baseUrl, apiKey);
         if (!health.ok && !allowOffline) {
             return {
                 success: false,
@@ -655,7 +549,7 @@ async function setupNonInteractive(configPath, params) {
                 error: `Server unreachable: ${health.error}. Use --allow-offline to save config anyway.`,
             };
         }
-        const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey) : undefined;
+        const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey) : undefined;
         if (keyProbe?.keyType === "root_key" && (!accountId || !userId)) {
             const missing = [];
             if (!accountId)
@@ -793,8 +687,8 @@ async function getStatus(configPath) {
     const baseUrl = String(existing.baseUrl ?? DEFAULT_REMOTE_URL);
     const apiKey = existing.apiKey ? String(existing.apiKey) : undefined;
     const headers = nonEmptyOpenVikingRequestHeaders(existing.headers);
-    const health = await checkServiceHealth(baseUrl, apiKey, headers);
-    const keyProbe = health.ok ? await probeApiKeyType(baseUrl, apiKey, headers) : undefined;
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey, headers);
+    const keyProbe = health.ok ? await setupProbes.probeApiKeyType(baseUrl, apiKey, headers) : undefined;
     const peerPrefix = resolveExistingPeerPrefix(existing);
     return {
         configured: true,
@@ -887,7 +781,7 @@ async function setupRemote(zh, configPath, existing, q) {
     let userId = existing?.userId ? String(existing.userId) : "";
     if (apiKey) {
         console.log(tr(zh, "  Detecting API key type...", "  正在检测 API Key 类型..."));
-        const probe = await probeApiKeyType(baseUrl, apiKey, headers);
+        const probe = await setupProbes.probeApiKeyType(baseUrl, apiKey, headers);
         if (probe.keyType === "root_key") {
             console.log(tr(zh, "  ⚠ Root API key detected. accountId and userId are required.", "  ⚠ 检测到 Root API Key，需要提供 accountId 和 userId。"));
             accountId = await q(tr(zh, "Account ID (required for root key)", "Account ID（root key 必填）"), accountId);
@@ -903,7 +797,7 @@ async function setupRemote(zh, configPath, existing, q) {
         : "";
     console.log("");
     console.log(tr(zh, `Testing connectivity to ${baseUrl}...`, `正在测试连接 ${baseUrl}...`));
-    const health = await checkServiceHealth(baseUrl, apiKey || undefined, headers);
+    const health = await setupProbes.checkServiceHealth(baseUrl, apiKey || undefined, headers);
     if (health.ok) {
         const ver = health.version ? ` (version: ${health.version})` : "";
         console.log(`  ✓ ${tr(zh, `Connected successfully${ver}`, `连接成功${ver}`)}`);
@@ -969,7 +863,6 @@ export const __test__ = {
     checkVersionCompatibility,
     parseVersionTuple,
     compareVersions,
-    probeApiKeyType,
     ensureInstallRecord,
     findPluginPackageRoot,
     readCompatRangeFromManifest,