@openviking/openclaw-plugin 2026.9.4 → 2026.9.8-1

package/INSTALL-AGENT.md

@@ -42,6 +42,7 @@ Before setup, determine:
 | --- | --- | --- |
 | OpenViking base URL | Yes | Ask user or read `OPENVIKING_BASE_URL` |
 | API key | Usually | Ask user or read `OPENVIKING_API_KEY` |
+| Memory scope | Optional; default `none` | Ask whether memory is shared, separated by assistant, or separated by sender. Use `sender`; accept legacy `person` as an alias. |
 | Account ID | Only for root API keys | Ask user if setup reports root-key tenant context is needed |
 | User ID | Only for root API keys | Ask user if setup reports root-key tenant context is needed |
 | Slot replacement approval | Only if another context engine owns the slot | Ask user before using `--force-slot` |
@@ -73,6 +74,23 @@ Run setup with `--json` whenever possible:
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 ```
 
+Choose memory scope before building that command:
+
+| Value | Concrete layout | Use when |
+| --- | --- | --- |
+| `none` (default; omit the flag) | Shared `viking://user/<user_id>/memories/...`; no concrete peer memory subtree | General case |
+| `assistant` | Assistant-attributed peer memory under `.../peers/<assistant_id>/memories/...` | A human is the OpenViking user and uses multiple OpenClaw assistants |
+| `sender` | Sender-attributed peer memory under `.../peers/<sender_id>/memories/...` | An agent is the OpenViking user and receives messages from multiple humans |
+
+`person` is a legacy alias for `sender`. Accept it from existing config or user input, but write `sender` in new setup commands. OpenViking initializes the managed `peers/` container for every user; `none` only means that no concrete `peers/<peer_id>/memories` subtree is used. Actor-peer recall includes shared user memory plus the current peer memory, and changing the scope does not move existing memories.
+
+Examples:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --json
+```
+
 Branch on the result:
 
 | JSON result | Meaning | Agent action |
@@ -96,10 +114,10 @@ openclaw openviking setup \
   --json
 ```
 
-Custom agent routing prefix (optional; only when the user explicitly requests a prefix):
+Custom assistant routing prefix (optional; only with `peer_role=assistant` and when the user explicitly requests a prefix):
 
 ```bash
-openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-prefix <PREFIX> --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
 Slot replacement retry, only after user approval:
@@ -139,6 +157,7 @@ Also inspect:
 | `health.version` | Records server version |
 | `health.compatibility` | Determines whether to warn |
 | `config.hasApiKey` | Confirms whether an API key was saved |
+| `config.peer_role` | Confirms `none`, `assistant`, or canonical `sender` scope |
 | `config.peer_prefix` | Confirms configured peer prefix when present |
 
 ## Environment Detection
@@ -267,7 +286,8 @@ Core fields:
 | `mode` | Legacy compatibility field. Expected value: `remote`. |
 | `baseUrl` | OpenViking HTTP endpoint |
 | `apiKey` | OpenViking API key |
-| `peer_prefix` | Optional; prefix for OpenClaw agent IDs when set. Interactive setup accepts only letters, digits, `_`, and `-`. If unset, the plugin follows session agent IDs. |
+| `peer_role` | `none` (shared user memory), `assistant` (`peers/<assistant_id>`), or `sender` (`peers/<sender_id>`). Legacy `person` is accepted as `sender`. |
+| `peer_prefix` | Optional only with `peer_role=assistant`; prefix for OpenClaw agent IDs. Interactive setup accepts only letters, digits, `_`, and `-`. If unset, the plugin follows session agent IDs. |
 | `accountId` | Required for root API keys |
 | `userId` | Required for root API keys |
 
@@ -329,7 +349,8 @@ Existing config fields are preserved during migration. The new plugin reads old
 
 - `baseUrl`
 - `apiKey`
-- `peer_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`
+- `peer_role`: optional; `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender`
+- `peer_prefix`: optional only with `peer_role=assistant`; interactive setup accepts only letters, digits, `_`, and `-`
 
 ## Backup Path: ov-install
 

package/INSTALL-ZH.md

@@ -197,12 +197,30 @@ openclaw openviking setup \
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
 ```
 
