feat(openclaw): sync OpenViking plugin runtime and docs by superops-team · Pull Request #2613 · volcengine/OpenViking

superops-team · 2026-06-15T08:09:15Z

Summary

This PR syncs the OpenViking OpenClaw plugin runtime into the community examples/openclaw-plugin tree while preserving upstream behavior and the plugin capabilities that were previously developed in the external OpenClaw/OpenViking integration branch.

The main goal is to make the OpenClaw plugin easier to install, test, observe, and maintain from the community repository itself.

What changed

1. Modularized the OpenClaw plugin runtime

The previous plugin entrypoint had too much logic in large files. This PR splits the runtime into smaller, testable modules:

tool registration and command registration
query runtime for ov_search, ov_read, ov_multi_read, and ov_list
memory recall tools and memory/archive tools
recall trace tools and HTTP route handlers
session routing and bypass-session handling
runtime state setup for query config and trace recorder
context engine registration and lifecycle service

2. Added runtime query configuration

Adds a runtime query configuration store so recall/search behavior can be tuned without restarting OpenClaw.

Supported override layers:

request overrides
  > session runtime config
  > claw runtime config
  > static plugin config
  > defaults

Supported settings include recall limit, candidate limit, score threshold, injected context budget, resource types, target URI, ov_search default limit, and ranking/category/resource-type weights.

3. Added recall trace observability

Adds recall trace recording, persistence, query tools, and HTTP APIs so users can inspect what the plugin recalled and why.

Capabilities:

trace recording for ov_search, memory_recall, and auto-recall paths
JSONL persistence with fallback from memory to disk
ov_recall_trace tool support
HTTP APIs for trace lists, trace detail, latest ov_search result list, and URI detail lookup
content previews and resource type inference

4. Improved install and release paths

Adds a more complete plugin packaging and install flow, including GitHub-free / TOS-based install support.

5. Expanded tests and architecture guards

Adds regression coverage for module boundaries, query config, feature gates, install contracts, tool registration, and runtime behavior.

Why this refactor

This refactor solves four maintenance problems:

Large entrypoint files were hard to review and change safely.
OpenClaw Gateway behavior needed real observability.
Recall/search tuning required config edits and restarts.
Plugin distribution needed a community-repo path.

Validation

Local verification from examples/openclaw-plugin:

npm test
Test Files  42 passed (42)
Tests       717 passed (717)

npm run typecheck

Result: passed.

npm run build

Result: passed.

Additional real-scenario validation was performed with Docker OpenClaw 2026.5.28:

Gateway pairing and scope approval flow
OpenViking plugin load and tool registration
OpenClaw agent calling ov_search
Gateway WebSocket RPC calls for health, status, system-presence, tools.catalog, tools.effective, and tools.invoke
HTTP trace APIs for recall traces, latest ov_search list, and URI detail
JSONL recall trace persistence and schema checks
Ark DeepSeek V4 Flash model configuration via environment-provided Ark credentials

Notes for reviewers

This is a large refactor, but the functional center is limited to examples/openclaw-plugin.

Recommended review order:

examples/openclaw-plugin/index.ts for the new composition flow
examples/openclaw-plugin/services/context-lifecycle-service.ts for lifecycle behavior
examples/openclaw-plugin/plugin/openviking-query-runtime.ts for query tool behavior
examples/openclaw-plugin/plugin/openviking-recall-trace-runtime.ts and recall-trace.ts for observability
examples/openclaw-plugin/query-config.ts for runtime config semantics
examples/openclaw-plugin/tests/ut/* for regression coverage

Compatibility

Keeps OpenClaw plugin compatibility at >=2026.4.8.
Keeps existing OpenViking client behavior while adding runtime configuration and traceability.
Keeps setup-only mode when config parsing fails, so users can recover with openclaw openviking setup.

github-actions · 2026-06-15T08:10:59Z

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪
🏅 Score: 85
🧪 PR contains tests
🔒 No security concerns identified
✅ No TODO sections
🔀 Multiple PR themes Sub-PR theme: Add TOS upload script and tests Relevant files: examples/openclaw-plugin/scripts/upload_tos.py examples/openclaw-plugin/scripts/test_upload_tos.py Sub-PR theme: Add query runtime and recall trace modules Relevant files: examples/openclaw-plugin/plugin/openviking-query-runtime.ts examples/openclaw-plugin/plugin/openviking-recall-trace-runtime.ts examples/openclaw-plugin/recall-trace.ts examples/openclaw-plugin/query-config.ts Sub-PR theme: Update tests and health check to support agent ID Relevant files: examples/openclaw-plugin/tests/e2e/test-archive-expand.py examples/openclaw-plugin/tests/e2e/test-tool-capture.py examples/openclaw-plugin/tests/e2e/test-memory-chain.py examples/openclaw-plugin/tests/test-tool-capture.py examples/openclaw-plugin/tests/test-memory-chain.py examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
⚡ No major issues detected

github-actions · 2026-06-15T08:12:40Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix test to use correct transport mock instead of unused client read mock The test uses a `readMock` passed as a client override, but the `ov_read` tool likely uses the `openVikingTransport` attached to the API object instead of a client `read` method. This makes the `expect(readMock).not.toHaveBeenCalled()` assertion a false positive, as it doesn't verify anything about the actual API call. Replace the `readMock` with an `openVikingTransport` mock to properly verify no API call is made. examples/openclaw-plugin/tests/ut/tools.test.ts [1248-1258] it("rejects display-truncated ov_read URIs before calling OpenViking", async () => { - const readMock = vi.fn().mockResolvedValue("content"); - const { tools, api } = setupPlugin({ read: readMock }); + const openVikingTransport = vi.fn().mockResolvedValue("content"); + const { tools, api } = setupPlugin(); + (api as any).openVikingTransport = openVikingTransport; contextEnginePlugin.register(api as any); const read = tools.get("ov_read")!; await expect(read.execute("tc-truncated-uri", { uri: "viking://resources/harness-paper/2._OpenCompass司南_面向大模型时代的罗盘全面开放与分布式的评测体系/2.3_解决思...", })).rejects.toThrow("truncated display URI"); - expect(readMock).not.toHaveBeenCalled(); + expect(openVikingTransport).not.toHaveBeenCalled(); }); Suggestion importance[1-10]: 6 __ Why: The original test used an unused `readMock` client override that didn’t verify the actual API call. The improved version uses `openVikingTransport` (consistent with other tests in the PR) to properly assert no transport call is made, fixing a false positive assertion.	Low

qin-ctx

这版实现看起来是从旧版 OpenClaw plugin runtime 同步过来的，但目标分支 main 现在已经迁到 user/peer contract。当前 patch 会把主线已有的 peer_role、X-OpenViking-Actor-Peer、peer_id、peer memory policy 等行为覆盖回旧的 user/agent 路径。模块化、recall trace、runtime query config 这些方向可以继续推进，但需要先基于当前 main 重新 port：新迭代应继续使用 user/peer，agent 相关字段只保留薄兼容或迁移入口，不能成为默认 runtime path。

qin-ctx · 2026-06-15T09:28:41Z

+    const effectiveAgentId = this.resolveEffectiveAgentId(agentId);
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), requestTimeoutMs ?? this.timeoutMs);
    try {


[Design] (blocking) 这一段请求路径把 OpenClaw plugin 的身份重新切回了 X-OpenViking-Agent（本 hunk 里 headers.set("X-OpenViking-Agent", effectiveAgentId)），并且后续 addSessionMessage 也从当前 main 的 peer_id 改成了 role_id。这看起来是从旧 runtime 基线同步过来的，但目标分支已经切到 user/peer：recall 应通过 X-OpenViking-Actor-Peer 过滤，session message 应用 peer_id 做归因，agentId 只能作为 legacy alias/migration 入口。否则群聊/多用户场景会回退到旧的 user/agent 隔离语义。

qin-ctx · 2026-06-15T09:28:41Z

-  parse(value: unknown): ParsedMemoryOpenVikingConfig {
+  parse(value: unknown): Required<MemoryOpenVikingConfig> {
    if (!value || typeof value !== "object" || Array.isArray(value)) {
      value = {};


[Bug] (blocking) 这个 parser 改动删除了 main 上已经支持的 peer_role、peer_prefix、autoRecallTimeoutMs、agentExperience 等配置项，允许字段列表里只保留了新的 agent 配置面。现有安装升级到这个 PR 后会配置解析失败或丢功能，这说明这次同步不是薄兼容，而是在用旧配置面覆盖当前主线配置面。建议保留 current user/peer 配置，并把旧外部分支里的 agent 字段映射到新模型。

qin-ctx · 2026-06-15T09:28:41Z

@@ -0,0 +1,80 @@
+export const ALLOWED_RECALL_RESOURCE_TYPES = ["resource", "session", "user", "agent"] as const;
+export type RecallResourceType = typeof ALLOWED_RECALL_RESOURCE_TYPES[number];
+export const DEFAULT_RECALL_RESOURCE_TYPES: readonly RecallResourceType[] = ["user", "agent"];


[Design] (blocking) 默认 recall target 现在是 user + agent，并会默认查 viking://agent/memories。当前主线迭代要求是 user/peer，所以默认召回不应依赖旧 agent namespace；person/assistant 相关记忆应通过 user scope 加 actor peer 过滤。agent scope 可以保留为显式 legacy 选项，但不能成为默认 runtime path。

feat(openclaw): sync OpenViking plugin docs and runtime

73f32e0

github-project-automation Bot added this to OpenViking project Jun 15, 2026

github-project-automation Bot moved this to Backlog in OpenViking project Jun 15, 2026

qin-ctx requested changes Jun 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(openclaw): sync OpenViking plugin runtime and docs#2613

feat(openclaw): sync OpenViking plugin runtime and docs#2613
superops-team wants to merge 1 commit into
volcengine:mainfrom
superops-team:openclaw-plugin-sync-runtime

superops-team commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026

Uh oh!

qin-ctx left a comment

Uh oh!

qin-ctx Jun 15, 2026 •

edited

Loading

Uh oh!

qin-ctx Jun 15, 2026 •

edited

Loading

Uh oh!

qin-ctx Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

superops-team commented Jun 15, 2026

Summary

What changed

1. Modularized the OpenClaw plugin runtime

2. Added runtime query configuration

3. Added recall trace observability

4. Improved install and release paths

5. Expanded tests and architecture guards

Why this refactor

Validation

Notes for reviewers

Compatibility

Uh oh!

github-actions Bot commented Jun 15, 2026

PR Reviewer Guide 🔍

Uh oh!

github-actions Bot commented Jun 15, 2026

PR Code Suggestions ✨

Uh oh!

qin-ctx left a comment

Choose a reason for hiding this comment

Uh oh!

qin-ctx Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qin-ctx Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qin-ctx Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

qin-ctx Jun 15, 2026 •

edited

Loading

qin-ctx Jun 15, 2026 •

edited

Loading