@openviking/openclaw-plugin 2026.7.15 → 2026.8.6-1

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` | 打包版插件不支持（应用市场安装扫描会拦截子进程执行） | 改用命令包一层环境变量：`OPENVIKING_API_KEY=$(op read op://vault/openviking/credential)`，然后配 `env`。 |
+
+  仍可使用纯字符串形式（含 `${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` | not supported in the packaged plugin (marketplace install scanners block subprocess execution) | Wrap the CLI instead: `OPENVIKING_API_KEY=$(op read op://vault/openviking/credential)` and use `env`. |
+
+  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/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" -> NOT supported in the packaged plugin. Marketplace
+ *                     install scanners (OpenClaw/ArkClaw) block any plugin
+ *                     whose shipped code can spawn subprocesses, so the exec
+ *                     resolver was removed from this build; configuring it
+ *                     fails with a clear error pointing at env/file instead.
+ */
+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,81 @@ 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`: rejected with a "not supported" error. The subprocess-based
+ *     resolver was removed because marketplace install scanners block plugins
+ *     whose shipped code can spawn processes; wrap the secret-manager CLI
+ *     output into an env var or file instead (`OPENVIKING_API_KEY=$(op ...)`).
+ */
+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", 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": {
+      throw new Error(
+        `OpenViking ${label} SecretRef exec source is not supported in the packaged plugin ` +
+          `(marketplace install scanners block subprocess execution). Export the secret to an ` +
+          `environment variable ({source:"env"}) or a file ({source:"file"}) instead, e.g. ` +
+          `OPENVIKING_API_KEY=$(op read ${id}).`,
+      );
+    }
+    default:
+      throw new Error(
+        `OpenViking ${label} SecretRef has unknown source "${String(
+          (obj as Record<string, unknown>).source,
+        )}". Supported: "env" | "file".`,
+      );
+  }
+}
+
 function resolvePeerRole(configured: unknown) {
   if (typeof configured === "string") {
     const role = configured.trim().toLowerCase();
@@ -465,7 +570,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 +620,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 +790,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, id}). " +
+        "Prefer the SecretRef shapes so the key never sits as plaintext in openclaw.json.",
     },
     headers: {
       label: "Headers",
@@ -836,7 +951,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/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,68 @@ 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`: rejected with a "not supported" error. The subprocess-based
+ *     resolver was removed because marketplace install scanners block plugins
+ *     whose shipped code can spawn processes; wrap the secret-manager CLI
+ *     output into an env var or file instead (`OPENVIKING_API_KEY=$(op ...)`).
+ */
+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", 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": {
+            throw new Error(`OpenViking ${label} SecretRef exec source is not supported in the packaged plugin ` +
+                `(marketplace install scanners block subprocess execution). Export the secret to an ` +
+                `environment variable ({source:"env"}) or a file ({source:"file"}) instead, e.g. ` +
+                `OPENVIKING_API_KEY=$(op read ${id}).`);
+        }
+        default:
+            throw new Error(`OpenViking ${label} SecretRef has unknown source "${String(obj.source)}". Supported: "env" | "file".`);
+    }
+}
 function resolvePeerRole(configured) {
     if (typeof configured === "string") {
         const role = configured.trim().toLowerCase();
@@ -320,7 +386,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 +414,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 +495,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, id}). " +
+                "Prefer the SecretRef shapes so the key never sits as plaintext in openclaw.json.",
         },
         headers: {
             label: "Headers",
@@ -579,7 +653,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/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";
@@ -136,6 +137,14 @@ const contextEnginePlugin = {
             isBypassedSession,
             makeBypassedToolResult,
         });
+        registerOpenVikingExperienceTools({
+            registerTool: registerOpenVikingTool,
+            getClient,
+            resolvePluginSessionRouting,
+            isBypassedSession,
+            makeBypassedToolResult,
+            userId: cfg.userId,
+        });
         registerOpenVikingMemoryRecallTools({
             registerTool: registerOpenVikingTool,
             getClient,

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

@@ -0,0 +1,105 @@
+import { Type } from "@sinclair/typebox";
+const EXPERIENCE_TARGET_URI = "viking://user/memories/experiences/";
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 20;
+const EXPERIENCE_SIDECAR_FILENAMES = new Set([".abstract.md", ".overview.md", ".relations.json"]);
+function clampLimit(value) {
+    const parsed = Number.isFinite(Number(value)) ? Math.trunc(Number(value)) : DEFAULT_LIMIT;
+    return Math.max(1, Math.min(MAX_LIMIT, parsed));
+}
+function experienceRelativePath(uri) {
+    return uri.match(/^viking:\/\/user\/[^/]+\/memories\/experiences\/(.+)$/)?.[1] ?? "";
+}
+export function isCanonicalExperienceUri(uri, expectedUserId) {
+    const value = typeof uri === "string" ? uri.trim() : "";
+    if (!value || value.includes("?") || value.includes("#")) {
+        return false;
+    }
+    const owner = value.match(/^viking:\/\/user\/([^/]+)\//)?.[1] ?? "";
+    if (expectedUserId?.trim() && owner !== expectedUserId.trim()) {
+        return false;
+    }
+    const relative = experienceRelativePath(value);
+    const segments = relative.split("/");
+    const basename = segments.at(-1) ?? "";
+    return Boolean(relative
+        && segments.every((segment) => segment && segment !== "." && segment !== "..")
+        && !EXPERIENCE_SIDECAR_FILENAMES.has(basename));
+}
+function titleFromUri(uri) {
+    const basename = uri.split("/").at(-1) ?? uri;
+    const title = basename.replace(/\.md$/i, "");
+    try {
+        return decodeURIComponent(title);
+    }
+    catch {
+        return title;
+    }
+}
+function jsonToolResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+export function registerOpenVikingExperienceTools(deps) {
+    deps.registerTool((ctx) => ({
+        name: "search_experience",
+        label: "Search Experience (OpenViking)",
+        description: "Search reusable task-execution experiences for the current OpenViking user. " +
+            "Use before executing operational or multi-step tasks, then call read_experience for selected results.",
+        parameters: Type.Object({
+            query: Type.String({ description: "Current task, situation, or execution problem to search for" }),
+            limit: Type.Optional(Type.Integer({
+                description: `Maximum results to return. Default: ${DEFAULT_LIMIT}; maximum: ${MAX_LIMIT}`,
+                minimum: 1,
+                maximum: MAX_LIMIT,
+            })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("search_experience");
+            }
+            const query = typeof params.query === "string" ? params.query.trim() : "";
+            if (!query) {
+                throw new Error("query is required");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            const client = await deps.getClient();
+            const result = await client.find(query, {
+                targetUri: EXPERIENCE_TARGET_URI,
+                limit: clampLimit(params.limit),
+            }, session.actorPeerId);
+            const results = (result.memories ?? [])
+                .filter((item) => isCanonicalExperienceUri(item.uri, deps.userId))
+                .map((item) => ({
+                uri: item.uri,
+                title: titleFromUri(item.uri),
+                score: typeof item.score === "number" ? item.score : 0,
+                snippet: item.abstract || item.overview || "",
+            }));
+            return jsonToolResult({ results });
+        },
+    }), { name: "search_experience" });
+    deps.registerTool((ctx) => ({
+        name: "read_experience",
+        label: "Read Experience (OpenViking)",
+        description: "Read the complete Markdown body of one Experience returned by search_experience and use it as execution guidance.",
+        parameters: Type.Object({
+            uri: Type.String({ description: "Exact canonical Experience URI returned by search_experience" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("read_experience");
+            }
+            const uri = typeof params.uri === "string" ? params.uri.trim() : "";
+            if (!isCanonicalExperienceUri(uri, deps.userId)) {
+                throw new Error("uri must be a canonical OpenViking Experience URI returned by search_experience");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            const client = await deps.getClient();
+            const content = await client.read(uri, session.actorPeerId);
+            const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+            return jsonToolResult({ uri, content: text });
+        },
+    }), { name: "read_experience" });
+}

package/index.ts

@@ -19,6 +19,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";
@@ -280,6 +281,15 @@ const contextEnginePlugin = {
       makeBypassedToolResult,
     });
 
+    registerOpenVikingExperienceTools({
+      registerTool: registerOpenVikingTool,
+      getClient,
+      resolvePluginSessionRouting,
+      isBypassedSession,
+      makeBypassedToolResult,
+      userId: cfg.userId,
+    });
+
     registerOpenVikingMemoryRecallTools({
       registerTool: registerOpenVikingTool,
       getClient,

package/install-manifest.json

@@ -41,6 +41,7 @@
       ".gitignore",
       "skills/install-openviking-memory/SKILL.md",
       "skills/openviking-context-database/SKILL.md",
+      "skills/ov-experience-memory/SKILL.md",
       "INSTALL-AGENT.md"
     ]
   },

package/openclaw.plugin.json

@@ -3,6 +3,7 @@
   "name": "OpenViking",
   "kind": "context-engine",
   "description": "OpenClaw context-engine plugin for memory management — powered by OpenViking",
+  "icon": "https://raw.githubusercontent.com/volcengine/OpenViking/main/docs/images/ov-logo-icon.png",
   "activation": {
     "onStartup": true,
     "onCapabilities": [
@@ -12,11 +13,14 @@
   },
   "contracts": {
     "tools": [
+      "add_resource",
       "add_skill",
       "ov_search",
       "ov_read",
       "ov_multi_read",
       "ov_list",
+      "search_experience",
+      "read_experience",
       "memory_recall",
       "ov_recall_trace",
       "memory_store",
@@ -96,7 +100,7 @@
       "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, id}). Prefer a SecretRef so the key is never stored as plaintext in openclaw.json."
     },
     "headers": {
       "label": "Headers",
@@ -250,7 +254,7 @@
     "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": {
@@ -290,7 +294,34 @@
         "description": "Deprecated and ignored. Tenant identity headers are controlled by explicit accountId/userId."
       },
       "apiKey": {
-        "type": "string"
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "Plain API key or ${ENV_VAR} interpolation. For secret-manager-managed keys, prefer the SecretRef object shape below."
+          },
+          {
+            "type": "object",
+            "title": "SecretRef (env)",
+            "description": "Read the API key from an environment variable.",
+            "additionalProperties": false,
+            "required": ["source", "id"],
+            "properties": {
+              "source": { "type": "string", "const": "env", "description": "Look up the key in process.env[id] at plugin load time. Equivalent to ${ENV} interpolation but declarative and visible in the UI." },
+              "id": { "type": "string", "description": "Name of the environment variable. Example: OPENVIKING_API_KEY." }
+            }
+          },
+          {
+            "type": "object",
+            "title": "SecretRef (file)",
+            "description": "Read the API key from a file on disk, e.g. a Kubernetes secretKeyRef mount volume or a 0600-permission managed file. ~ is expanded and trailing whitespace is trimmed.",
+            "additionalProperties": false,
+            "required": ["source", "id"],
+            "properties": {
+              "source": { "type": "string", "const": "file" },
+              "id": { "type": "string", "description": "Absolute file path or ~/relative path. Example: /etc/secrets/openviking.key." }
+            }
+          }
+        ]
       },
       "headers": {
         "type": "object",

package/package.json

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

package/plugin/openviking-experience-tools.ts

@@ -0,0 +1,160 @@
+import { Type } from "@sinclair/typebox";
+
+import type { FindResult } from "../client.js";
+
+const EXPERIENCE_TARGET_URI = "viking://user/memories/experiences/";
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 20;
+const EXPERIENCE_SIDECAR_FILENAMES = new Set([".abstract.md", ".overview.md", ".relations.json"]);
+
+export type OpenVikingExperienceToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+  requesterSenderId?: string;
+};
+
+export type OpenVikingExperienceSession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+  actorPeerId?: string;
+};
+
+type OpenVikingExperienceClient = {
+  find: (
+    query: string,
+    options: { targetUri: string; limit: number; scoreThreshold?: number },
+    actorPeerId?: string,
+  ) => Promise<FindResult>;
+  read: (uri: string, actorPeerId?: string) => Promise<unknown>;
+};
+
+export type OpenVikingExperienceToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingExperienceClient>;
+  resolvePluginSessionRouting: (ctx?: OpenVikingExperienceToolContext) => OpenVikingExperienceSession;
+  isBypassedSession: (ctx?: OpenVikingExperienceToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  userId?: string;
+};
+
+function clampLimit(value: unknown): number {
+  const parsed = Number.isFinite(Number(value)) ? Math.trunc(Number(value)) : DEFAULT_LIMIT;
+  return Math.max(1, Math.min(MAX_LIMIT, parsed));
+}
+
+function experienceRelativePath(uri: string): string {
+  return uri.match(/^viking:\/\/user\/[^/]+\/memories\/experiences\/(.+)$/)?.[1] ?? "";
+}
+
+export function isCanonicalExperienceUri(uri: unknown, expectedUserId?: string): uri is string {
+  const value = typeof uri === "string" ? uri.trim() : "";
+  if (!value || value.includes("?") || value.includes("#")) {
+    return false;
+  }
+  const owner = value.match(/^viking:\/\/user\/([^/]+)\//)?.[1] ?? "";
+  if (expectedUserId?.trim() && owner !== expectedUserId.trim()) {
+    return false;
+  }
+  const relative = experienceRelativePath(value);
+  const segments = relative.split("/");
+  const basename = segments.at(-1) ?? "";
+  return Boolean(
+    relative
+    && segments.every((segment) => segment && segment !== "." && segment !== "..")
+    && !EXPERIENCE_SIDECAR_FILENAMES.has(basename)
+  );
+}
+
+function titleFromUri(uri: string): string {
+  const basename = uri.split("/").at(-1) ?? uri;
+  const title = basename.replace(/\.md$/i, "");
+  try {
+    return decodeURIComponent(title);
+  } catch {
+    return title;
+  }
+}
+
+function jsonToolResult(payload: Record<string, unknown>): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+  };
+}
+
+export function registerOpenVikingExperienceTools(deps: OpenVikingExperienceToolsDeps): void {
+  deps.registerTool(
+    (ctx: OpenVikingExperienceToolContext) => ({
+      name: "search_experience",
+      label: "Search Experience (OpenViking)",
+      description:
+        "Search reusable task-execution experiences for the current OpenViking user. " +
+        "Use before executing operational or multi-step tasks, then call read_experience for selected results.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Current task, situation, or execution problem to search for" }),
+        limit: Type.Optional(Type.Integer({
+          description: `Maximum results to return. Default: ${DEFAULT_LIMIT}; maximum: ${MAX_LIMIT}`,
+          minimum: 1,
+          maximum: MAX_LIMIT,
+        })),
+      }, { additionalProperties: false }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("search_experience");
+        }
+        const query = typeof params.query === "string" ? params.query.trim() : "";
+        if (!query) {
+          throw new Error("query is required");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const client = await deps.getClient();
+        const result = await client.find(query, {
+          targetUri: EXPERIENCE_TARGET_URI,
+          limit: clampLimit(params.limit),
+        }, session.actorPeerId);
+        const results = (result.memories ?? [])
+          .filter((item) => isCanonicalExperienceUri(item.uri, deps.userId))
+          .map((item) => ({
+            uri: item.uri,
+            title: titleFromUri(item.uri),
+            score: typeof item.score === "number" ? item.score : 0,
+            snippet: item.abstract || item.overview || "",
+          }));
+        return jsonToolResult({ results });
+      },
+    }),
+    { name: "search_experience" },
+  );
+
+  deps.registerTool(
+    (ctx: OpenVikingExperienceToolContext) => ({
+      name: "read_experience",
+      label: "Read Experience (OpenViking)",
+      description:
+        "Read the complete Markdown body of one Experience returned by search_experience and use it as execution guidance.",
+      parameters: Type.Object({
+        uri: Type.String({ description: "Exact canonical Experience URI returned by search_experience" }),
+      }, { additionalProperties: false }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("read_experience");
+        }
+        const uri = typeof params.uri === "string" ? params.uri.trim() : "";
+        if (!isCanonicalExperienceUri(uri, deps.userId)) {
+          throw new Error("uri must be a canonical OpenViking Experience URI returned by search_experience");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const client = await deps.getClient();
+        const content = await client.read(uri, session.actorPeerId);
+        const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+        return jsonToolResult({ uri, content: text });
+      },
+    }),
+    { name: "read_experience" },
+  );
+}

package/registries/openviking-tools.ts

@@ -1,6 +1,7 @@
 export type OpenVikingToolGroup =
   | "memory"
   | "resource_query"
+  | "experience"
   | "import"
   | "recall_trace"
   | "archive"
@@ -13,6 +14,8 @@ export type OpenVikingToolName =
   | "ov_read"
   | "ov_multi_read"
   | "ov_list"
+  | "search_experience"
+  | "read_experience"
   | "memory_recall"
   | "ov_recall_trace"
   | "memory_store"
@@ -44,6 +47,8 @@ export const OPENVIKING_TOOL_SPECS = [
   { name: "ov_read", group: "resource_query", defaultEnabled: true },
   { name: "ov_multi_read", group: "resource_query", defaultEnabled: true },
   { name: "ov_list", group: "resource_query", defaultEnabled: true },
+  { name: "search_experience", group: "experience", defaultEnabled: true },
+  { name: "read_experience", group: "experience", defaultEnabled: true },
   { name: "memory_recall", group: "memory", defaultEnabled: true },
   { name: "ov_recall_trace", group: "recall_trace", defaultEnabled: true },
   { name: "memory_store", group: "memory", defaultEnabled: true },
@@ -64,6 +69,7 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = OPENVIKING_TOOL_SPECS
 const OPENVIKING_TOOL_GROUP_ORDER: readonly OpenVikingToolGroup[] = [
   "memory",
   "resource_query",
+  "experience",
   "import",
   "recall_trace",
   "archive",

package/skills/ov-experience-memory/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ov-experience-memory
+description: >
+  Use OpenViking experience memories during task execution. Search relevant
+  experiences with search_experience, read selected experiences with
+  read_experience, and leave standard tool parts in the committed session so
+  OpenViking can report recall and injection usage.
+version: 2026.7.9
+tags:
+  - openviking
+  - experience-memory
+  - agent-memory
+  - usage-reporting
+---
+
+# OpenViking Experience Memory
+
+Use this skill when the current user request starts or continues an executable
+task, especially tasks involving tools, files, code changes, data operations,
+workflow decisions, or multi-step actions.
+
+Do not use this skill for casual chat, pure explanation, or one-off factual Q&A
+that does not require operational guidance.
+
+## Runtime Contract
+
+The agent runtime must expose two tools with these exact names:
+
+- `search_experience`
+- `read_experience`
+
+OpenViking usage reporting recognizes only completed tool parts with these exact
+tool names. Calls to generic `find`, `search`, `read`, `ov_search`, or `ov_read`
+do not count as experience recall or injection events.
+
+## Tool: search_experience
+
+Purpose: search reusable execution experiences from the OpenViking experience
+library before assembling task context.
+
+Input schema:
+
+```json
+{
+  "query": "string",
+  "limit": 5
+}
+```
+
+Output schema:
+
+```json
+{
+  "results": [
+    {
+      "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
+      "title": "example",
+      "score": 0.82,
+      "snippet": "Short summary or matched situation"
+    }
+  ]
+}
+```
+
+Implementation:
+
+The runtime tool calls OpenViking `POST /api/v1/search/find` with `target_uri`
+fixed to the current-user shorthand `viking://user/memories/experiences/`.
+Callers provide only `query` and optional `limit`; they cannot override or pass
+`target_uri`. OpenViking resolves the fixed shorthand against the authenticated
+request user. Return only canonical experience memory URIs for that user; never
+hardcode `default` or another user ID.
+
+Usage reporting:
+
+A completed `search_experience` tool part is counted as an experience recall
+event for every `results[].uri` value.
+
+## Tool: read_experience
+
+Purpose: read the full Markdown body of a selected experience and inject it into
+the agent prompt as task execution guidance.
+
+Input schema:
+
+```json
+{
+  "uri": "viking://user/<current_user_id>/memories/experiences/example.md"
+}
+```
+
+Output schema:
+
+```json
+{
+  "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
+  "content": "Experience Markdown body"
+}
+```
+
+Implementation:
+
+Call OpenViking `GET /api/v1/content/read?uri=<encoded_uri>` for the selected
+experience URI. Always pass the canonical URI returned by `search_experience`;
+do not construct a URI with a hardcoded user ID. The returned content should be
+inserted into the prompt as operational guidance, not as user profile facts.
+
+Usage reporting:
+
+A completed `read_experience` tool part is counted as an experience injection
+event for `tool_input.uri` or `tool_output.uri`. In this design, reading an
+experience through `read_experience` means the experience was injected into the
+prompt.
+
+## Recommended Flow
+
+1. When a task begins, build a short query from the latest user instruction,
+   current plan, active skill name, and important tool/environment context.
+2. Call `search_experience` before final prompt assembly.
+3. Review returned titles/snippets and select only experiences likely to affect
+   execution.
+4. Call `read_experience` for selected experience URIs.
+5. Inject the returned Markdown into the prompt under an explicit experience
+   section.
+6. Continue task execution.
+7. Commit the session normally. The committed session must include the
+   `search_experience` and `read_experience` tool parts so OpenViking can report
+   usage.
+
+## Prompt Injection Format
+
+Use a compact and explicit block:
+
+```text
+<openviking-experience-memory>
+The following guidance was retrieved from prior task execution experience.
+Use it as operational guidance. Do not treat it as user identity or preference.
+
+<experience uri="viking://user/<current_user_id>/memories/experiences/example.md">
+...experience markdown...
+</experience>
+</openviking-experience-memory>
+```
+
+## Commit Requirements
+
+The session committed to OpenViking must preserve tool parts with:
+
+- `tool_name`
+- `tool_status`
+- `tool_input`
+- `tool_output`
+- `tool_id`
+
+Only `tool_status == "completed"` is counted. Failed, cancelled, or skipped tool
+parts are ignored by usage reporting.