@openviking/openclaw-plugin 2026.9.24 → 2026.10.1

package/INSTALL-AGENT.md

@@ -42,7 +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. |
+| Memory scope | Optional; default `none` | Ask whether memory is shared, separated by assistant, or separated by sender. Use `sender`. |
 | 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` |
@@ -82,7 +82,7 @@ Choose memory scope before building that command:
 | `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.
+Setup rejects `person`; always pass `sender`. An existing config that still says `person` keeps working as `sender`. 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:
 

package/INSTALL-ZH.md

@@ -205,7 +205,7 @@ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --forc
 | `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`。
+安装和 setup 只接受 `sender`；已有配置里的 `person` 仍按 `sender` 生效。
 
 例如，让每个助手使用独立的 peer 记忆，并可选给 assistant id 加前缀：
 
@@ -405,7 +405,7 @@ ov-install
 | `--current-version` | 查看 helper 记录的当前版本 |
 | `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
 | `--api-key KEY` | OpenViking API key |
-| `--peer-role ROLE` | 记忆归属：`none`、`assistant` 或 `sender`；旧值 `person` 作为 `sender` 的别名兼容 |
+| `--peer-role ROLE` | 记忆归属：`none`、`assistant` 或 `sender` |
 | `--peer-prefix PREFIX` | assistant `peer_id` / actor peer 值的前缀 |
 | `--update` | 更新 helper 管理的安装 |
 

package/INSTALL.md

@@ -149,7 +149,7 @@ Choose `--peer-role` from what the OpenViking user represents:
 | `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`.
+Setup and the installer accept only `sender`. An existing config that still says `person` keeps working as `sender`.
 
 For example, give each assistant its own peer memory and optionally namespace the assistant id:
 
@@ -329,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` | Memory scope: `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender` |
+| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender` |
 | `--peer-prefix PREFIX` | Prefix for assistant `peer_id` / actor peer values |
 | `--update` | Update an existing helper-managed install |
 

package/commands/setup.ts

@@ -136,6 +136,12 @@ function normalizePeerRole(value: unknown): PeerRole | undefined {
   return undefined;
 }
 
+// `person` survives only in existing configs; setup input must say `sender`.
+function normalizePeerRoleInput(value: unknown): PeerRole | undefined {
+  if (typeof value === "string" && value.trim().toLowerCase() === "person") return undefined;
+  return normalizePeerRole(value);
+}
+
 function resolveExistingPeerRole(existing: Record<string, unknown> | null | undefined): PeerRole {
   const explicit = normalizePeerRole(existing?.peer_role);
   if (explicit) return explicit;
@@ -151,9 +157,9 @@ function resolveExistingPeerPrefix(existing: Record<string, unknown> | null | un
 
 function resolveSetupPeerRole(value: unknown): PeerRole {
   if (value === undefined) return DEFAULT_SETUP_PEER_ROLE;
-  const role = normalizePeerRole(value);
+  const role = normalizePeerRoleInput(value);
   if (role) return role;
-  throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');
+  throw new Error('peer_role must be "none", "assistant", or "sender" ("person" was renamed to "sender")');
 }
 
 function normalizeSetupRecallTargetTypes(value: unknown): RecallTargetType[] | undefined {
@@ -217,10 +223,10 @@ async function askPeerRole(
       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).",
+        "sender: viking://user/<user_id>/peers/<sender_id>/memories.",
       "记忆归属 —— 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）。",
+        "sender：viking://user/<user_id>/peers/<sender_id>/memories。",
     )}`,
   );
   while (true) {
@@ -228,13 +234,13 @@ async function askPeerRole(
       tr(zh, "Memory scope (none/assistant/sender)", "记忆归属（none/assistant/sender）"),
       defaultValue,
     );
-    const role = normalizePeerRole(value);
+    const role = normalizePeerRoleInput(value);
     if (role) return role;
     console.log(
       `  ✗ ${tr(
         zh,
-        'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).',
-        '记忆归属必须是 "none"、"assistant" 或 "sender"（也兼容旧值 "person"）。',
+        'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").',
+        '记忆归属必须是 "none"、"assistant" 或 "sender"（"person" 已更名为 "sender"）。',
       )}`,
     );
   }
@@ -496,7 +502,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>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")
+        .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender)")
         .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)")

package/dist/commands/setup.js

@@ -106,6 +106,12 @@ function normalizePeerRole(value) {
         return role;
     return undefined;
 }