-如需给默认 assistant peer 路由增加前缀，可以额外传：
+根据 OpenViking user 代表谁来选择 `--peer-role`：
+
+| 值 | 存储示例 | 适用场景 |
+| --- | --- | --- |
+| `none`（默认） | `viking://user/alice/memories/...` | 该 OpenViking 用户下的所有对话共享 user-level 记忆，不使用具体 peer 的记忆子树。 |
+| `assistant` | `viking://user/alice/peers/main/memories/...` | OpenViking user 代表人，并希望把 assistant 归因的 peer 记忆按不同 OpenClaw 助手分开。 |
+| `sender` | `viking://user/support-agent/peers/customer-42/memories/...` | OpenViking user 代表 agent，并希望把 sender 归因的 peer 记忆按不同发送者分开。 |
+
+`person` 仍作为 `sender` 的旧配置别名被兼容；新配置请使用 `sender`。
+
+例如，让每个助手使用独立的 peer 记忆，并可选给 assistant id 加前缀：
 
 ```bash
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
+如果 OpenViking user 是 agent，按给它发消息的 sender 分开 peer 记忆：
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --json
+```
+
+OpenViking 会为每个用户初始化受管的 `peers/` 容器。`none` 表示插件不创建、也不路由到具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆；切换配置不会搬迁已有记忆。
+
 #### 无法执行 CLI 时直接配置文件
 
 如果容器内无法执行 `openclaw` CLI，可以把以下字段合并到 OpenClaw 实际读取的配置文件。设置了 `OPENCLAW_CONFIG_PATH` 时使用该路径；否则通常是 `$OPENCLAW_STATE_DIR/openclaw.json`（默认 `~/.openclaw/openclaw.json`）。
@@ -300,7 +318,7 @@ plugins.entries.openviking.config
 | `mode` | `remote` | 兼容旧配置的字段。当前只支持 remote。 |
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP 地址 |
 | `apiKey` | 空 | OpenViking API key |
-| `peer_role` | `assistant` | Peer 身份模式：`none`、`assistant` 或 `person`。Session message 使用 body `peer_id`；数据面 recall/search 使用 `X-OpenViking-Actor-Peer`。 |
+| `peer_role` | `none` | 记忆归属：`none`（共享 `viking://user/<user_id>/memories`）、`assistant`（`.../peers/<assistant_id>/memories`）或 `sender`（`.../peers/<sender_id>/memories`）。旧值 `person` 作为 `sender` 的别名兼容。Session message 使用 body `peer_id`；数据面 recall/search 使用 `X-OpenViking-Actor-Peer`。 |
 | `peer_prefix` | 空 | `peer_role=assistant` 时 assistant `peer_id` / actor peer 值的可选前缀。 |
 | `accountId` | 空 | 使用 root API key 时需要 |
 | `userId` | 空 | 使用 root API key 时需要 |
@@ -325,7 +343,7 @@ openclaw config get plugins.entries.openviking.config
 | --- | --- | --- |
 | `baseUrl` | `http://127.0.0.1:1933` | 远端 OpenViking 服务地址 |
 | `apiKey` | 空 | 远端 OpenViking API Key；服务端未开启认证时可不填 |
-| `peer_role` | `assistant` | Peer 身份模式：`none`、`assistant` 或 `person`；session message 使用 body `peer_id`，数据面 recall/search 使用 `X-OpenViking-Actor-Peer` |
+| `peer_role` | `none` | 记忆归属：`none`、`assistant` 或 `sender`；旧值 `person` 作为 `sender` 的别名兼容。Session message 使用 body `peer_id`，数据面 recall/search 使用 `X-OpenViking-Actor-Peer` |
 | `peer_prefix` | 空 | `peer_role=assistant` 时 assistant `peer_id` / actor peer 值的可选前缀 |
 
 常见设置：
