@openviking/openclaw-plugin 2026.7.11 → 2026.8.6

package/INSTALL-ZH.md

@@ -203,6 +203,45 @@ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --forc
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
+#### 无法执行 CLI 时直接配置文件
+
+如果容器内无法执行 `openclaw` CLI，可以把以下字段合并到 OpenClaw 实际读取的配置文件。设置了 `OPENCLAW_CONFIG_PATH` 时使用该路径；否则通常是 `$OPENCLAW_STATE_DIR/openclaw.json`（默认 `~/.openclaw/openclaw.json`）。
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openviking": {
+        "enabled": true,
+        "config": {
+          "mode": "remote",
+          "baseUrl": "http://openviking:1933",
+          "apiKey": "<API_KEY>",
+          "peer_role": "assistant"
+        }
+      }
+    },
+    "slots": {
+      "contextEngine": "openviking"
+    }
+  }
+}
+```
+
+- 插件必须已经安装；编辑前请备份配置，并把以上字段合并到现有 `plugins` 配置。
+- 如果配置中已有 `plugins.allow`，把 `openviking` 追加进去；如果没有，不要仅为本插件新建 allowlist。
+- `contextEngine` 是独占 slot；若已有其他 context engine，只有确认替换后再修改该字段。使用 root API key 时，还需在 `config` 中设置 `accountId` 和 `userId`。
+- 容器连接其他服务时，`baseUrl` 应使用容器内可访问的服务地址，而不是 `127.0.0.1`。
+- 推荐使用 `SecretRef` 对象作为 `apiKey`（而不是明文字符串），避免密钥直接落盘写入 `openclaw.json`。支持的形式与 OpenClaw 核心中 LLM/TTS/MCP 等 provider 配置使用的标准 `SecretRef` 一致：
+
+  | 类型 | 示例 | 说明 |
+  | --- | --- | --- |
+  | `env` | `{ "source": "env", "id": "OPENVIKING_API_KEY" }` | 启动时读取同名环境变量。 |
+  | `file` | `{ "source": "file", "id": "/etc/secrets/openviking.key" }` | 以 UTF-8 读取并去除首尾空白；`~` 可展开，适配 Kubernetes `secretKeyRef` 卷挂载、0600 权限文件。 |
+  | `exec` | `{ "source": "exec", "provider": "op", "id": "op://vault/openviking/credential" }` | 运行 `<provider> <id>`，去除 stdout 首尾空白（1Password `op`、Vault、gopass 等均符合此形态）。 |
+
+  仍可使用纯字符串形式（含 `${ENV_VAR}` 插值）作为向后兼容路径；此时请限制文件权限或通过受控 Secret 卷提供，并在修改后重启 Gateway、容器或 Pod。
+
 ### 3. 重启 OpenClaw Gateway
 
 ```bash

package/INSTALL.md

@@ -147,6 +147,45 @@ If you want assistant messages to carry a prefixed `peer_id` and data-plane reca
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
+#### 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`).
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openviking": {
+        "enabled": true,
+        "config": {
+          "mode": "remote",
+          "baseUrl": "http://openviking:1933",
+          "apiKey": "<API_KEY>",
+          "peer_role": "assistant"
+        }
+      }
+    },
+    "slots": {
+      "contextEngine": "openviking"
+    }
+  }
+}
+```
+
+- The plugin must already be installed. Back up the file and merge these fields into the existing `plugins` config.
+- If `plugins.allow` already exists, append `openviking`; otherwise, do not create an allowlist only for this plugin.
+- `contextEngine` is an exclusive slot. If another context engine is configured, change it only after confirming the replacement. Root API keys also require `accountId` and `userId` in `config`.
+- When connecting to another service from a container, use a `baseUrl` that is reachable from the container rather than `127.0.0.1`.
+- Prefer a `SecretRef` for `apiKey` instead of a plaintext string so the key is never stored inside `openclaw.json`. Supported shapes match OpenClaw's standard `SecretRef` used by LLM/TTS/MCP provider configs:
+
+  | Shape | Example | Notes |
+  | --- | --- | --- |
+  | `env` | `{ "source": "env", "id": "OPENVIKING_API_KEY" }` | Reads the named env var at plugin load time. |
+  | `file` | `{ "source": "file", "id": "/etc/secrets/openviking.key" }` | Reads UTF-8, trims whitespace. `~` is expanded; ideal for Kubernetes `secretKeyRef` volumes and 0600-managed files. |
+  | `exec` | `{ "source": "exec", "provider": "op", "id": "op://vault/openviking/credential" }` | Runs `<provider> <id>` and trims stdout (1Password `op`, Vault, gopass, etc. all match this shape). |
+
+  A plain `string` (including `${ENV_VAR}` interpolation) is still accepted, but only as a backward-compatibility path; in that case, restrict file permissions or provide the file through a managed Secret volume, then restart the Gateway, container, or Pod.
+
 ### 3. Restart OpenClaw Gateway
 
 ```bash

