Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(openclaw): stop offering the legacy person peer role at install time (#5355)

Zayn Jarvis9ecb2863a7df
diff --git a/docs/en/agent-integrations/03-openclaw.md b/docs/en/agent-integrations/03-openclaw.md
index fb8fc046e..af0045016 100644
--- a/docs/en/agent-integrations/03-openclaw.md
+++ b/docs/en/agent-integrations/03-openclaw.md
@@ -53,7 +53,7 @@ Key parameters:
| `--plugin-version=VER` | Plugin version: npm version, dist-tag, or Git ref |
| `--base-url URL` | OpenViking server URL |
| `--api-key KEY` | OpenViking API key |
-| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender` (`person` is a legacy alias) |
+| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender` |
| `--uninstall` | Uninstall the plugin |
Full parameter list in the [install guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md).
@@ -80,7 +80,7 @@ openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --
openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json
```
-New configuration should use `sender`; existing `peer_role=person` configurations remain compatible and are treated as `sender`. OpenViking initializes the managed `peers/` container for every user, so `none` 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 and the installer accept only `sender`; existing `peer_role=person` configurations remain compatible and are treated as `sender`. OpenViking initializes the managed `peers/` container for every user, so `none` 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.
## How assemble builds context
diff --git a/docs/images/agents/en/openclaw.md b/docs/images/agents/en/openclaw.md
index f90c900d5..b8f027191 100644
--- a/docs/images/agents/en/openclaw.md
+++ b/docs/images/agents/en/openclaw.md
@@ -12,7 +12,7 @@
openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <$OPENVIKING_API_KEY>
```
-3. Configure `peer_role`: `peer_role` identifies the type of conversation participant. It is not a permission role. `assistant` represents agents, tools, or models; `person` represents human participants. After the setup above, `peer_role` defaults to `none`. To change `peer_role`, run:
+3. Configure `peer_role`: `peer_role` identifies the type of conversation participant. It is not a permission role. `assistant` represents agents, tools, or models; `sender` represents human participants. After the setup above, `peer_role` defaults to `none`. To change `peer_role`, run:
```bash
openclaw openviking setup --reconfigure
diff --git a/docs/images/agents/zh/openclaw.md b/docs/images/agents/zh/openclaw.md
index 12c894100..904075ba8 100644
--- a/docs/images/agents/zh/openclaw.md
+++ b/docs/images/agents/zh/openclaw.md
@@ -12,7 +12,7 @@
openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <$OPENVIKING_API_KEY>
```
-3. 配置 `peer_role`:`peer_role` 用于标识对话参与者的类型,并非权限角色。其中,`assistant` 表示不同的 Agent、工具或模型,`person` 表示不同的人类参与者。完成上述配置后,`peer_role` 默认为 `none`。如需调整 `peer_role`,可执行以下命令:
+3. 配置 `peer_role`:`peer_role` 用于标识对话参与者的类型,并非权限角色。其中,`assistant` 表示不同的 Agent、工具或模型,`sender` 表示不同的人类参与者。完成上述配置后,`peer_role` 默认为 `none`。如需调整 `peer_role`,可执行以下命令:
```bash
openclaw openviking setup --reconfigure
diff --git a/docs/zh/agent-integrations/03-openclaw.md b/docs/zh/agent-integrations/03-openclaw.md
index 2ea59ed90..a79e30370 100644
--- a/docs/zh/agent-integrations/03-openclaw.md
+++ b/docs/zh/agent-integrations/03-openclaw.md
@@ -53,7 +53,7 @@ ov-install --base-url http://your-server:1933
| `--plugin-version=VER` | 插件版本:npm 版本、dist-tag 或 Git ref |
| `--base-url URL` | OpenViking 服务地址 |
| `--api-key KEY` | OpenViking API Key |
-| `--peer-role ROLE` | 记忆归属:`none`、`assistant` 或 `sender`(`person` 是旧别名) |
+| `--peer-role ROLE` | 记忆归属:`none`、`assistant` 或 `sender` |
| `--uninstall` | 卸载插件 |
完整参数列表见 [安装指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md)。
@@ -80,7 +80,7 @@ openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --
openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json
```
-新配置请使用 `sender`;已有的 `peer_role=person` 配置仍兼容,并按 `sender` 处理。OpenViking 会为每个用户初始化受管的 `peers/` 容器,因此 `none` 的含义是不使用具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆;切换 scope 不会搬迁已有记忆。
+安装和 setup 只接受 `sender`;已有的 `peer_role=person` 配置仍兼容,并按 `sender` 处理。OpenViking 会为每个用户初始化受管的 `peers/` 容器,因此 `none` 的含义是不使用具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆;切换 scope 不会搬迁已有记忆。
## assemble 如何组装上下文
diff --git a/examples/openclaw-plugin/INSTALL-AGENT.md b/examples/openclaw-plugin/INSTALL-AGENT.md
index 527078fd3..85b92cb8d 100644
--- a/examples/openclaw-plugin/INSTALL-AGENT.md
+++ b/examples/openclaw-plugin/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:
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md
index 995d179cb..cc81b575f 100644
--- a/examples/openclaw-plugin/INSTALL-ZH.md
+++ b/examples/openclaw-plugin/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 管理的安装 |
diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.md
index ac8893f6a..6007d3713 100644
--- a/examples/openclaw-plugin/INSTALL.md
+++ b/examples/openclaw-plugin/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 |
diff --git a/examples/openclaw-plugin/commands/setup.ts b/examples/openclaw-plugin/commands/setup.ts
index b732c5dde..2ce101f4b 100644
--- a/examples/openclaw-plugin/commands/setup.ts
+++ b/examples/openclaw-plugin/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)")
diff --git a/examples/openclaw-plugin/setup-helper/install.js b/examples/openclaw-plugin/setup-helper/install.js
index cca2c42c0..938a0770b 100755
--- a/examples/openclaw-plugin/setup-helper/install.js
+++ b/examples/openclaw-plugin/setup-helper/install.js
@@ -290,16 +290,16 @@ for (let i = 0; i < argv.length; i++) {
if (arg === "--peer-role") {
const val = argv[i + 1]?.trim();
if (!val) { console.error("--peer-role requires a value"); process.exit(1); }
- const role = normalizePeerRole(val);
- if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" (legacy alias: "person")'); process.exit(1); }
+ const role = normalizePeerRoleInput(val);
+ if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" ("person" was renamed to "sender")'); process.exit(1); }
remotePeerRole = role;
peerRoleExplicit = true;
i += 1;
continue;
}
if (arg.startsWith("--peer-role=")) {
- const role = normalizePeerRole(arg.slice("--peer-role=".length));
- if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" (legacy alias: "person")'); process.exit(1); }
+ const role = normalizePeerRoleInput(arg.slice("--peer-role=".length));
+ if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" ("person" was renamed to "sender")'); process.exit(1); }
remotePeerRole = role;
peerRoleExplicit = true;
continue;
@@ -343,6 +343,10 @@ for (let i = 0; i < argv.length; i++) {
}
}
+if (remotePeerRole === "person") {
+ console.error('OPENVIKING_PEER_ROLE must be "none", "assistant", or "sender" ("person" was renamed to "sender")');
+ process.exit(1);
+}
remotePeerRole = normalizePeerRole(remotePeerRole) || "none";
if (!isValidPeerPrefixInput(remotePeerPrefix)) {
console.error("--peer-prefix may only contain letters, digits, underscores, and hyphens");
@@ -373,7 +377,7 @@ function printHelp() {
console.log(" --uninstall, --remove Uninstall OpenViking plugin from OpenClaw (backup config, remove plugin entries)");
console.log(" --base-url=URL OpenViking server URL (default: $OPENVIKING_BASE_URL or http://127.0.0.1:1933)");
console.log(" --api-key=KEY OpenViking API key (default: $OPENVIKING_API_KEY)");
- console.log(" --peer-role=ROLE Memory scope: none (shared), assistant (per assistant), sender (per sender); person is a legacy alias (default: $OPENVIKING_PEER_ROLE or none)");
+ console.log(" --peer-role=ROLE Memory scope: none (shared), assistant (per assistant), sender (per sender) (default: $OPENVIKING_PEER_ROLE or none)");
console.log(" --peer-prefix=PREFIX Prefix for assistant peer_id values (default: $OPENVIKING_PEER_PREFIX)");
console.log(" --account-id=ID Account ID for root API key (default: $OPENVIKING_ACCOUNT_ID)");
console.log(" --user-id=ID User ID for root API key (default: $OPENVIKING_USER_ID)");
@@ -525,6 +529,12 @@ function normalizePeerRole(value) {
return role === "none" || role === "assistant" || role === "sender" ? role : null;
}
+// `person` survives only in existing configs; installer input must say `sender`.
+function normalizePeerRoleInput(value) {
+ const role = String(value || "").trim().toLowerCase();
+ return role === "person" ? null : normalizePeerRole(role);
+}
+
function parseJsonObjectFromOutput(output) {
const text = String(output || "").trim();
if (!text) return null;
@@ -550,21 +560,21 @@ async function questionPeerRole(defaultValue = "none") {
info(tr(
"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) {
const answer = await question(
tr("Memory scope (none/assistant/sender)", "记忆归属(none/assistant/sender)"),
defaultValue,
);
- const role = normalizePeerRole(answer);
+ const role = normalizePeerRoleInput(answer);
if (role) return role;
warn(tr(
- '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")。',
));
}
}
diff --git a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts b/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts
index abfad0c60..6d373d0bd 100644
--- a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts
+++ b/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts
@@ -148,6 +148,7 @@ describe("OpenClaw plugin package and install contract", () => {
expect(installHelper).toContain("OPENVIKING_PEER_ROLE");
expect(installHelper).toContain("OPENVIKING_PEER_PREFIX");
expect(installHelper).toContain('if (role === "person") return "sender"');
+ expect(installHelper).toContain('return role === "person" ? null : normalizePeerRole(role);');
expect(installHelper).not.toContain("OPENVIKING_AGENT_PREFIX");
});
});
diff --git a/examples/openclaw-plugin/tests/ut/setup-command.test.ts b/examples/openclaw-plugin/tests/ut/setup-command.test.ts
index 02dd80a08..85f9df426 100644
--- a/examples/openclaw-plugin/tests/ut/setup-command.test.ts
+++ b/examples/openclaw-plugin/tests/ut/setup-command.test.ts
@@ -35,10 +35,11 @@ describe("openviking setup agent prefix validation", () => {
},
);
- it("uses sender as the canonical setup value and accepts legacy person input", () => {
+ it("reads legacy person from existing config but rejects it as setup input", () => {
expect(setupCommandTest.normalizePeerRole("sender")).toBe("sender");
expect(setupCommandTest.normalizePeerRole("person")).toBe("sender");
- expect(setupCommandTest.resolveSetupPeerRole("person")).toBe("sender");
+ expect(setupCommandTest.resolveSetupPeerRole("sender")).toBe("sender");
+ expect(() => setupCommandTest.resolveSetupPeerRole("person")).toThrow('"person" was renamed to "sender"');
});
it("interactive reconfiguration preserves the selected retention policy", async () => {