@@ -387,7 +405,7 @@ ov-install
 | `--current-version` | 查看 helper 记录的当前版本 |
 | `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
 | `--api-key KEY` | OpenViking API key |
-| `--peer-role ROLE` | Peer role：`none`、`assistant` 或 `person` |
+| `--peer-role ROLE` | 记忆归属：`none`、`assistant` 或 `sender`；旧值 `person` 作为 `sender` 的别名兼容 |
 | `--peer-prefix PREFIX` | assistant `peer_id` / actor peer 值的前缀 |
 | `--update` | 更新 helper 管理的安装 |
 

package/INSTALL.md

@@ -141,12 +141,30 @@ If another context engine already owns the slot, setup will not replace it by de
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
 ```
 
-If you want assistant messages to carry a prefixed `peer_id` and data-plane recall/search requests to use the matching actor peer view, pass a prefix explicitly:
+Choose `--peer-role` from what the OpenViking user represents:
+
+| Value | Storage example | Use when |
+| --- | --- | --- |
+| `none` (default) | `viking://user/alice/memories/...` | All conversations for this OpenViking user share user-level memory. No peer-specific memory subtree is used. |
+| `assistant` | `viking://user/alice/peers/main/memories/...` | The OpenViking user is a human and assistant-attributed peer memory should be separated by OpenClaw assistant. |
+| `sender` | `viking://user/support-agent/peers/customer-42/memories/...` | The OpenViking user is an agent and sender-attributed peer memory should be separated by human sender. |
+
+`person` is still accepted as a legacy alias for `sender`. New configuration should use `sender`.
+
+For example, give each assistant its own peer memory and optionally namespace the assistant id:
 
 ```bash
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
+Or scope peer memory by the sender talking to an agent:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --json
+```
+
+OpenViking initializes the managed `peers/` container for every user. `none` means the plugin does not create or route into a concrete `peers/<peer_id>/memories` subtree. Actor-peer recall includes shared user memory plus the current peer memory, and changing the setting does not move existing memories.
+
 #### Configure The File Directly When The CLI Is Unavailable
 
 If the `openclaw` CLI cannot run inside the container, merge the following fields into the config file that OpenClaw actually reads. Use `OPENCLAW_CONFIG_PATH` when it is set; otherwise the file is usually `$OPENCLAW_STATE_DIR/openclaw.json` (default: `~/.openclaw/openclaw.json`).
@@ -244,7 +262,7 @@ Core fields:
 | `mode` | `remote` | Legacy compatibility field. Only remote mode is supported. |
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint |
 | `apiKey` | empty | OpenViking API key |
-| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
+| `peer_role` | `none` | Memory scope: `none` (shared `viking://user/<user_id>/memories`), `assistant` (`.../peers/<assistant_id>/memories`), or `sender` (`.../peers/<sender_id>/memories`). Legacy `person` is accepted as `sender`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
 | `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant`. |
 | `accountId` | empty | Required when using a root API key |
 | `userId` | empty | Required when using a root API key |
@@ -311,7 +329,7 @@ Useful backup/source flags:
 | `--current-version` | Print the version tracked by the helper |
 | `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
 | `--api-key KEY` | OpenViking API key |
-| `--peer-role ROLE` | Peer role: `none`, `assistant`, or `person` |
+| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender` |
 | `--peer-prefix PREFIX` | Prefix for assistant `peer_id` / actor peer values |
 | `--update` | Update an existing helper-managed install |
 
@@ -356,7 +374,7 @@ The plugin connects to an existing remote OpenViking server.
 | --- | --- | --- |
 | `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |
 | `apiKey` | empty | Optional OpenViking API key |
-| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`; session messages use body `peer_id`, while data-plane recall/search uses `X-OpenViking-Actor-Peer` |
+| `peer_role` | `none` | Memory scope: `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender`. Session messages use body `peer_id`, while data-plane recall/search uses `X-OpenViking-Actor-Peer` |
 | `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant` |
 
 Common settings:

package/README.md

@@ -124,15 +124,26 @@ The main rules are:
 - reuse `sessionId` directly when it is already a UUID
 - prefer `sessionKey` when deriving a stable `ovSessionId`
 - normalize unsafe path characters, or fall back to a stable SHA-256 when needed