+// `person` survives only in existing configs; setup input must say `sender`.
+function normalizePeerRoleInput(value) {
+    if (typeof value === "string" && value.trim().toLowerCase() === "person")
+        return undefined;
+    return normalizePeerRole(value);
+}
 function resolveExistingPeerRole(existing) {
     const explicit = normalizePeerRole(existing?.peer_role);
     if (explicit)
@@ -122,10 +128,10 @@ function resolveExistingPeerPrefix(existing) {
 function resolveSetupPeerRole(value) {
     if (value === undefined)
         return DEFAULT_SETUP_PEER_ROLE;
-    const role = normalizePeerRole(value);
+    const role = normalizePeerRoleInput(value);
     if (role)
         return role;
-    throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');
+    throw new Error('peer_role must be "none", "assistant", or "sender" ("person" was renamed to "sender")');
 }
 function normalizeSetupRecallTargetTypes(value) {
     if (value === undefined || value === null || value === "") {
@@ -178,15 +184,15 @@ function preserveCurrentConfig(existing) {
 async function askPeerRole(zh, q, defaultValue) {
     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，所有对话共享；" +
+        "sender: viking://user/<user_id>/peers/<sender_id>/memories.", "记忆归属 —— 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）。")}`);
+        "sender：viking://user/<user_id>/peers/<sender_id>/memories。")}`);
     while (true) {
         const value = await q(tr(zh, "Memory scope (none/assistant/sender)", "记忆归属（none/assistant/sender）"), defaultValue);
-        const role = normalizePeerRole(value);
+        const role = normalizePeerRoleInput(value);
         if (role)
             return role;
-        console.log(`  ✗ ${tr(zh, 'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).', '记忆归属必须是 "none"、"assistant" 或 "sender"（也兼容旧值 "person"）。')}`);
+        console.log(`  ✗ ${tr(zh, 'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").', '记忆归属必须是 "none"、"assistant" 或 "sender"（"person" 已更名为 "sender"）。')}`);
     }
 }
 async function askPeerPrefix(zh, q, defaultValue) {
@@ -375,7 +381,7 @@ export function registerSetupCli(api) {
             .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>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")
+            .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender)")
             .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)")

package/dist/plugin/openviking-session-routing-runtime.js

@@ -50,6 +50,7 @@ export function createOpenVikingSessionRoutingRuntime(options) {
                 peerRole,
                 senderPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
                 assistantPeerId: agentId,
+                warn: (message) => options.logger.warn(message),
             }),
         };
     };

package/dist/routing/identity-routing.js

@@ -20,13 +20,21 @@ export function resolveOpenVikingMessagePeerId(params) {
     }
     return undefined;
 }
+/**
+ * Peer scoping is soft isolation. OpenClaw does not hand every path a sender
+ * (context-engine assemble gets no runtimeContext; cron and heartbeat turns
+ * have no sender at all), so a missing one widens to the unscoped request a
+ * caller without X-OpenViking-Actor-Peer gets, with a warning, rather than
+ * taking OpenViking away for the turn.
+ */
 export function resolveOpenVikingActorPeerId(params) {
     const actorPeerId = resolveOpenVikingMessagePeerId({
         ...params,
         role: params.peerRole === "sender" ? "user" : "assistant",
     });
     if (params.peerRole === "sender" && !actorPeerId) {
-        throw new Error("openviking: peer_role=sender requires a sender identity");
+        params.warn?.("openviking: peer_role=sender but OpenClaw supplied no sender identity; " +
+            "continuing as an unscoped request under this user (no X-OpenViking-Actor-Peer)");
     }
     return actorPeerId;
 }

package/dist/services/context-lifecycle-service.js

@@ -207,6 +207,7 @@ async function recallForAssemble(params, recallQuery) {
         peerRole: cfg.peer_role ?? "none",
         senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
         assistantPeerId: agentId,
+        warn: (message) => logger.warn?.(message),
     });
     const queryConfig = await queryConfigStore?.getEffective({
         agentId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.9.24",
+  "version": "2026.10.1",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",

package/plugin/openviking-session-routing-runtime.ts

@@ -9,6 +9,7 @@ import {
 
 type Logger = {
   info: (message: string) => void;
+  warn: (message: string) => void;
 };
 
 export type SessionAgentLookup = {
@@ -99,6 +100,7 @@ export function createOpenVikingSessionRoutingRuntime(options: {
         peerRole,
         senderPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
         assistantPeerId: agentId,
+        warn: (message) => options.logger.warn(message),
       }),
     };
   };

package/routing/identity-routing.ts

@@ -41,17 +41,28 @@ export function resolveOpenVikingMessagePeerId(params: {
   return undefined;
 }
 
+/**
+ * Peer scoping is soft isolation. OpenClaw does not hand every path a sender
+ * (context-engine assemble gets no runtimeContext; cron and heartbeat turns
+ * have no sender at all), so a missing one widens to the unscoped request a
+ * caller without X-OpenViking-Actor-Peer gets, with a warning, rather than
+ * taking OpenViking away for the turn.
+ */
 export function resolveOpenVikingActorPeerId(params: {
   peerRole: OpenVikingPeerRole;
   senderPeerId?: string;
   assistantPeerId?: string;
+  warn?: (message: string) => void;
 }): string | undefined {
   const actorPeerId = resolveOpenVikingMessagePeerId({
     ...params,
     role: params.peerRole === "sender" ? "user" : "assistant",
   });
   if (params.peerRole === "sender" && !actorPeerId) {
-    throw new Error("openviking: peer_role=sender requires a sender identity");
+    params.warn?.(
+      "openviking: peer_role=sender but OpenClaw supplied no sender identity; " +
+        "continuing as an unscoped request under this user (no X-OpenViking-Actor-Peer)",
+    );
   }
   return actorPeerId;
 }

package/services/context-lifecycle-service.ts

@@ -440,6 +440,7 @@ async function recallForAssemble(
     peerRole: cfg.peer_role ?? "none",
     senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
     assistantPeerId: agentId,
+    warn: (message) => logger.warn?.(message),
   });
   const queryConfig = await queryConfigStore?.getEffective({
     agentId,