Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(openclaw): treat agent_prefix as prefix only (#1809)
bot-of-qin-ctx9c08d716ca5c
diff --git a/examples/openclaw-plugin/INSTALL-AGENT.md b/examples/openclaw-plugin/INSTALL-AGENT.mdindex 7ccd777b0..2eb08d6df 100644--- a/examples/openclaw-plugin/INSTALL-AGENT.md+++ b/examples/openclaw-plugin/INSTALL-AGENT.md@@ -16,6 +16,7 @@ Choose the smallest action that matches the user's intent:| Upgrade only the plugin | `ov-install --update` || Show installed versions | `ov-install --current-version` || Operate on a specific OpenClaw instance | add `--workdir <path>` |+| Start missing OpenViking server | `openviking-server init && openviking-server doctor && openviking-server` |Default rule: when upgrading, refresh the setup helper first unless the user explicitly asks to pin the helper itself.@@ -46,13 +47,36 @@ Requirements:- Node.js >= 22- OpenClaw >= 2026.3.7+### 3. Detect or start OpenViking server++The OpenClaw plugin only connects to an OpenViking HTTP server. It does not start the server.++Check the default local server first:++```bash+curl -fsS http://127.0.0.1:1933/health+```++If no OpenViking server is running and the user wants a local server:++```bash+pip install openviking --upgrade --force-reinstall+openviking-server init+openviking-server doctor+openviking-server+```++Keep `openviking-server` running while OpenClaw uses the plugin. Use `http://127.0.0.1:1933` as the plugin `baseUrl` for the default local setup.++For a remote server, confirm the reachable URL with the user and use that URL as `baseUrl`.+If OpenClaw is missing, tell the user to run:```bashnpm install -g openclaw && openclaw onboard```-### 3. Detect existing install state+### 4. Detect existing install stateUse:@@ -193,7 +217,7 @@ Core OpenClaw plugin fields:- `baseUrl`- `apiKey`-- `agent_prefix`+- `agent_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`## Uninstalldiff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.mdindex 92c7328be..f42725e7a 100644--- a/examples/openclaw-plugin/INSTALL-ZH.md+++ b/examples/openclaw-plugin/INSTALL-ZH.md@@ -11,7 +11,7 @@| Node.js | >= 22 || OpenClaw | >= 2026.3.7 |-插件以远程模式连接到已有的 OpenViking 服务。安装前请确保已有可访问的 OpenViking HTTP 服务。+插件以远程模式连接到已有的 OpenViking 服务。它不会帮你启动 OpenViking server。需要先启动 OpenViking,并保持服务运行,再把插件的 `baseUrl` 指向这个 HTTP 服务。默认本地地址是 `http://127.0.0.1:1933`。快速检查:@@ -20,6 +20,40 @@ node -vopenclaw --version```+## 启动 OpenViking Server++如果 OpenViking 和 OpenClaw 在同一台机器上,最短流程是:++```bash+pip install openviking --upgrade --force-reinstall+openviking-server init+openviking-server doctor+openviking-server+```++`openviking-server init` 用来生成服务端配置,`openviking-server doctor` 用来检查本地模型和 provider 鉴权是否可用,`openviking-server` 才是真正启动 HTTP API 的命令。OpenClaw 使用插件期间,这个服务进程需要一直运行。++后台启动可以用:++```bash+mkdir -p ~/.openviking/data/log+nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &+```++如果 OpenViking 跑在另一台机器上,需要监听可访问的地址和端口,例如:++```bash+openviking-server --host 0.0.0.0 --port 1933+```++然后把 OpenClaw 插件的 `baseUrl` 配成对应地址,例如 `http://your-server:1933`。++安装或重启插件前,先确认服务能访问:++```bash+curl http://127.0.0.1:1933/health+```+## 旧版升级说明如果你之前安装过旧版 `memory-openviking`,先清理旧插件,再执行下面的安装或升级命令。@@ -106,7 +140,7 @@ openclaw config get plugins.entries.openviking.config| --- | --- | --- || `baseUrl` | `http://127.0.0.1:1933` | 远端 OpenViking 服务地址 || `apiKey` | 空 | 远端 OpenViking API Key;服务端未开启认证时可不填 |-| `agent_prefix` | `default` | 当前 OpenClaw 实例在远端 OpenViking 上的 agent 前缀 |+| `agent_prefix` | 空 | OpenClaw agent ID 的可选前缀;如果拿不到 agent ID,插件使用 `main`。交互式配置只接受字母、数字、`_` 和 `-` |常见设置:diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.mdindex 26160d638..602f6493e 100644--- a/examples/openclaw-plugin/INSTALL.md+++ b/examples/openclaw-plugin/INSTALL.md@@ -11,7 +11,7 @@ Use [OpenViking](https://github.com/volcengine/OpenViking) as the long-term memo| Node.js | >= 22 || OpenClaw | >= 2026.3.7 |-The plugin connects to an existing OpenViking server. Make sure you have a running OpenViking service accessible via HTTP before proceeding.+The plugin connects to an existing OpenViking server. It does not start the OpenViking server for you. Start OpenViking first, keep it running, then point the plugin `baseUrl` at that HTTP service. The default local URL is `http://127.0.0.1:1933`.Quick check:@@ -20,6 +20,40 @@ node -vopenclaw --version```+## Start OpenViking Server++For a local OpenViking server on the same machine as OpenClaw:++```bash+pip install openviking --upgrade --force-reinstall+openviking-server init+openviking-server doctor+openviking-server+```++`openviking-server init` writes the server configuration, `openviking-server doctor` validates local model/provider auth, and `openviking-server` starts the HTTP API. Keep this process running while OpenClaw uses the plugin.++To run the server in the background:++```bash+mkdir -p ~/.openviking/data/log+nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &+```++If OpenViking runs on another machine, start it on a reachable host/port, for example:++```bash+openviking-server --host 0.0.0.0 --port 1933+```++Then configure the OpenClaw plugin `baseUrl` to that address, such as `http://your-server:1933`.++Verify the server before installing or restarting the plugin:++```bash+curl http://127.0.0.1:1933/health+```+## Legacy Upgrade NoteIf you previously installed the legacy `memory-openviking` plugin, remove it first, then continue with the install or upgrade commands below.@@ -113,7 +147,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 |-| `agent_prefix` | `default` | Agent prefix used by this OpenClaw instance on the remote server |+| `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-` |Common settings:diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.mdindex 1098476fb..eaa2aee17 100644--- a/examples/openclaw-plugin/README.md+++ b/examples/openclaw-plugin/README.md@@ -46,8 +46,10 @@ The main rules are:- prefer `sessionKey` when deriving a stable `ovSessionId`- normalize unsafe path characters, or fall back to a stable SHA-256 when needed- resolve `X-OpenViking-Agent` per session, not per process-- when `plugins.entries.openviking.config.agent_prefix` is not `default`, prefix the session agent as `<agent_prefix>_<sessionAgent>`-- add `X-OpenViking-Agent` in the client layer, and only add `X-OpenViking-Account` / `X-OpenViking-User` when `accountId` / `userId` are explicitly configured+- when `plugins.entries.openviking.config.agent_prefix` is non-empty, prefix the session agent as `<agent_prefix>_<sessionAgent>`+- when OpenClaw does not provide a session agent, use its default agent `main`+- send `X-OpenViking-Agent` on OpenViking requests, including startup health checks+- only add `X-OpenViking-Account` / `X-OpenViking-User` when `accountId` / `userId` are explicitly configuredThis matters because the plugin is built to support multi-agent and multi-session OpenClaw usage without mixing memories across sessions.diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.mdindex 3f040d619..b69214d19 100644--- a/examples/openclaw-plugin/README_CN.md+++ b/examples/openclaw-plugin/README_CN.md@@ -46,8 +46,10 @@- `sessionKey` 存在时优先用它生成稳定的 `ovSessionId`。- 非安全路径字符会被规整或退化成稳定的 SHA-256。- `X-OpenViking-Agent` 按 session 解析,不按进程写死。-- 若 `plugins.entries.openviking.config.agent_prefix` 不是 `default`,会形成 `<agent_prefix>_<sessionAgent>` 的前缀形式。-- client 层会发送 `X-OpenViking-Agent`;只有显式配置了 `accountId` / `userId` 时才发送 `X-OpenViking-Account` / `X-OpenViking-User`。+- 若 `plugins.entries.openviking.config.agent_prefix` 非空,会形成 `<agent_prefix>_<sessionAgent>` 的前缀形式。+- OpenClaw 没有提供 session agent 时,使用其默认 agent `main`。+- OpenViking 请求都会发送 `X-OpenViking-Agent`,包括启动阶段的 health check。+- 只有显式配置了 `accountId` / `userId` 时才发送 `X-OpenViking-Account` / `X-OpenViking-User`。这样做是为了支持多 agent、多 session 并发时的记忆隔离,避免不同 OpenClaw 会话串用同一套长期上下文。@@ -260,3 +262,4 @@ ov tui---安装、升级、卸载请查看 [INSTALL-ZH.md](./INSTALL-ZH.md)。+diff --git a/examples/openclaw-plugin/client.ts b/examples/openclaw-plugin/client.tsindex e47ea6fec..307bb5f57 100644--- a/examples/openclaw-plugin/client.ts+++ b/examples/openclaw-plugin/client.ts@@ -216,6 +216,15 @@ export class OpenVikingClient {return this.defaultAgentId;}+ private resolveEffectiveAgentId(agentId?: string): string {+ const explicit = agentId?.trim();+ if (explicit) {+ return explicit;+ }+ const prefix = this.defaultAgentId.trim();+ return prefix ? `${prefix}_main` : "main";+ }+async getResolvedIdentity(agentId?: string): Promise<RuntimeIdentity> {return this.getRuntimeIdentity(agentId);}@@ -241,7 +250,7 @@ export class OpenVikingClient {if (!this.routingDebugLog) {return;}- const effectiveAgentId = agentId ?? this.defaultAgentId;+ const effectiveAgentId = this.resolveEffectiveAgentId(agentId);const identity = await this.getRuntimeIdentity(agentId);const tenantHeaders = this.resolveTenantHeaders();this.routingDebugLog(@@ -265,7 +274,7 @@ export class OpenVikingClient {agentId?: string,requestTimeoutMs?: number,): Promise<T> {- const effectiveAgentId = agentId ?? this.defaultAgentId;+ const effectiveAgentId = this.resolveEffectiveAgentId(agentId);const controller = new AbortController();const timer = setTimeout(() => controller.abort(), requestTimeoutMs ?? this.timeoutMs);try {@@ -316,17 +325,17 @@ export class OpenVikingClient {}private async getRuntimeIdentity(agentId?: string): Promise<RuntimeIdentity> {- const effectiveAgentId = agentId ?? this.defaultAgentId;+ const effectiveAgentId = this.resolveEffectiveAgentId(agentId);const cached = this.identityCache.get(effectiveAgentId);if (cached) {return cached;}- const fallback: RuntimeIdentity = { userId: "default", agentId: effectiveAgentId || "default" };+ const fallback: RuntimeIdentity = { userId: "default", agentId: effectiveAgentId };try {const status = await this.request<{ user?: unknown }>("/api/v1/system/status", {}, agentId);const userId =typeof status.user === "string" && status.user.trim() ? status.user.trim() : "default";- const identity: RuntimeIdentity = { userId, agentId: effectiveAgentId || "default" };+ const identity: RuntimeIdentity = { userId, agentId: effectiveAgentId };this.identityCache.set(effectiveAgentId, identity);return identity;} catch {@@ -390,7 +399,7 @@ export class OpenVikingClient {limit: options.limit,score_threshold: options.scoreThreshold,};- const effectiveAgentId = agentId ?? this.defaultAgentId;+ const effectiveAgentId = this.resolveEffectiveAgentId(agentId);const identity = await this.getRuntimeIdentity(agentId);const tenantHeaders = this.resolveTenantHeaders();this.routingDebugLog?.(diff --git a/examples/openclaw-plugin/commands/setup.ts b/examples/openclaw-plugin/commands/setup.tsindex 10416eeea..4c77fe700 100644--- a/examples/openclaw-plugin/commands/setup.ts+++ b/examples/openclaw-plugin/commands/setup.ts@@ -30,6 +30,34 @@ function maskKey(key: string): string {return `${key.slice(0, 4)}...${key.slice(-4)}`;}+function isValidAgentPrefixInput(value: string): boolean {+ const trimmed = value.trim();+ return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);+}++async function askAgentPrefix(+ zh: boolean,+ q: (prompt: string, def?: string) => Promise<string>,+ defaultValue: string,+): Promise<string> {+ while (true) {+ const value = (await q(+ tr(zh, "Agent Prefix (optional)", "Agent Prefix(可选)"),+ defaultValue,+ )).trim();+ if (isValidAgentPrefixInput(value)) {+ return value;+ }+ console.log(+ ` ✗ ${tr(+ zh,+ "Agent Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",+ "Agent Prefix 只能包含字母、数字、下划线和连字符,或留空。",+ )}`,+ );+ }+}+function ask(rl: readline.Interface, prompt: string, defaultValue = ""): Promise<string> {const suffix = defaultValue ? ` [${defaultValue}]` : "";return new Promise((resolve) => {@@ -288,7 +316,7 @@ async function setupRemote(const baseUrl = await q(tr(zh, "OpenViking server URL", "OpenViking 服务器地址"), defaultUrl);const apiKey = await q(tr(zh, "API Key (optional)", "API Key(可选)"), defaultApiKey);- const agentPrefix = await q(tr(zh, "Agent Prefix (optional)", "Agent Prefix(可选)"), defaultAgentPrefix);+ const agentPrefix = await askAgentPrefix(zh, q, defaultAgentPrefix);console.log("");@@ -339,4 +367,5 @@ async function setupRemote(export const __test__ = {resolveAbsoluteCommand,isLegacyLocalMode,+ isValidAgentPrefixInput,};diff --git a/examples/openclaw-plugin/config.ts b/examples/openclaw-plugin/config.tsindex 379404e3f..ef7d881c5 100644--- a/examples/openclaw-plugin/config.ts+++ b/examples/openclaw-plugin/config.ts@@ -61,11 +61,12 @@ const DEFAULT_RECALL_MAX_INJECTED_CHARS = 4000;const DEFAULT_COMMIT_TOKEN_THRESHOLD = 20000;const DEFAULT_BYPASS_SESSION_PATTERNS: string[] = [];const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;-const DEFAULT_AGENT_PREFIX = "default";+const DEFAULT_AGENT_PREFIX = "";function resolveAgentPrefix(configured: unknown): string {if (typeof configured === "string" && configured.trim()) {- return configured.trim();+ const trimmed = configured.trim();+ return trimmed === "default" ? DEFAULT_AGENT_PREFIX : trimmed;}return DEFAULT_AGENT_PREFIX;}@@ -313,8 +314,8 @@ export const memoryOpenVikingConfigSchema = {},agent_prefix: {label: "Agent Prefix",- placeholder: "auto-generated",- help: 'OpenViking X-OpenViking-Agent prefix. "default" follows OpenClaw ctx.agentId. Non-default values are prepended as "<prefix>_<ctx.agentId>" (sanitized to [a-zA-Z0-9_-]).',+ placeholder: "optional-prefix",+ help: 'Optional prefix for OpenViking X-OpenViking-Agent. Empty means use OpenClaw ctx.agentId directly. Non-empty values are prepended as "<prefix>_<ctx.agentId>" (sanitized to [a-zA-Z0-9_-]). If ctx.agentId is unavailable, OpenClaw default agent "main" is used.',},apiKey: {label: "OpenViking API Key",diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.tsindex 687977115..f56f7aedf 100644--- a/examples/openclaw-plugin/index.ts+++ b/examples/openclaw-plugin/index.ts@@ -157,6 +157,7 @@ type OpenClawPluginApi = {const AUTO_RECALL_TIMEOUT_MS = 5_000;const RECALL_QUERY_MAX_CHARS = 4_000;+const DEFAULT_OPENCLAW_AGENT_ID = "main";/*** OpenViking `UserIdentifier` allows only [a-zA-Z0-9_-] for agent_id@@ -439,6 +440,7 @@ function collectSessionAgentAliases(}export function createSessionAgentResolver(configAgentId: string) {+ const configAgentPrefix = configAgentId.trim() === "default" ? "" : configAgentId.trim();const sessionAgentIds = new Map<string, string>();const remember = (ctx: SessionAgentLookup): void => {@@ -453,10 +455,8 @@ export function createSessionAgentResolver(configAgentId: string) {return;}- const resolvedBeforeSanitize =- !configAgentId || configAgentId === "default"- ? rawAgentId- : `${configAgentId}_${rawAgentId}`;+ const prefix = configAgentPrefix;+ const resolvedBeforeSanitize = prefix ? `${prefix}_${rawAgentId}` : rawAgentId;const resolved = sanitizeOpenVikingAgentIdHeader(resolvedBeforeSanitize);for (const alias of collectSessionAgentAliases(ctx.sessionId, ctx.sessionKey, ctx.ovSessionId)) {sessionAgentIds.set(alias, resolved);@@ -478,31 +478,26 @@ export function createSessionAgentResolver(configAgentId: string) {let resolvedBeforeSanitize: string;let resolved: string;let branch: SessionAgentResolveBranch;+ const prefix = configAgentPrefix;if (mappedResolvedAgentId) {resolvedBeforeSanitize = mappedResolvedAgentId;resolved = mappedResolvedAgentId;branch = "session_resolved";} else if (sessionScopedAgentId) {- resolvedBeforeSanitize =- !configAgentId || configAgentId === "default"- ? sessionScopedAgentId- : `${configAgentId}_${sessionScopedAgentId}`;+ resolvedBeforeSanitize = prefix ? `${prefix}_${sessionScopedAgentId}` : sessionScopedAgentId;resolved = sanitizeOpenVikingAgentIdHeader(resolvedBeforeSanitize);branch = "session_resolved";- } else if (!configAgentId || configAgentId === "default") {- resolvedBeforeSanitize = "default";- resolved = "default";+ } else if (!prefix) {+ resolvedBeforeSanitize = DEFAULT_OPENCLAW_AGENT_ID;+ resolved = DEFAULT_OPENCLAW_AGENT_ID;branch = "default_no_session";} else {- resolvedBeforeSanitize = configAgentId;- resolved = sanitizeOpenVikingAgentIdHeader(configAgentId);+ resolvedBeforeSanitize = `${prefix}_${DEFAULT_OPENCLAW_AGENT_ID}`;+ resolved = sanitizeOpenVikingAgentIdHeader(resolvedBeforeSanitize);branch = "config_only_fallback";}- // Only explicit agent observations are persisted via remember().- // Fallback values must stay ephemeral so a later real ctx.agentId- // can safely take over without inheriting a stale default binding.return {resolved,resolvedBeforeSanitize,@@ -554,9 +549,9 @@ const contextEnginePlugin = {`openviking: loaded plugin config agent_prefix="${cfg.agent_prefix}" ` +`(raw plugins.entries.openviking.config.agent_prefix=${JSON.stringify(rawAgentId ?? "(missing)")}; ` +`${- cfg.agent_prefix !== "default"- ? "non-default → X-OpenViking-Agent is <configAgentId>_<ctx.agentId> (sanitized to [a-zA-Z0-9_-]) when hooks expose session agent; config-only if ctx.agentId unknown"- : 'default → X-OpenViking-Agent follows OpenClaw ctx.agentId per session (e.g. "main")'+ cfg.agent_prefix+ ? 'non-empty → X-OpenViking-Agent is <agent_prefix>_<ctx.agentId> when hooks expose session agent, or <agent_prefix>_main when ctx.agentId is unknown'+ : 'empty → X-OpenViking-Agent follows OpenClaw ctx.agentId per session, or "main" when ctx.agentId is unknown'})`,);verboseRoutingInfo(diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.jsonindex fc9486787..82314f29b 100644--- a/examples/openclaw-plugin/openclaw.plugin.json+++ b/examples/openclaw-plugin/openclaw.plugin.json@@ -11,8 +11,8 @@},"agent_prefix": {"label": "Agent Prefix",- "placeholder": "auto-generated",- "help": "OpenViking agent prefix. default: follow OpenClaw ctx.agentId. Non-default: use `<prefix>_<OpenClaw ctx.agentId>` (sanitized to letters/digits/_/-), so the configured value acts as a prefix."+ "placeholder": "optional-prefix",+ "help": "Optional OpenViking agent prefix. Empty: follow OpenClaw ctx.agentId directly. Non-empty: use `<prefix>_<OpenClaw ctx.agentId>` (sanitized to letters/digits/_/-). If OpenClaw ctx.agentId is unavailable, use OpenClaw default agent `main`."},"apiKey": {"label": "OpenViking API Key",diff --git a/examples/openclaw-plugin/setup-helper/install.js b/examples/openclaw-plugin/setup-helper/install.jsindex 0a6152774..1b6183767 100755--- a/examples/openclaw-plugin/setup-helper/install.js+++ b/examples/openclaw-plugin/setup-helper/install.js@@ -326,6 +326,27 @@ function question(prompt, defaultValue = "") {});}+function isValidAgentPrefixInput(value) {+ const trimmed = String(value || "").trim();+ return !trimmed || /^[a-zA-Z0-9_-]+$/.test(trimmed);+}++async function questionAgentPrefix(defaultValue = "") {+ while (true) {+ const answer = (await question(+ tr("Agent Prefix (optional)", "Agent Prefix(可选)"),+ defaultValue,+ )).trim();+ if (isValidAgentPrefixInput(answer)) {+ return answer;+ }+ warn(tr(+ "Agent Prefix may only contain letters, digits, underscores, and hyphens, or be empty.",+ "Agent Prefix 只能包含字母、数字、下划线和连字符,或留空。",+ ));+ }+}+function detectOpenClawInstances() {const instances = [];try {@@ -372,7 +393,7 @@ async function collectRemoteConfig() {if (installYes) return;remoteBaseUrl = await question(tr("OpenViking server URL", "OpenViking 服务器地址"), remoteBaseUrl);remoteApiKey = await question(tr("API Key (optional)", "API Key(可选)"), remoteApiKey);- remoteAgentPrefix = await question(tr("Agent Prefix (optional)", "Agent Prefix(可选)"), remoteAgentPrefix);+ remoteAgentPrefix = await questionAgentPrefix(remoteAgentPrefix);}async function checkOpenClaw() {diff --git a/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md b/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.mdindex 782928b36..fc18b0c44 100644--- a/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md+++ b/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md@@ -55,11 +55,25 @@ Example: User says "Forget my phone number"## Configuration+The plugin connects to an OpenViking HTTP server. Start OpenViking first and keep it running:++```bash+openviking-server init+openviking-server doctor+openviking-server+```++The default local plugin URL is `http://127.0.0.1:1933`. Check it with:++```bash+curl http://127.0.0.1:1933/health+```+| Field | Default | Description ||-------|---------|-------------|| `baseUrl` | `http://127.0.0.1:1933` | OpenViking server URL || `apiKey` | — | OpenViking API Key (optional) |-| `agent_prefix` | `default` | Agent prefix identifying this instance to OpenViking |+| `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. Interactive setup accepts only letters, digits, `_`, and `-`. If no agent ID is available, the plugin uses `main` || `targetUri` | `viking://user/memories` | Default search scope || `autoCapture` | `true` | Automatically capture memories || `captureMode` | `semantic` | Capture mode: `semantic` / `keyword` |@@ -71,7 +85,10 @@ Example: User says "Forget my phone number"## Daily Operations```bash-# Start+# Start OpenViking server+openviking-server++# Start or restart OpenClaw gatewayopenclaw gateway# Check statusdiff --git a/examples/openclaw-plugin/tests/ut/client.test.ts b/examples/openclaw-plugin/tests/ut/client.test.tsindex def206e17..b4ab0acb5 100644--- a/examples/openclaw-plugin/tests/ut/client.test.ts+++ b/examples/openclaw-plugin/tests/ut/client.test.ts@@ -334,6 +334,21 @@ describe("OpenVikingClient resource and skill import", () => {});describe("OpenVikingClient tenant headers (advanced accountId / userId overrides)", () => {+ it.each([+ ["prefix", "prefix_main"],+ ["", "main"],+ ])("sends OpenClaw default agent for health checks with prefix %j", async (prefix, expected) => {+ const fetchMock = vi.fn().mockResolvedValue(okResponse({ status: "ok" }));+ vi.stubGlobal("fetch", fetchMock);++ const client = new OpenVikingClient("http://127.0.0.1:1933", "sk-test", prefix, 5000);+ await client.healthCheck();++ const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];+ const headers = new Headers(init.headers);+ expect(headers.get("X-OpenViking-Agent")).toBe(expected);+ });+it("sends explicitly configured accountId and userId in request headers", async () => {const fetchMock = vi.fn().mockResolvedValue(okResponse({ status: "ok" }));vi.stubGlobal("fetch", fetchMock);@@ -436,7 +451,7 @@ describe("OpenVikingClient canonical namespace policy", () => {false,true,);- await client.find("test query", { targetUri: "viking://user/memories" });+ await client.find("test query", { targetUri: "viking://user/memories" }, "my-agent");const findCall = fetchMock.mock.calls.find((c) =>String(c[0]).endsWith("/api/v1/search/find"),@@ -463,7 +478,7 @@ describe("OpenVikingClient canonical namespace policy", () => {true,true,);- await client.find("test query", { targetUri: "viking://user/memories" });+ await client.find("test query", { targetUri: "viking://user/memories" }, "my-agent");const findCall = fetchMock.mock.calls.find((c) =>String(c[0]).endsWith("/api/v1/search/find"),@@ -490,7 +505,7 @@ describe("OpenVikingClient canonical namespace policy", () => {false,true,);- await client.find("test", { targetUri: "viking://agent/memories" });+ await client.find("test", { targetUri: "viking://agent/memories" }, "shared-agent");const findCall = fetchMock.mock.calls.find((c) =>String(c[0]).endsWith("/api/v1/search/find"),@@ -517,7 +532,7 @@ describe("OpenVikingClient canonical namespace policy", () => {false,false,);- await client.find("test", { targetUri: "viking://agent/skills" });+ await client.find("test", { targetUri: "viking://agent/skills" }, "shared-agent");const findCall = fetchMock.mock.calls.find((c) =>String(c[0]).endsWith("/api/v1/search/find"),diff --git a/examples/openclaw-plugin/tests/ut/config.test.ts b/examples/openclaw-plugin/tests/ut/config.test.tsindex 18c86cae7..43eecc76b 100644--- a/examples/openclaw-plugin/tests/ut/config.test.ts+++ b/examples/openclaw-plugin/tests/ut/config.test.ts@@ -23,7 +23,7 @@ describe("memoryOpenVikingConfigSchema.parse()", () => {expect(cfg.captureMode).toBe("semantic");expect(cfg.captureMaxLength).toBe(24000);expect(cfg.recallMaxContentChars).toBe(5000);- expect(cfg.agent_prefix).toBe("default");+ expect(cfg.agent_prefix).toBe("");expect(cfg.isolateUserScopeByAgent).toBe(false);expect(cfg.isolateAgentScopeByUser).toBe(false);expect(cfg.emitStandardDiagnostics).toBe(false);@@ -164,9 +164,14 @@ describe("memoryOpenVikingConfigSchema.parse()", () => {expect(cfg.agent_prefix).toBe("my-agent");});- it("falls back to 'default' for empty agent_prefix", () => {+ it("falls back to an empty prefix for empty agent_prefix", () => {const cfg = memoryOpenVikingConfigSchema.parse({ agent_prefix: " " });- expect(cfg.agent_prefix).toBe("default");+ expect(cfg.agent_prefix).toBe("");+ });++ it("normalizes legacy 'default' agent_prefix to an empty prefix", () => {+ const cfg = memoryOpenVikingConfigSchema.parse({ agent_prefix: "default" });+ expect(cfg.agent_prefix).toBe("");});it("migrates legacy agentId to agent_prefix", () => {diff --git a/examples/openclaw-plugin/tests/ut/index-utils.test.ts b/examples/openclaw-plugin/tests/ut/index-utils.test.tsindex c8b91844b..fde800dbf 100644--- a/examples/openclaw-plugin/tests/ut/index-utils.test.ts+++ b/examples/openclaw-plugin/tests/ut/index-utils.test.ts@@ -45,17 +45,17 @@ describe("sanitizeOpenVikingAgentIdHeader", () => {});describe("createSessionAgentResolver", () => {- it("resolves to 'default' when no session info and configAgentId is 'default'", () => {+ it("falls back to OpenClaw default agent when no session agent is available", () => {const resolver = createSessionAgentResolver("default");const result = resolver.resolve();- expect(result.resolved).toBe("default");+ expect(result.resolved).toBe("main");expect(result.branch).toBe("default_no_session");});- it("resolves to configAgentId when no session info", () => {+ it("combines prefix with OpenClaw default agent when no session agent is available", () => {const resolver = createSessionAgentResolver("custom-agent");const result = resolver.resolve();- expect(result.resolved).toBe("custom-agent");+ expect(result.resolved).toBe("custom-agent_main");expect(result.branch).toBe("config_only_fallback");});diff --git a/examples/openclaw-plugin/tests/ut/setup-command.test.ts b/examples/openclaw-plugin/tests/ut/setup-command.test.tsnew file mode 100644index 000000000..6a633f791--- /dev/null+++ b/examples/openclaw-plugin/tests/ut/setup-command.test.ts@@ -0,0 +1,19 @@+import { describe, expect, it } from "vitest";++import { __test__ } from "../../commands/setup.js";++describe("openviking setup agent prefix validation", () => {+ it.each(["", " ", "main", "foo_main", "foo-main", "Foo_123"])(+ "accepts valid agent prefix %j",+ (value) => {+ expect(__test__.isValidAgentPrefixInput(value)).toBe(true);+ },+ );++ it.each(["foo.bar", "foo/bar", "foo bar", "中文", "foo:bar"])(+ "rejects invalid agent prefix %j",+ (value) => {+ expect(__test__.isValidAgentPrefixInput(value)).toBe(false);+ },+ );+});