package/README.md

@@ -46,6 +46,8 @@ Once installed, the plugin provides these agent tools:
 | `ov_read` | Read the full original content of one exact OpenViking URI |
 | `ov_multi_read` | Read the full original content of multiple OpenViking URIs |
 | `ov_list` | List OpenViking directories after search to inspect sibling chunks and overview files |
+| `search_experience` | Search reusable execution experiences for the current OpenViking user |
+| `read_experience` | Read one exact Experience returned by `search_experience` |
 | `openviking_tool_result_read` | Restore the full original content of an externalized tool result |
 | `openviking_tool_result_search` | Search inside an externalized tool result by keyword |
 | `openviking_tool_result_list` | List externalized tool results in the current session |
@@ -248,6 +250,8 @@ Beyond automatic behavior, the plugin exposes these tools directly:
 - `ov_read`: read one exact `viking://` URI returned by `ov_search` or `ov_list`
 - `ov_multi_read`: read multiple exact `viking://` URIs, useful for an overview plus sibling chunks
 - `ov_list`: list a hit's parent directory after `ov_search` to recover sibling chunks, `.overview.md`, and related split-document context
+- `search_experience`: search reusable execution experiences for the current OpenViking user
+- `read_experience`: read one exact Experience returned by `search_experience`
 
 They serve different roles:
 
@@ -261,6 +265,7 @@ They serve different roles:
 - `ov_read` turns a ranked hit into original evidence before answering precise documentation, codebase, configuration, or procedural questions
 - `ov_multi_read` reads overview and sibling chunks together when a split document needs more context than a single hit
 - `ov_list` complements `ov_search` when a ranked hit is only one chunk of a larger procedure or document
