Skip to content

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

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.md
index 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:
```bash
npm install -g openclaw && openclaw onboard
```
-### 3. Detect existing install state
+### 4. Detect existing install state
Use:
@@ -193,7 +217,7 @@ Core OpenClaw plugin fields:
- `baseUrl`
- `apiKey`
-- `agent_prefix`
+- `agent_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`
## Uninstall
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md
index 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 -v
openclaw --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.md
index 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 -v
openclaw --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 Note
If 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.md
index 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 configured
This 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.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.js
index 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.md
index 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 gateway
openclaw gateway
# Check status
diff --git a/examples/openclaw-plugin/tests/ut/client.test.ts b/examples/openclaw-plugin/tests/ut/client.test.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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);
+ },
+ );
+});