@openviking/openclaw-plugin 2026.5.8 → 2026.5.21

package/INSTALL-AGENT.md

@@ -13,10 +13,10 @@ This package is the OpenClaw plugin `@openviking/openclaw-plugin`.
 
 | User intent | Command |
 | --- | --- |
-| Fresh install, latest | `openclaw plugins install @openviking/openclaw-plugin` |
-| Upgrade plugin to latest | `openclaw plugins install @openviking/openclaw-plugin` |
+| Fresh install, latest | `openclaw plugins install clawhub:@openviking/openclaw-plugin` |
+| Upgrade plugin to latest | `openclaw plugins install clawhub:@openviking/openclaw-plugin` |
 | Install or upgrade a specific release | Use the published ClawHub package selector if available; otherwise ask before using backup `ov-install --plugin-version=<REF>` |
-| Upgrade only the plugin | `openclaw plugins install @openviking/openclaw-plugin` |
+| Upgrade only the plugin | `openclaw plugins install clawhub:@openviking/openclaw-plugin` |
 | Show installed plugins | `openclaw plugins list` |
 | Backup install when ClawHub is unavailable | `npx -y openclaw-openviking-setup-helper@latest --base-url <URL> [--api-key <KEY>]` |
 | Operate on a specific OpenClaw instance | add `--workdir <path>` |