-- `peer_role=assistant` is the default and writes assistant messages with `peer_id=<sessionAgent>`; if `peer_prefix` is set, the value becomes `<peer_prefix>_<sessionAgent>`
-- `peer_role=none` disables peer message attribution and actor-peer routing
-- `peer_role=person` writes user messages with `peer_id` derived from OpenClaw sender identity; assistant messages do not get `peer_id`
-- data-plane recall/search/read/import/delete sends the same resolved peer identity as `X-OpenViking-Actor-Peer` when `peer_role` is `assistant` or `person`
+- `peer_role=none` is the default: messages have no peer attribution and memory stays in the shared user scope, for example `viking://user/alice/memories/...`; no peer-specific memory subtree is used
+- `peer_role=assistant` writes assistant messages with `peer_id=<sessionAgent>` and uses peer-scoped memory such as `viking://user/alice/peers/main/memories/...`; if `peer_prefix` is set, the peer id becomes `<peer_prefix>_<sessionAgent>`
+- `peer_role=sender` writes user messages with the OpenClaw sender identity as `peer_id` and uses peer-scoped memory such as `viking://user/support-agent/peers/customer-42/memories/...`; assistant messages do not get `peer_id`
+- `person` remains accepted as a legacy config alias for `sender`, but new configuration and documentation use `sender`
+- data-plane recall/search/read/import/delete sends the same resolved peer identity as `X-OpenViking-Actor-Peer` when `peer_role` is `assistant` or `sender`
 - when OpenClaw does not provide a session agent, use its default agent `main` for local session and assistant peer metadata
 - only add `X-OpenViking-Account` / `X-OpenViking-User` when `accountId` / `userId` are explicitly configured
 
 This matters because OpenViking tenant identity is account/user-scoped, while OpenClaw agent identity is runtime metadata.
 
+Choose the scope from what `viking://user/<user_id>` represents:
+
+| Model | Example | Result |
+| --- | --- | --- |
+| General/shared (`none`) | `user_id=alice` uses any OpenClaw assistant | Shared user memory under `viking://user/alice/memories/...` |
+| Human is the OpenViking user (`assistant`) | Alice uses OpenClaw assistants `main` and `research` | Assistant-scoped memories are separated under `.../peers/main/memories/...` and `.../peers/research/memories/...` |
+| Agent is the OpenViking user (`sender`) | `user_id=support-agent` receives messages from `customer-42` and `customer-99` | Sender-scoped memories are separated under `.../peers/customer-42/memories/...` and `.../peers/customer-99/memories/...` |
+
+OpenViking creates the managed `peers/` container as part of the user namespace. `none` means that the plugin does not create or route into a specific `peers/<peer_id>/memories` subtree. With `assistant` or `sender`, actor-peer recall includes the shared user memory plus the current peer's memory; changing the setting does not move existing memories.
+
 The recommended remote-mode configuration only needs:
 
 - `baseUrl`
@@ -143,7 +154,7 @@ The recommended remote-mode configuration only needs:
 In this setup:
 
 - `apiKey` should usually be a user key
-- new installs default to `peer_role=assistant`
+- new installs default to `peer_role=none`
 - `accountId` / `userId` are advanced options only when the deployment needs explicit identity headers, such as root-key or trusted-server flows
 
 ### User namespace

package/client.ts