+- `search_experience` and `read_experience` provide the exact tool-call contract used by the bundled Experience Memory skill and usage reporting
 
 `ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
 

package/auto-recall.ts

@@ -313,6 +313,7 @@ export async function buildAutoRecallContext(params: {
   queryConfig?: EffectiveQueryConfig;
   client: OpenVikingClient;
   agentId: string;
+  actorPeerId?: string;
   queryText: string;
   logger: Logger;
   verbose?: (message: string) => void;
@@ -324,14 +325,14 @@ export async function buildAutoRecallContext(params: {
   queryTruncated?: boolean;
   resourceTypes?: RecallResourceType[];
 }): Promise<{ block?: string; memoryCount: number; estimatedTokens: number }> {
-  const { cfg, client, agentId, queryText, logger, verbose } = params;
+  const { cfg, client, agentId, actorPeerId, queryText, logger, verbose } = params;
   const queryConfig = params.queryConfig;
 
   if (!cfg.autoRecall || queryText.length < 5) {
     return { memoryCount: 0, estimatedTokens: 0 };
   }
 
-  const precheck = await quickRecallPrecheck(client, agentId);
+  const precheck = await quickRecallPrecheck(client, actorPeerId);
   if (!precheck.ok) {
     verbose?.(`openviking: skipping auto-recall because precheck failed (${precheck.reason})`);
     return { memoryCount: 0, estimatedTokens: 0 };
@@ -369,7 +370,7 @@ export async function buildAutoRecallContext(params: {
           limit: candidateLimit,
           scoreThreshold: 0,
           contextType: search.contextType,
-          actorPeerId: agentId,
+          actorPeerId,
         });
         return {
           resourceType: search.resourceType,
@@ -484,7 +485,7 @@ export async function buildAutoRecallContext(params: {
 
       const { lines: memoryLines, estimatedTokens } = await buildMemoryLinesWithBudget(
         memories,
-        (uri) => client.read(uri, agentId),
+        (uri) => client.read(uri, actorPeerId),
         {
           recallPreferAbstract,
           recallMaxInjectedChars: maxInjectedChars,

package/config.ts

@@ -1,13 +1,38 @@
 import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 
 import { getEnv } from "./runtime-utils.js";
 
+/**
+ * Subset of OpenClaw's standard `SecretRef` shape supported by the OpenViking
+ * plugin. The full runtime SDK also recognises `source: "exec"` with a
+ * provider plugin, but the plugin self-hosts its own env/file resolution so
+ * users on pluginSdkVersion < 2026.6.x (no host-level secret-resolver) still
+ * get vault-free secret management.
+ *
+ *   source: "env"  -> `process.env[id]` (same as the bare `${ENV}` string
+ *                     interpolation, but declarative and visible to UI hints).
+ *   source: "file" -> contents of `id` path (``~`` expansion supported),
+ *                     leading/trailing whitespace trimmed — convenient for
+ *                     Kubernetes `secretKeyRef` mount volumes and
+ *                     file-permission-only deployments.
+ *   source: "exec" -> delegate to host `openclaw` secret resolver when the
+ *                     runtime exposes it; today the plugin performs a
+ *                     best-effort `provider + id` CLI exec call so that
+ *                     1Password / Vault / gopass users can share OpenViking
+ *                     credentials with their other providers.
+ */
+export type OpenVikingSecretRef =
+  | { source: "env"; id: string }
+  | { source: "file"; id: string }
+  | { source: "exec"; provider: string; id: string };
+
 export type MemoryOpenVikingConfig = {
   mode?: "remote";
   baseUrl?: string;
   peer_role?: "none" | "assistant" | "person";
   peer_prefix?: string;
-  apiKey?: string;
+  apiKey?: string | OpenVikingSecretRef;
   /** Optional HTTP headers merged into every OpenViking request. */
   headers?: Record<string, string>;
   /** Advanced option. Only needed when explicitly sending tenant identity headers. With a user key the server derives identity from the key. */
@@ -102,8 +127,10 @@ export type MemoryOpenVikingConfig = {
 
 /** Runtime config after memoryOpenVikingConfigSchema.parse() has applied defaults. */
 export type ParsedMemoryOpenVikingConfig = Required<
-  Omit<MemoryOpenVikingConfig, "agentExperience" | "recallTargetTypes">
+  Omit<MemoryOpenVikingConfig, "agentExperience" | "recallTargetTypes" | "apiKey">
 > & {
+  /** parse() resolves SecretRef values, so the runtime shape is always a plain string. */
+  apiKey: string;
   agentExperience: Required<NonNullable<MemoryOpenVikingConfig["agentExperience"]>>;
   recallTargetTypes: Array<"resource" | "user" | "agent">;
 };
@@ -143,6 +170,8 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = [
   "ov_read",
   "ov_multi_read",
   "ov_list",
+  "search_experience",
+  "read_experience",
   "memory_recall",
   "ov_recall_trace",
   "memory_store",
@@ -163,6 +192,7 @@ export const OPENVIKING_TOOL_GROUPS: Record<string, readonly OpenVikingToolName[
   default: OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES,
   memory: ["memory_recall", "memory_store", "memory_forget"],
   resource_query: ["ov_search", "ov_read", "ov_multi_read", "ov_list"],
+  experience: ["search_experience", "read_experience"],
   import: ["add_resource", "add_skill"],
   recall_trace: ["ov_recall_trace"],
   archive: ["ov_archive_search", "ov_archive_expand"],
@@ -188,6 +218,105 @@ function resolvePeerPrefix(configured: unknown): string {
   return DEFAULT_PEER_PREFIX;
 }
 
+/**
+ * Resolve an {@link OpenVikingSecretRef} to the actual secret string. Plain
+ * strings pass through untouched so callers can compose this with the legacy
+ * `resolveEnvVars` pipeline without branching.
+ *
+ * Intentional behaviours:
+ *   * `env`: uses `getEnv` (process.env but exposed for vitest overrides). An
+ *     unset / empty env var is an error — the user asked for a named secret
+ *     so silent empty-string fallback would mask misconfigurations.
+ *   * `file`: ~ expanded, then read as UTF-8, then leading/trailing whitespace
+ *     stripped (de-facto standard for files written with `echo xxx > key`).
+ *     Missing / unreadable files propagate the original node error with an
+ *     error prefix that names the OpenViking field, so the user knows which
+ *     secretRef failed to load.
+ *   * `exec`: shells out `<provider> <id>`. Providers commonly expose this
+ *     shape (1Password CLI, gopass, HashiCorp Vault), which matches how
+ *     OpenClaw's own `@transmitt0r/openclaw-plugin-onepassword` provider
+ *     resolves `{source:"exec", provider:"onepassword", id:"..."}`. Exec is
+ *     best-effort; failures surface with an error prefix so users can
+ *     distinguish `provider not installed` from `provider configured but id
+ *     missing`.
+ */
+function resolveSecret(
+  value: string | OpenVikingSecretRef | undefined | null,
+  label: string,
+): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object") {
+    throw new Error(
+      `OpenViking ${label} must be a plain string or a SecretRef object ` +
+        `({source:"env"|"file"|"exec", id})`,
+    );
+  }
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.id !== "string" || !obj.id) {
+    throw new Error(`OpenViking ${label} SecretRef requires a non-empty string "id"`);
+  }
+  const id = obj.id;
+  switch (obj.source) {
+    case "env": {
+      const envValue = getEnv(id);
+      if (!envValue) {
+        throw new Error(
+          `OpenViking ${label} SecretRef env source: environment variable ${id} is not set or empty`,
+        );
+      }
+      return envValue;
+    }
+    case "file": {
+      const resolvedPath = expandHomeDir(id);
+      try {
+        const contents = readFileSync(resolvedPath, "utf8");
+        return contents.trim();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `OpenViking ${label} SecretRef file source: cannot read ${resolvedPath} (${msg})`,
+        );
+      }
+    }
+    case "exec": {
+      const provider = typeof (obj as Record<string, unknown>).provider === "string"
+        ? (obj as Record<string, unknown>).provider as string
+        : "";
+      if (!provider) {
+        throw new Error(
+          `OpenViking ${label} SecretRef exec source requires a "provider" field naming the secret-manager CLI on PATH`,
+        );
+      }
+      try {
+        // Avoid top-level `import "node:child_process"` — this branch is rare
+        // and keeping the require lazy makes startup marginally faster for
+        // the 95% of users who pick env/file.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
+        const out = execFileSync(provider, [id], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          timeout: 15_000,
+          env: process.env,
+        }) as string;
+        return out.trim();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `OpenViking ${label} SecretRef exec source: provider "${provider}" failed for id "${id}" (${msg})`,
+        );
+      }
+    }
+    default:
+      throw new Error(
+        `OpenViking ${label} SecretRef has unknown source "${String(
+          (obj as Record<string, unknown>).source,
+        )}". Supported: "env" | "file" | "exec".`,
+      );
+  }
+}
+
 function resolvePeerRole(configured: unknown) {
   if (typeof configured === "string") {
     const role = configured.trim().toLowerCase();
@@ -465,7 +594,14 @@ export const memoryOpenVikingConfigSchema = {
     const peerPrefix = resolvePeerPrefix(cfg.peer_prefix);
     const rawBaseUrl = typeof cfg.baseUrl === "string" ? cfg.baseUrl : resolveDefaultBaseUrl();
     const resolvedBaseUrl = resolveEnvVars(rawBaseUrl).replace(/\/+$/, "");
-    const rawApiKey = typeof cfg.apiKey === "string" ? cfg.apiKey : getEnv("OPENVIKING_API_KEY");
+    // Support plain string, SecretRef object, and OPENVIKING_API_KEY fallback.
+    // A user writing a SecretRef has explicitly opted out of the bare env
+    // interpolation path, so the fallback kicks in only when nothing is
+    // configured at all (matches existing behaviour).
+    const rawApiKey: string | OpenVikingSecretRef | undefined =
+      cfg.apiKey !== undefined && cfg.apiKey !== null
+        ? (cfg.apiKey as string | OpenVikingSecretRef)
+        : getEnv("OPENVIKING_API_KEY") || undefined;
     const captureMode = cfg.captureMode;
     if (
       typeof captureMode !== "undefined" &&
@@ -508,7 +644,7 @@ export const memoryOpenVikingConfigSchema = {
       baseUrl: resolvedBaseUrl,
       peer_role: peerRole,
       peer_prefix: peerPrefix,
-      apiKey: rawApiKey ? resolveEnvVars(rawApiKey) : "",
+      apiKey: rawApiKey ? resolveEnvVars(resolveSecret(rawApiKey, "config.apiKey")) : "",
       headers: toStringRecord(cfg.headers, "openviking config headers"),
       accountId,
       userId,
@@ -678,7 +814,10 @@ export const memoryOpenVikingConfigSchema = {
       label: "OpenViking API Key",
       sensitive: true,
       placeholder: "${OPENVIKING_API_KEY}",
-      help: "Optional API key for OpenViking server",
+      help:
+        "Optional API key for OpenViking server. Accepts a plain string, " +
+        "${ENV_VAR} interpolation, or a SecretRef object ({source: env/file/exec, id}). " +
+        "Prefer the SecretRef shapes so the key never sits as plaintext in openclaw.json.",
     },
     headers: {
       label: "Headers",
@@ -836,7 +975,7 @@ export const memoryOpenVikingConfigSchema = {
     enabledTools: {
       label: "Enabled Tools",
       placeholder: "default",
-      help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
+      help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, experience, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
       advanced: true,
     },
     disabledTools: {

package/context-engine.ts

@@ -283,7 +283,6 @@ export function createMemoryOpenVikingContextEngine(params: {
       getClient,
       logger,
       rememberSessionAgentId,
-      resolveAgentId,
       isBypassedSession,
     });
   }

package/dist/auto-recall.js

@@ -200,12 +200,12 @@ export function shouldRecallAgentExperience(input) {
     return { recall: false, score, reason: score < 0 ? "non_execution" : "below_threshold" };
 }
 export async function buildAutoRecallContext(params) {
-    const { cfg, client, agentId, queryText, logger, verbose } = params;
+    const { cfg, client, agentId, actorPeerId, queryText, logger, verbose } = params;
     const queryConfig = params.queryConfig;
     if (!cfg.autoRecall || queryText.length < 5) {
         return { memoryCount: 0, estimatedTokens: 0 };
     }
-    const precheck = await quickRecallPrecheck(client, agentId);
+    const precheck = await quickRecallPrecheck(client, actorPeerId);
     if (!precheck.ok) {
         verbose?.(`openviking: skipping auto-recall because precheck failed (${precheck.reason})`);
         return { memoryCount: 0, estimatedTokens: 0 };
@@ -236,7 +236,7 @@ export async function buildAutoRecallContext(params) {
                 limit: candidateLimit,
                 scoreThreshold: 0,
                 contextType: search.contextType,
-                actorPeerId: agentId,
+                actorPeerId,
             });
             return {
                 resourceType: search.resourceType,
@@ -343,7 +343,7 @@ export async function buildAutoRecallContext(params) {
             await recordTrace([], 0, 0);
             return { memoryCount: 0, estimatedTokens: 0 };
         }
-        const { lines: memoryLines, estimatedTokens } = await buildMemoryLinesWithBudget(memories, (uri) => client.read(uri, agentId), {
+        const { lines: memoryLines, estimatedTokens } = await buildMemoryLinesWithBudget(memories, (uri) => client.read(uri, actorPeerId), {
             recallPreferAbstract,
             recallMaxInjectedChars: maxInjectedChars,
             includeUri: true,

package/dist/config.js

@@ -1,4 +1,5 @@
 import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 import { getEnv } from "./runtime-utils.js";
 const DEFAULT_BASE_URL = "http://127.0.0.1:1933";
 const DEFAULT_TARGET_URI = "viking://user/memories";
@@ -34,6 +35,8 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = [
     "ov_read",
     "ov_multi_read",
     "ov_list",
+    "search_experience",
+    "read_experience",
     "memory_recall",
     "ov_recall_trace",
     "memory_store",
@@ -53,6 +56,7 @@ export const OPENVIKING_TOOL_GROUPS = {
     default: OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES,
     memory: ["memory_recall", "memory_store", "memory_forget"],
     resource_query: ["ov_search", "ov_read", "ov_multi_read", "ov_list"],
+    experience: ["search_experience", "read_experience"],
     import: ["add_resource", "add_skill"],
     recall_trace: ["ov_recall_trace"],
     archive: ["ov_archive_search", "ov_archive_expand"],
@@ -76,6 +80,91 @@ function resolvePeerPrefix(configured) {
     }
     return DEFAULT_PEER_PREFIX;
 }
+/**
+ * Resolve an {@link OpenVikingSecretRef} to the actual secret string. Plain
+ * strings pass through untouched so callers can compose this with the legacy
+ * `resolveEnvVars` pipeline without branching.
+ *
+ * Intentional behaviours:
+ *   * `env`: uses `getEnv` (process.env but exposed for vitest overrides). An
+ *     unset / empty env var is an error — the user asked for a named secret
+ *     so silent empty-string fallback would mask misconfigurations.
+ *   * `file`: ~ expanded, then read as UTF-8, then leading/trailing whitespace
+ *     stripped (de-facto standard for files written with `echo xxx > key`).
+ *     Missing / unreadable files propagate the original node error with an
+ *     error prefix that names the OpenViking field, so the user knows which
+ *     secretRef failed to load.
+ *   * `exec`: shells out `<provider> <id>`. Providers commonly expose this
+ *     shape (1Password CLI, gopass, HashiCorp Vault), which matches how
+ *     OpenClaw's own `@transmitt0r/openclaw-plugin-onepassword` provider
+ *     resolves `{source:"exec", provider:"onepassword", id:"..."}`. Exec is
+ *     best-effort; failures surface with an error prefix so users can
+ *     distinguish `provider not installed` from `provider configured but id
+ *     missing`.
+ */
+function resolveSecret(value, label) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (!value || typeof value !== "object") {
+        throw new Error(`OpenViking ${label} must be a plain string or a SecretRef object ` +
+            `({source:"env"|"file"|"exec", id})`);
+    }
+    const obj = value;
+    if (typeof obj.id !== "string" || !obj.id) {
+        throw new Error(`OpenViking ${label} SecretRef requires a non-empty string "id"`);
+    }
+    const id = obj.id;
+    switch (obj.source) {
+        case "env": {
+            const envValue = getEnv(id);
+            if (!envValue) {
+                throw new Error(`OpenViking ${label} SecretRef env source: environment variable ${id} is not set or empty`);
+            }
+            return envValue;
+        }
+        case "file": {
+            const resolvedPath = expandHomeDir(id);
+            try {
+                const contents = readFileSync(resolvedPath, "utf8");
+                return contents.trim();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`OpenViking ${label} SecretRef file source: cannot read ${resolvedPath} (${msg})`);
+            }
+        }
+        case "exec": {
+            const provider = typeof obj.provider === "string"
+                ? obj.provider
+                : "";
+            if (!provider) {
+                throw new Error(`OpenViking ${label} SecretRef exec source requires a "provider" field naming the secret-manager CLI on PATH`);
+            }
+            try {
+                // Avoid top-level `import "node:child_process"` — this branch is rare
+                // and keeping the require lazy makes startup marginally faster for
+                // the 95% of users who pick env/file.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { execFileSync } = require("node:child_process");
+                const out = execFileSync(provider, [id], {
+                    encoding: "utf8",
+                    stdio: ["ignore", "pipe", "pipe"],
+                    timeout: 15_000,
+                    env: process.env,
+                });
+                return out.trim();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`OpenViking ${label} SecretRef exec source: provider "${provider}" failed for id "${id}" (${msg})`);
+            }
+        }
+        default:
+            throw new Error(`OpenViking ${label} SecretRef has unknown source "${String(obj.source)}". Supported: "env" | "file" | "exec".`);
+    }
+}
 function resolvePeerRole(configured) {
     if (typeof configured === "string") {
         const role = configured.trim().toLowerCase();
@@ -320,7 +409,13 @@ export const memoryOpenVikingConfigSchema = {
         const peerPrefix = resolvePeerPrefix(cfg.peer_prefix);
         const rawBaseUrl = typeof cfg.baseUrl === "string" ? cfg.baseUrl : resolveDefaultBaseUrl();
         const resolvedBaseUrl = resolveEnvVars(rawBaseUrl).replace(/\/+$/, "");
-        const rawApiKey = typeof cfg.apiKey === "string" ? cfg.apiKey : getEnv("OPENVIKING_API_KEY");
+        // Support plain string, SecretRef object, and OPENVIKING_API_KEY fallback.
+        // A user writing a SecretRef has explicitly opted out of the bare env
+        // interpolation path, so the fallback kicks in only when nothing is
+        // configured at all (matches existing behaviour).
+        const rawApiKey = cfg.apiKey !== undefined && cfg.apiKey !== null
+            ? cfg.apiKey
+            : getEnv("OPENVIKING_API_KEY") || undefined;
         const captureMode = cfg.captureMode;
         if (typeof captureMode !== "undefined" &&
             captureMode !== "semantic" &&
@@ -342,7 +437,7 @@ export const memoryOpenVikingConfigSchema = {
             baseUrl: resolvedBaseUrl,
             peer_role: peerRole,
             peer_prefix: peerPrefix,
-            apiKey: rawApiKey ? resolveEnvVars(rawApiKey) : "",
+            apiKey: rawApiKey ? resolveEnvVars(resolveSecret(rawApiKey, "config.apiKey")) : "",
             headers: toStringRecord(cfg.headers, "openviking config headers"),
             accountId,
             userId,
@@ -423,7 +518,9 @@ export const memoryOpenVikingConfigSchema = {
             label: "OpenViking API Key",
             sensitive: true,
             placeholder: "${OPENVIKING_API_KEY}",
-            help: "Optional API key for OpenViking server",
+            help: "Optional API key for OpenViking server. Accepts a plain string, " +
+                "${ENV_VAR} interpolation, or a SecretRef object ({source: env/file/exec, id}). " +
+                "Prefer the SecretRef shapes so the key never sits as plaintext in openclaw.json.",
         },
         headers: {
             label: "Headers",
@@ -579,7 +676,7 @@ export const memoryOpenVikingConfigSchema = {
         enabledTools: {
             label: "Enabled Tools",
             placeholder: "default",
-            help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
+            help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, experience, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
             advanced: true,
         },
         disabledTools: {

package/dist/context-engine.js

@@ -135,7 +135,6 @@ export function createMemoryOpenVikingContextEngine(params) {
             getClient,
             logger,
             rememberSessionAgentId,
-            resolveAgentId,
             isBypassedSession,
         });
     }

package/dist/index.js

@@ -15,6 +15,7 @@ import { registerOpenVikingCommands } from "./plugin/command-registration.js";
 import { registerRecallTraceRoutes as registerRecallTraceRouteAdapters } from "./plugin/recall-trace-routes.js";
 import { createOpenVikingService } from "./plugin/openviking-services.js";
 import { registerOpenVikingArchiveTools } from "./plugin/openviking-archive-tools.js";
+import { registerOpenVikingExperienceTools } from "./plugin/openviking-experience-tools.js";
 import { createOpenVikingImportRuntime } from "./plugin/openviking-import-runtime.js";
 import { registerOpenVikingImportTools } from "./plugin/openviking-import-tools.js";
 import { registerOpenVikingLifecycleHooks } from "./plugin/openviking-lifecycle-hooks.js";
@@ -25,8 +26,8 @@ import { registerOpenVikingRecallTraceTools } from "./plugin/openviking-recall-t
 import { createOpenVikingRuntimeState } from "./plugin/openviking-runtime-state.js";
 import { createOpenVikingSessionRoutingRuntime } from "./plugin/openviking-session-routing-runtime.js";
 import { registerOpenVikingToolResultTools } from "./plugin/openviking-tool-result-tools.js";
-import { boundTraceQuery, createMemoryStoreTempSessionId, createTraceId, extractToolSenderId, inferRecallResourceType, makeBypassedToolResult, previewText, } from "./plugin/openviking-runtime-utils.js";
-import { formatMessageFaithful, toRoleId } from "./services/context-message-adapter.js";
+import { boundTraceQuery, createMemoryStoreTempSessionId, createTraceId, inferRecallResourceType, makeBypassedToolResult, previewText, } from "./plugin/openviking-runtime-utils.js";
+import { formatMessageFaithful } from "./services/context-message-adapter.js";
 import { clampScore, postProcessMemories, pickMemoriesForInjection, } from "./memory-ranking.js";
 import { createMemoryOpenVikingContextEngine, } from "./context-engine.js";
 import { openClawSessionRefToOvStorageId, openClawSessionToOvStorageId, } from "./routing/identity-routing.js";
@@ -80,6 +81,7 @@ const contextEnginePlugin = {
             logger: api.logger,
         });
         const { rememberSessionAgentId, resolveAgentId, resolvePluginSessionRouting, toQueryConfigContext, } = createOpenVikingSessionRoutingRuntime({
+            peerRole: cfg.peer_role,
             peerPrefix: cfg.peer_prefix,
             logFindRequests: cfg.logFindRequests,
             logger: api.logger,
@@ -135,6 +137,14 @@ const contextEnginePlugin = {
             isBypassedSession,
             makeBypassedToolResult,
         });
+        registerOpenVikingExperienceTools({
+            registerTool: registerOpenVikingTool,
+            getClient,
+            resolvePluginSessionRouting,
+            isBypassedSession,
+            makeBypassedToolResult,
+            userId: cfg.userId,
+        });
         registerOpenVikingMemoryRecallTools({
             registerTool: registerOpenVikingTool,
             getClient,
@@ -182,8 +192,7 @@ const contextEnginePlugin = {
             getClient,
             normalizeSessionId: openClawSessionRefToOvStorageId,
             createTempSessionId: createMemoryStoreTempSessionId,
-            extractSenderId: extractToolSenderId,
-            toRoleId,
+            peerRole: cfg.peer_role,
             resolvePluginSessionRouting,
             isBypassedSession,
             makeBypassedToolResult,

package/dist/plugin/openviking-archive-tools.js

@@ -55,7 +55,6 @@ export function registerOpenVikingArchiveTools(deps) {
                 const result = await client.grepSessionArchives(ovSessionId, escapedQuery, {
                     archiveId,
                     caseInsensitive: true,
-                    agentId,
                 });
                 const traceResults = (result.matches ?? []).slice(0, deps.traceRecallMaxResultsPerSearch).map((match) => ({
                     uri: match.uri,
@@ -175,7 +174,7 @@ export function registerOpenVikingArchiveTools(deps) {
             }
             try {
                 const client = await deps.getClient();
-                const detail = await client.getSessionArchive(session.ovSessionId, archiveId, session.agentId);
+                const detail = await client.getSessionArchive(session.ovSessionId, archiveId);
                 const header = [
                     `## ${detail.archive_id}`,
                     detail.abstract ? `**Summary**: ${detail.abstract}` : "",