@@ -31,7 +31,7 @@ clawhub install openviking
 That installs an AgentSkill, not the plugin. The plugin install command is:
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## Required Inputs
@@ -53,7 +53,7 @@ Never silently replace another context engine.
 Use this workflow for normal installs and upgrades from published packages.
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json
@@ -220,7 +220,7 @@ openclaw plugins list
 Fresh install:
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json
@@ -307,7 +307,7 @@ Same plugin ID (openviking, >= 0.3.x):
 
 ```bash
 rm -rf ~/.openclaw/extensions/openviking/
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --reconfigure
 openclaw gateway restart
 openclaw openviking status --json
@@ -319,7 +319,7 @@ Old plugin ID (memory-openviking, < 0.3.x):
 openclaw plugins uninstall memory-openviking 2>/dev/null || true
 openclaw config set plugins.slots.memory none
 rm -rf ~/.openclaw/extensions/memory-openviking/
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json
@@ -333,7 +333,7 @@ Existing config fields are preserved during migration. The new plugin reads old
 
 ## Backup Path: ov-install
 
-`ov-install` is the backup path, not the primary user install path. Use it when `openclaw plugins install @openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when the user explicitly wants a source ref / Git branch install.
+`ov-install` is the backup path, not the primary user install path. Use it when `openclaw plugins install clawhub:@openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when the user explicitly wants a source ref / Git branch install.
 
 Backup install:
 
@@ -352,4 +352,4 @@ Backup/source commands:
 | Show helper-tracked version | `ov-install --current-version` |
 | Update helper-managed install | `ov-install --update` |
 
-For user installs, always try `openclaw plugins install @openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
+For user installs, always try `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.

package/INSTALL-ZH.md

@@ -19,7 +19,7 @@ clawhub install openviking
 安装插件应使用：
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## 前置要求
@@ -36,7 +36,7 @@ OpenClaw 插件包版本边界：
 - `2026.4.8` 是当前插件支持的最低 OpenClaw 版本。
 - `2026.5.3` 开始，OpenClaw 在安装包时会校验 TypeScript 插件入口是否有编译后的 JavaScript 产物。
 - `2026.5.4` 及之后，已安装/全局插件如果缺少编译后的 JavaScript，运行时不再回退加载 `.ts` 源码，插件可能被跳过。
-- 推荐的 `openclaw plugins install @openviking/openclaw-plugin` 会安装已经发布并包含 `dist/*.js` 的插件包，普通用户不需要本地编译。
+- 推荐的 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 会安装已经发布并包含 `dist/*.js` 的插件包，普通用户不需要本地编译。
 - `ov-install` 是备用/源码安装路径。当 ClawHub 或 OpenClaw 插件管理器路径不可用、被限流，或者明确需要测试源码 ref 时才使用。目标 OpenClaw `>= 2026.5.3` 时，它会在安装过程中编译插件。
 
 快速检查：
@@ -87,7 +87,7 @@ curl http://127.0.0.1:1933/health
 ### 1. 安装插件
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 如果你的 OpenClaw 环境需要显式 registry 前缀，使用：
@@ -271,7 +271,7 @@ python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
 
 ## 备用路径：ov-install
 
-`ov-install` 是备用路径，不是主安装方式。仅当 `openclaw plugins install @openviking/openclaw-plugin` 无法访问 ClawHub、被限流，或者你明确需要从 Git 分支/源码 ref 安装测试时使用。
+`ov-install` 是备用路径，不是主安装方式。仅当 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 无法访问 ClawHub、被限流，或者你明确需要从 Git 分支/源码 ref 安装测试时使用。
 
 先尝试 OpenClaw 插件管理器。如果该路径不可用，再执行：
 
@@ -285,14 +285,14 @@ ov-install
 | 参数 | 含义 |
 | --- | --- |
 | `--workdir PATH` | 指定 OpenClaw state 目录 |
-| `--version REF` | 指定 Git ref、tag、branch 或发布版本 |
+| `--plugin-version=REF` | 指定插件版本：npm 版本、npm dist-tag 或 Git ref |
 | `--current-version` | 查看 helper 记录的当前版本 |
 | `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
 | `--api-key KEY` | OpenViking API key |
 | `--agent-prefix PREFIX` | Agent 路由前缀 |
 | `--update` | 更新 helper 管理的安装 |
 
-面向用户的安装，请先使用 `openclaw plugins install @openviking/openclaw-plugin`。只有作为备用路径时才选择 `ov-install`。
+面向用户的安装，请先使用 `openclaw plugins install clawhub:@openviking/openclaw-plugin`。只有作为备用路径时才选择 `ov-install`。
 
 ## 从 ov-install 迁移到 openclaw plugin install
 
@@ -307,7 +307,7 @@ ov-install 的 context-engine 部署会将文件写入 `~/.openclaw/extensions/o
 rm -rf ~/.openclaw/extensions/openviking/
 
 # 通过 OpenClaw 插件管理器安装
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 
 # 重新配置（openclaw.json 中的已有配置会保留）
 openclaw openviking setup --reconfigure
@@ -330,7 +330,7 @@ openclaw config set plugins.slots.memory none
 rm -rf ~/.openclaw/extensions/memory-openviking/
 
 # 安装新插件
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json

package/INSTALL.md

@@ -19,7 +19,7 @@ That command installs an AgentSkill named `openviking`, not the OpenClaw plugin.
 Use this plugin command instead:
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## Requirements
@@ -36,7 +36,7 @@ OpenClaw plugin package boundaries:
 - `2026.4.8` is the minimum supported OpenClaw version for the current plugin.
 - `2026.5.3` starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
 - `2026.5.4` and later stop falling back to `.ts` source for installed/global plugin runtime loading when compiled JavaScript is missing.
-- The recommended `openclaw plugins install @openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.
+- The recommended `openclaw plugins install clawhub:@openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.
 - `ov-install` is the backup/source install path. Use it when ClawHub or the OpenClaw plugin manager path is unavailable/rate-limited, or when explicitly testing a source ref. For OpenClaw `>= 2026.5.3`, it builds the plugin during installation.
 
 Quick check:
@@ -87,7 +87,7 @@ Use this path for normal users, production installs, and agent-assisted installs
 ### 1. Install The Plugin
 
 ```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 If your OpenClaw installation requires an explicit registry prefix, use:
@@ -253,7 +253,7 @@ This checks the Gateway to OpenViking path by injecting a real conversation and
 
 ## Backup Path: ov-install
 
-`ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install @openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
+`ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install clawhub:@openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
 
 Try the OpenClaw plugin manager first. If that path is unavailable, run:
 
@@ -267,14 +267,14 @@ Useful backup/source flags:
 | Flag | Meaning |
 | --- | --- |
 | `--workdir PATH` | Target OpenClaw state directory |
-| `--version REF` | Git ref, tag, branch, or release version to install |
+| `--plugin-version=REF` | Plugin version: npm version, npm dist-tag, or Git ref to install |
 | `--current-version` | Print the version tracked by the helper |
 | `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
 | `--api-key KEY` | OpenViking API key |
 | `--agent-prefix PREFIX` | Agent routing prefix |
 | `--update` | Update an existing helper-managed install |
 
-For user-facing installs, use `openclaw plugins install @openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
+For user-facing installs, use `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
 
 ## Migrate From ov-install To openclaw plugin install
 
@@ -289,7 +289,7 @@ The ov-install context-engine deployment writes files to `~/.openclaw/extensions
 rm -rf ~/.openclaw/extensions/openviking/
 
 # Install via the OpenClaw plugin manager
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 
 # Reconfigure (your existing config in openclaw.json is preserved)
 openclaw openviking setup --reconfigure
@@ -347,7 +347,7 @@ openclaw config set plugins.slots.memory none
 rm -rf ~/.openclaw/extensions/memory-openviking/
 
 # Install new plugin
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json

package/README.md

@@ -1,59 +1,78 @@
-# @openviking/openclaw-plugin — OpenViking OpenClaw Plugin
+# OpenViking for OpenClaw
 
-OpenClaw context-engine plugin for OpenViking remote memory, context database, RAG and semantic retrieval.
+Use [OpenViking](https://github.com/volcengine/OpenViking) as OpenClaw's long-term context engine: automatic recall, session archive, memory extraction, semantic search, and RAG over a remote OpenViking server.
 
-## Important: Plugin vs Skill
+## Quick Start
 
-This page is for the **OpenClaw plugin package**:
-
-```
-@openviking/openclaw-plugin
+```bash
+openclaw plugins install clawhub:@openviking/openclaw-plugin
+openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --json
+openclaw gateway restart
+openclaw openviking status --json
 ```
 
-**Do NOT** install the plugin with `clawhub install openviking` — that installs the `openviking` AgentSkill (under `skills/openviking`), which is a different thing.
+That's it. The `setup` command activates the context-engine slot and validates the connection.
 
-For **agent-assisted plugin setup**, ask the agent to follow [INSTALL-AGENT.md](./INSTALL-AGENT.md). The primary install path is still `openclaw plugins install @openviking/openclaw-plugin`.
+### Or ask your agent
 
-## Install (Natural Language)
+> Install the OpenClaw plugin @openviking/openclaw-plugin for OpenViking remote memory. My server is at `http://my-server:1933` and my API key is `sk-xxx`.
 
-Ask your agent:
+The agent runs install → setup → restart → verify automatically. See [INSTALL-AGENT.md](./INSTALL-AGENT.md).
 
-> Install the OpenClaw plugin @openviking/openclaw-plugin for OpenViking remote memory. My server is at `http://my-server:1933` and my API key is `sk-xxx`.
+## How It Works
 
-Or in Chinese:
+| Stage | What happens |
+|-------|-------------|
+| **Every turn** (`afterTurn`) | Your messages are archived into an OpenViking session |
+| **On `/compact`** (`compact`) | Archived messages are extracted into long-term memories |
+| **Before each reply** (`assemble`) | Relevant memories are auto-retrieved and injected into context |
 
-> 帮我安装 OpenViking 远程记忆插件 @openviking/openclaw-plugin。我的服务器地址是 `http://my-server:1933`，API key 是 `sk-xxx`。
+## Tools
 
-The agent will automatically run install → setup → restart → verify. No manual steps needed.
+Once installed, the plugin provides these agent tools:
 
-## Install (Command Line)
+| Tool | Purpose |
+|------|---------|
+| `memory_recall` | Explicit long-term memory search |
+| `memory_store` | Persist important information immediately |
+| `memory_forget` | Delete memories by URI or query |
+| `ov_archive_search` | Search across archives by keyword |
+| `ov_archive_expand` | Expand an archive back to raw messages |
+| `add_resource` | Import documents, URLs, or Git repos |
+| `add_skill` | Import agent skills |
+| `memory_search` | Search imported resources and skills |
 
-```bash
-openclaw plugins install @openviking/openclaw-plugin
-openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --json
-openclaw gateway restart
-openclaw openviking status --json
-```
+## Data Flow & Privacy
 
-The `setup` command automatically activates the context-engine slot and validates the server connection.
+- **What is sent**: User/assistant message text from each turn (after stripping injected memory blocks and metadata noise).
+- **Where it goes**: Your configured OpenViking server (`baseUrl`). The plugin only sends data to that server; downstream model/provider data handling (embedding, VLM) depends on the server's configuration.
+- **Storage**: All data lives on your OpenViking server under `viking://user/*`, `viking://agent/*`, and `viking://session/*`.
+- **API Key**: Sent as `X-OpenViking-Key` header over your configured connection. Never logged or forwarded.
+- **Multi-tenant isolation**: Supports `accountId`, `userId`, and `agent_prefix` for per-tenant scoping.
 
-## Search Keywords
+## Verify
 
-@openviking/openclaw-plugin, openclaw openviking plugin, openviking remote memory plugin, OpenViking Context Database plugin, install-openviking-memory.
+```bash
+openclaw openviking status --json     # one-shot health check
+openclaw config get plugins.slots.contextEngine  # should output: openviking
+```
 
 ## Documentation
 
-- Install and upgrade: [INSTALL.md](./INSTALL.md)
-- Chinese design and install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)
-- Agent-oriented operator guide: [INSTALL-AGENT.md](./INSTALL-AGENT.md)
+| Doc | Description |
+|-----|-------------|
+| [INSTALL.md](./INSTALL.md) | Full install, upgrade, and uninstall guide |
+| [INSTALL-ZH.md](./INSTALL-ZH.md) | Chinese install guide |
+| [INSTALL-AGENT.md](./INSTALL-AGENT.md) | Agent-oriented operator guide |
 
----
+> **Plugin vs Skill**: This page is for `@openviking/openclaw-plugin` (the context-engine plugin). Do **not** use `clawhub install openviking` — that installs a different AgentSkill.
 
-## Technical Overview
+---
 
-Use [OpenViking](https://github.com/volcengine/OpenViking) as the long-term memory backend for [OpenClaw](https://github.com/openclaw/openclaw). In OpenClaw, this plugin is registered as the `openviking` context engine.
+<details>
+<summary><b>Technical Overview (for integrators and engineers)</b></summary>
 
-The remainder of this document is an implementation-focused design note for integrators and engineers.
+This plugin is registered as the `openviking` context engine in OpenClaw.
 
 ## Design Positioning
 
@@ -197,13 +216,14 @@ So `afterTurn()` is closer to "incremental append plus threshold-triggered async
 
 ## Tools and Expandability
 
-Beyond automatic behavior, the plugin exposes six tools directly:
+Beyond automatic behavior, the plugin exposes seven tools directly:
 
 - `memory_recall`: explicit long-term memory search
 - `memory_store`: write text into an OpenViking session and trigger commit
 - `memory_forget`: delete by URI, or search first and remove a single strong match
 - `ov_archive_expand`: expand a concrete archive back into raw messages
-- `ov_import`: import a resource or skill; defaults to resource and uses `kind: "skill"` for skills
+- `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource
+- `add_skill`: import or register an OpenViking agent skill
 - `memory_search`: search OpenViking resources and skills, especially after importing them
 
 They serve different roles:
@@ -212,7 +232,8 @@ They serve different roles:
 - `memory_recall` gives the model an explicit follow-up search path
 - `memory_store` is for immediately persisting clearly important information
 - `ov_archive_expand` is the "go back to archive detail" escape hatch when summaries are not enough
-- `ov_import` lets the agent complete explicit import requests without asking the user to remember slash commands
+- `add_resource` lets the agent save explicit document or repository import requests without asking the user to remember slash commands
+- `add_skill` imports skills into OpenViking, while `add_resource` imports resources
 - `memory_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
 
 `ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
@@ -227,8 +248,8 @@ Resource and skill imports are intentionally separate because they land in diffe
 The plugin also registers explicit slash commands for manual imports:
 
 ```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
-/ov-import ./skills/install-openviking-memory --kind skill --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
+/add-skill ./skills/install-openviking-memory --wait
 /memory-search "OpenViking install" --uri viking://resources/openviking-readme
 /memory-search "memory install skill" --uri viking://agent/skills
 ```
@@ -313,3 +334,5 @@ ov tui
 ---
 
 For installation, upgrade, and uninstall operations, use [INSTALL.md](./INSTALL.md).
+
+</details>