@@ -1,12 +1,3 @@
-import { randomUUID } from "node:crypto";
-import { once } from "node:events";
-import { createWriteStream } from "node:fs";
-import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
-
-import { Zip, ZipDeflate } from "fflate";
-
 import { defaultHttpTransport, type HttpTransport } from "./adapters/http-transport.js";
 import {
   defaultResourcePackager,
@@ -255,23 +246,6 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-const MEMORY_URI_PATTERNS = [
-  /^viking:\/\/user\/(?:[^/]+\/)?memories(?:\/|$)/,
-];
-const REMOTE_RESOURCE_PREFIXES = ["http://", "https://", "git@", "ssh://", "git://"];
-
-export function isMemoryUri(uri: string): boolean {
-  return MEMORY_URI_PATTERNS.some((pattern) => pattern.test(uri));
-}
-
-function isRemoteResourceSource(source: string): boolean {
-  return REMOTE_RESOURCE_PREFIXES.some((prefix) => source.startsWith(prefix));
-}
-
-function toBlobPart(value: Buffer): ArrayBuffer {
-  return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) as ArrayBuffer;
-}
-
 function resolveWaitRequestTimeoutMs(defaultTimeoutMs: number, waitTimeoutSeconds?: number): number {
   const requestedMs =
     typeof waitTimeoutSeconds === "number" && Number.isFinite(waitTimeoutSeconds) && waitTimeoutSeconds > 0
@@ -280,14 +254,6 @@ function resolveWaitRequestTimeoutMs(defaultTimeoutMs: number, waitTimeoutSecond
   return Math.max(defaultTimeoutMs, requestedMs);
 }
 
-async function cleanupUploadTempPath(path?: string): Promise<void> {
-  if (!path) {
-    return;
-  }
-  await rm(path, { force: true }).catch(() => undefined);
-  await rm(dirname(path), { recursive: true, force: true }).catch(() => undefined);
-}
-
 export class OpenVikingClient {
   private readonly transport: HttpTransport;
   private readonly configuredHeaders: Record<string, string>;
@@ -685,63 +651,6 @@ export class OpenVikingClient {
     return result.temp_file_id;
   }
 
-  async zipDirectoryForUpload(dirPath: string): Promise<string> {
-    const rootStats = await stat(dirPath);
-    if (!rootStats.isDirectory()) {
-      throw new Error(`Not a directory: ${dirPath}`);
-    }
-
-    const zipDir = await mkdtemp(join(tmpdir(), "openviking-openclaw-upload-"));
-    const zipPath = join(zipDir, `${basename(dirPath).replace(/[^a-zA-Z0-9._-]/g, "_")}-${randomUUID()}.zip`);
-    const output = createWriteStream(zipPath);
-    const outputClosed = once(output, "close");
-    const outputErrored = once(output, "error").then(([err]) => Promise.reject(err));
-    const zip = new Zip((err, chunk, final) => {
-      if (err) {
-        output.destroy(err);
-        return;
-      }
-      if (chunk?.length) {
-        output.write(Buffer.from(chunk));
-      }
-      if (final) {
-        output.end();
-      }
-    });
-
-    const walk = async (currentDir: string) => {
-      const entries = await readdir(currentDir, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = join(currentDir, entry.name);
-        if (entry.isDirectory()) {
-          await walk(fullPath);
-          continue;
-        }
-        if (!entry.isFile()) {
-          continue;
-        }
-        const relPath = relative(dirPath, fullPath).replace(/\\/g, "/");
-        if (!relPath || relPath.startsWith("../") || relPath.includes("/../")) {
-          throw new Error(`Unsafe relative path while zipping: ${relPath}`);
-        }
-        const file = new ZipDeflate(relPath);
-        zip.add(file);
-        file.push(new Uint8Array(await readFile(fullPath)), true);
-      }
-    };
-    try {
-      await walk(dirPath);
-      zip.end();
-      await Promise.race([outputClosed, outputErrored]);
-    } catch (err) {
-      zip.terminate();
-      output.destroy(err as Error);
-      await cleanupUploadTempPath(zipPath);
-      throw err;
-    }
-    return zipPath;
-  }
-
   async addResource(input: AddResourceInput, actorPeerId?: string): Promise<AddResourceResult> {
     const pathOrUrl = input.pathOrUrl.trim();
     if (!pathOrUrl) {

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");
@@ -84,8 +88,8 @@ const CONFIG_KEYS_TO_PRESERVE = [
   "logFindRequests",
 ] as const;
 
-type PeerRole = "none" | "assistant" | "person";
-const DEFAULT_SETUP_PEER_ROLE: PeerRole = "assistant";
+type PeerRole = "none" | "assistant" | "sender";
+const DEFAULT_SETUP_PEER_ROLE: PeerRole = "none";
 type RecallTargetType = "resource" | "user" | "agent";
 const ALLOWED_RECALL_TARGET_TYPES = ["resource", "user", "agent"] as const;
 
@@ -126,7 +130,8 @@ function isValidPeerPrefixInput(value: string): boolean {
 function normalizePeerRole(value: unknown): PeerRole | undefined {
   if (typeof value !== "string") return undefined;
   const role = value.trim().toLowerCase();
-  if (role === "none" || role === "assistant" || role === "person") return role;
+  if (role === "person") return "sender";
+  if (role === "none" || role === "assistant" || role === "sender") return role;
   return undefined;
 }
 
@@ -147,7 +152,7 @@ function resolveSetupPeerRole(value: unknown): PeerRole {
   if (value === undefined) return DEFAULT_SETUP_PEER_ROLE;
   const role = normalizePeerRole(value);
   if (role) return role;
-  throw new Error('peer_role must be "none", "assistant", or "person"');
+  throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');
 }
 
 function normalizeSetupRecallTargetTypes(value: unknown): RecallTargetType[] | undefined {
@@ -206,9 +211,20 @@ async function askPeerRole(
   q: (prompt: string, def?: string) => Promise<string>,
   defaultValue: PeerRole,
 ): Promise<PeerRole> {
+  console.log(
+    `  ${tr(
+      zh,
+      "Memory scope — none (default): viking://user/<user_id>/memories, shared across all conversations; " +
+        "assistant: viking://user/<user_id>/peers/<assistant_id>/memories; " +
+        "sender: viking://user/<user_id>/peers/<sender_id>/memories (legacy alias: person).",
+      "记忆归属 —— none（默认）：viking://user/<user_id>/memories，所有对话共享；" +
+        "assistant：viking://user/<user_id>/peers/<assistant_id>/memories；" +
+        "sender：viking://user/<user_id>/peers/<sender_id>/memories（兼容旧值 person）。",
+    )}`,
+  );
   while (true) {
     const value = await q(
-      tr(zh, "Peer Role (none/assistant/person)", "Peer Role（none/assistant/person）"),
+      tr(zh, "Memory scope (none/assistant/sender)", "记忆归属（none/assistant/sender）"),
       defaultValue,
     );
     const role = normalizePeerRole(value);
@@ -216,8 +232,8 @@ async function askPeerRole(
     console.log(
       `  ✗ ${tr(
         zh,
-        'Peer Role must be "none", "assistant", or "person".',
-        'Peer Role 必须是 "none"、"assistant" 或 "person"。',
+        'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).',
+        '记忆归属必须是 "none"、"assistant" 或 "sender"（也兼容旧值 "person"）。',
       )}`,
     );
   }
@@ -257,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];
@@ -305,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 */ }
+type ApiKeyProbeResult = SetupApiKeyProbeResult;
 
-      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: 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 {};
@@ -605,7 +495,7 @@ export function registerSetupCli(api: any): void {
         .option("--zh", "Chinese prompts")
         .option("--base-url <url>", "OpenViking server URL (enables non-interactive mode)")
         .option("--api-key <key>", "API key for authentication")
-        .option("--peer-role <role>", "Peer ID role: none, assistant, or person")
+        .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")
         .option("--peer-prefix <prefix>", "Prefix for assistant peer_id values")
         .option("--account-id <id>", "Account ID (required for root API keys)")
         .option("--user-id <id>", "User ID (required for root API keys)")
@@ -801,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}`)}`);
@@ -835,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 {
@@ -848,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[] = [];
@@ -984,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 {
@@ -1107,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.",
@@ -1128,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}`)}`);
@@ -1182,6 +1072,8 @@ async function setupRemote(
 export const __test__ = {
   isLegacyLocalMode,
   isValidPeerPrefixInput,
+  normalizePeerRole,
+  resolveSetupPeerRole,
   normalizeSetupRecallTargetTypes,
   activateContextEngineSlot,
   isContextEngineSlotActive,
@@ -1190,7 +1082,6 @@ export const __test__ = {
   checkVersionCompatibility,
   parseVersionTuple,
   compareVersions,
-  probeApiKeyType,
   ensureInstallRecord,
   findPluginPackageRoot,
   readCompatRangeFromManifest,