Skip to content

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

docs(openclaw): align plugin docs with ClawHub standard install experience (#2150)

LinQiang39187039cac4cc3
diff --git a/docs/en/agent-integrations/03-openclaw.md b/docs/en/agent-integrations/03-openclaw.md
index 3cf4a7261..2209f4447 100644
--- a/docs/en/agent-integrations/03-openclaw.md
+++ b/docs/en/agent-integrations/03-openclaw.md
@@ -11,7 +11,7 @@ Source: [examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree
| Component | Required Version |
| --- | --- |
| Node.js | >= 22 |
-| OpenClaw | >= 2026.3.7 |
+| OpenClaw | >= 2026.4.8 |
The plugin connects to an existing OpenViking server. Make sure you have one reachable over HTTP — see the [Deployment Guide](../guides/03-deployment.md). Quick check:
@@ -27,29 +27,21 @@ openclaw --version
> bash cleanup-memory-openviking.sh
> ```
-## Install via ClawHub (recommended)
+## Install
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
-```
-
-Then run the interactive setup wizard:
-
-```bash
-openclaw openviking setup
-```
-
-The wizard prompts for your remote OpenViking server URL and optional API key, then writes configuration to `$OPENCLAW_STATE_DIR/openclaw.json` (default: `~/.openclaw/openclaw.json`).
-
-Restart the gateway:
-
-```bash
+openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --json
openclaw gateway restart
+openclaw openviking status --json
```
-## Install via `ov-install` (alternative)
+The `setup` wizard writes configuration to `$OPENCLAW_STATE_DIR/openclaw.json` (default: `~/.openclaw/openclaw.json`) and activates the context-engine slot.
+
+<details>
+<summary><b>Alternative: Install via <code>ov-install</code></b></summary>
-The `ov-install` helper automates plugin deployment:
+If ClawHub is unavailable (rate-limited, offline, or auth issues), use the `ov-install` backup path:
```bash
npm install -g openclaw-openviking-setup-helper
@@ -63,28 +55,37 @@ Common variants:
ov-install --workdir ~/.openclaw-second
# Pin to a specific plugin release
-ov-install -y --version 0.2.9
+ov-install --base-url http://your-server:1933 --plugin-version=0.2.9
```
To upgrade later:
```bash
-npm install -g openclaw-openviking-setup-helper@latest && ov-install -y
+npm install -g openclaw-openviking-setup-helper@latest && ov-install --base-url http://your-server:1933
```
### `ov-install` parameters
-| Parameter | Meaning |
-| -------------------------- | ------------------------------------------------------------------ |
-| `--workdir PATH` | Target OpenClaw data directory |
-| `--version VER` | Set plugin version (e.g. `0.2.9` → plugin `v0.2.9`) |
-| `--current-version` | Print the currently installed plugin version |
-| `--plugin-version REF` | Set plugin version — auto-detected: npm version (e.g. `2026.5.8`) or npm dist-tag (e.g. `dev`) resolves via npm; other refs (e.g. `v0.3.16`, `main`) resolve via the GitHub repo; default `npm latest` |
-| `--plugin-source=npm\|github` | Plugin download source (default `npm`) |
-| `--plugin-package=NAME` | npm plugin package name (default `@openviking/openclaw-plugin`) |
-| `--github-repo owner/repo` | Use a different GitHub repo for plugin files (default `volcengine/OpenViking`) |
-| `--update` | Upgrade only the plugin |
-| `-y` | Non-interactive mode, use default values |
+| Parameter | Meaning |
+| ----------------------------- | ------------------------------------------------------------------ |
+| `--workdir PATH` | Target OpenClaw data directory (default `~/.openclaw`) |
+| `--plugin-version=VER` | Plugin version: npm version (e.g. `2026.5.8`), npm dist-tag (e.g. `dev`), or Git ref (e.g. `v0.3.16`, `main`). Default: npm `latest` |
+| `--plugin-source=npm\|github` | Plugin download source (default `npm`) |
+| `--plugin-package=NAME` | npm plugin package name (default `@openviking/openclaw-plugin`) |
+| `--github-repo owner/repo` | Use a different GitHub repo for plugin files (default `volcengine/OpenViking`) |
+| `--current-version` | Print the currently installed plugin version and exit |
+| `--update` | Upgrade only the plugin to the requested `--plugin-version` |
+| `--rollback` | Roll back the last plugin upgrade |
+| `--uninstall` | Uninstall the plugin |
+| `--base-url URL` | OpenViking server URL |
+| `--api-key KEY` | OpenViking API key |
+| `--agent-prefix PREFIX` | Agent prefix for memory namespace isolation |
+| `--account-id ID` | Multi-tenant account ID (root-key deployments only) |
+| `--user-id ID` | Multi-tenant user ID (root-key deployments only) |
+| `--force-slot` | Force-replace the contextEngine slot if another plugin owns it |
+| `--allow-offline` | Save config even if the OpenViking server is unreachable |
+
+</details>
## Plugin configuration
diff --git a/docs/zh/agent-integrations/03-openclaw.md b/docs/zh/agent-integrations/03-openclaw.md
index 2ebab0087..32899d86f 100644
--- a/docs/zh/agent-integrations/03-openclaw.md
+++ b/docs/zh/agent-integrations/03-openclaw.md
@@ -11,7 +11,7 @@
| 组件 | 版本要求 |
| --- | --- |
| Node.js | >= 22 |
-| OpenClaw | >= 2026.3.7 |
+| OpenClaw | >= 2026.4.8 |
插件以远程模式连接到已有的 OpenViking 服务,安装前请确保有可访问的 HTTP 服务——参见 [部署指南](../guides/03-deployment.md)。快速检查:
@@ -27,29 +27,21 @@ openclaw --version
> bash cleanup-memory-openviking.sh
> ```
-## 通过 ClawHub 安装(推荐)
+## 安装
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
-```
-
-随后运行交互式配置向导:
-
-```bash
-openclaw openviking setup
-```
-
-向导会提示填写远程 OpenViking 服务地址和可选的 API Key,并将配置写入 `$OPENCLAW_STATE_DIR/openclaw.json`(默认:`~/.openclaw/openclaw.json`)。
-
-重启 gateway:
-
-```bash
+openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --json
openclaw gateway restart
+openclaw openviking status --json
```
-## 通过 `ov-install` 安装(替代方案)
+`setup` 向导会将配置写入 `$OPENCLAW_STATE_DIR/openclaw.json`(默认:`~/.openclaw/openclaw.json`)并激活 context-engine slot。
+
+<details>
+<summary><b>备用方案:通过 <code>ov-install</code> 安装</b></summary>
-`ov-install` 一键完成插件部署:
+当 ClawHub 不可用(被限流、离线或认证问题)时,可使用 `ov-install` 备用路径:
```bash
npm install -g openclaw-openviking-setup-helper
@@ -63,28 +55,37 @@ ov-install
ov-install --workdir ~/.openclaw-second
# 锁定到某个发布版本
-ov-install -y --version 0.2.9
+ov-install --base-url http://your-server:1933 --plugin-version=0.2.9
```
之后升级:
```bash
-npm install -g openclaw-openviking-setup-helper@latest && ov-install -y
+npm install -g openclaw-openviking-setup-helper@latest && ov-install --base-url http://your-server:1933
```
### `ov-install` 参数
-| 参数 | 含义 |
-| -------------------------- | --------------------------------------------------------------- |
-| `--workdir PATH` | OpenClaw 数据目录 |
-| `--version VER` | 插件版本(如 `0.2.9` → 插件 `v0.2.9`) |
-| `--current-version` | 查看当前已安装的插件版本 |
-| `--plugin-version REF` | 仅指定插件版本,自动识别:npm 版本(如 `2026.5.8`)或 npm dist-tag(如 `dev`)走 npm;其它 ref(如 `v0.3.16`、`main`)走 GitHub 仓库;默认 `npm latest` |
+| 参数 | 含义 |
+| ----------------------------- | --------------------------------------------------------------- |
+| `--workdir PATH` | OpenClaw 数据目录(默认 `~/.openclaw`) |
+| `--plugin-version=VER` | 插件版本:npm 版本(如 `2026.5.8`)、npm dist-tag(如 `dev`)或 Git ref(如 `v0.3.16`、`main`)。默认:npm `latest` |
| `--plugin-source=npm\|github` | 插件下载来源(默认 `npm`) |
-| `--plugin-package=NAME` | npm 插件包名(默认 `@openviking/openclaw-plugin`) |
-| `--github-repo owner/repo` | 指定插件来源仓库,默认 `volcengine/OpenViking` |
-| `--update` | 只升级插件 |
-| `-y` | 非交互模式,使用默认配置 |
+| `--plugin-package=NAME` | npm 插件包名(默认 `@openviking/openclaw-plugin`) |
+| `--github-repo owner/repo` | 指定插件来源仓库(默认 `volcengine/OpenViking`) |
+| `--current-version` | 查看当前已安装的插件版本并退出 |
+| `--update` | 仅升级插件到指定的 `--plugin-version` |
+| `--rollback` | 回滚上次插件升级 |
+| `--uninstall` | 卸载插件 |
+| `--base-url URL` | OpenViking 服务地址 |
+| `--api-key KEY` | OpenViking API Key |
+| `--agent-prefix PREFIX` | Agent 前缀,用于记忆命名空间隔离 |
+| `--account-id ID` | 多租户 Account ID(仅 root-key 部署需要) |
+| `--user-id ID` | 多租户 User ID(仅 root-key 部署需要) |
+| `--force-slot` | 强制替换 contextEngine slot(当其他插件占用时) |
+| `--allow-offline` | 服务不可达时仍保存配置 |
+
+</details>
## 插件配置
diff --git a/examples/openclaw-plugin/.clawhubignore b/examples/openclaw-plugin/.clawhubignore
index 5b5a3bbd0..24f01badb 100644
--- a/examples/openclaw-plugin/.clawhubignore
+++ b/examples/openclaw-plugin/.clawhubignore
@@ -1,7 +1,6 @@
setup-helper/
tests/
__tests__/
-images/
health_check_tools/
upgrade_scripts/
INSTALL*.md
diff --git a/examples/openclaw-plugin/INSTALL-AGENT.md b/examples/openclaw-plugin/INSTALL-AGENT.md
index 399674a82..3e324bfbe 100644
--- a/examples/openclaw-plugin/INSTALL-AGENT.md
+++ b/examples/openclaw-plugin/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.
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md
index 1b491ebf8..c75c88ad2 100644
--- a/examples/openclaw-plugin/INSTALL-ZH.md
+++ b/examples/openclaw-plugin/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
diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.md
index 62c98a0d3..74f2bab58 100644
--- a/examples/openclaw-plugin/INSTALL.md
+++ b/examples/openclaw-plugin/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
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index 762c2c236..9ab31ea4a 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/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
@@ -315,3 +334,5 @@ ov tui
---
For installation, upgrade, and uninstall operations, use [INSTALL.md](./INSTALL.md).
+
+</details>
diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.md
index 2d12260f8..af94d6393 100644
--- a/examples/openclaw-plugin/README_CN.md
+++ b/examples/openclaw-plugin/README_CN.md
@@ -1,55 +1,78 @@
-# @openviking/openclaw-plugin — OpenViking OpenClaw 插件
+# OpenViking for OpenClaw
-OpenClaw 上下文引擎插件,用于接入 OpenViking 远程记忆、上下文数据库、RAG 和语义检索。
+将 [OpenViking](https://github.com/volcengine/OpenViking) 作为 OpenClaw 的长期上下文引擎:自动召回、会话归档、记忆抽取、语义检索和 RAG,连接远程 OpenViking 服务。
-## 重要:插件 vs Skill 区分
+## 快速开始
-本页面是 **OpenClaw 插件包**:
-
-```
-@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
```
-**不要** 使用 `clawhub install openviking` 安装插件——那安装的是 `openviking` AgentSkill(`skills/openviking` 下的技能描述),不是本插件。
+四步完成。`setup` 命令会自动激活 context-engine slot 并验证连接。
-如需 **Agent 辅助安装插件**,让 agent 按 [INSTALL-AGENT.md](./INSTALL-AGENT.md) 执行。主安装方式仍然是 `openclaw plugins install @openviking/openclaw-plugin`。
+### 或者直接让 Agent 安装
-## 安装(自然语言)
+> 帮我安装 OpenViking 远程记忆插件 @openviking/openclaw-plugin。我的服务器地址是 `http://my-server:1933`,API key 是 `sk-xxx`。
-对你的 agent 说:
+Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-AGENT.md](./INSTALL-AGENT.md)。
-> 帮我安装 OpenViking 远程记忆插件 @openviking/openclaw-plugin。我的服务器地址是 `http://my-server:1933`,API key 是 `sk-xxx`。
+## 工作原理
-Agent 会自动完成安装 → 配置 → 重启 → 验证,无需手动操作。
+| 阶段 | 行为 |
+|------|------|
+| **每轮对话后** (`afterTurn`) | 消息自动归档到 OpenViking session |
+| **`/compact` 时** (`compact`) | 归档消息被抽取为长期记忆 |
+| **回复前** (`assemble`) | 自动检索相关记忆并注入上下文 |
-## 安装(命令行)
+## 工具
-```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
-```
+安装后,插件为 Agent 提供以下工具:
+
+| 工具 | 用途 |
+|------|------|
+| `memory_recall` | 显式检索长期记忆 |
+| `memory_store` | 立即持久化重要信息 |
+| `memory_forget` | 按 URI 或查询删除记忆 |
+| `ov_archive_search` | 按关键词搜索历史 archive |
+| `ov_archive_expand` | 展开某个 archive 的原始消息 |
+| `add_resource` | 导入文档、URL 或 Git 仓库 |
+| `add_skill` | 导入 agent 技能 |
+| `memory_search` | 检索已导入的 resources 和 skills |
+
+## 数据流与隐私
-`setup` 命令会自动激活 context-engine slot 并验证服务器连接。
+- **发送内容**:每轮 user/assistant 消息文本(已剥离注入的记忆块和元数据噪音)。
+- **发送去向**:仅发往你配置的 OpenViking 服务(`baseUrl`)。插件本身只与该服务通信;服务端对 embedding、VLM 等模型的调用取决于服务端配置。
+- **存储位置**:所有数据存储在你的 OpenViking 服务上,路径为 `viking://user/*`、`viking://agent/*`、`viking://session/*`。
+- **API Key**:通过 `X-OpenViking-Key` header 发送,不会被日志记录或转发。
+- **多租户隔离**:支持 `accountId`、`userId`、`agent_prefix` 三级租户隔离。
-## 搜索关键词
+## 验证
-@openviking/openclaw-plugin, openclaw openviking 插件, openviking 远程记忆插件, OpenViking 上下文数据库插件, install-openviking-memory
+```bash
+openclaw openviking status --json # 一键健康检查
+openclaw config get plugins.slots.contextEngine # 应输出:openviking
+```
-## 文档入口
+## 文档
-- 安装与升级:[INSTALL-ZH.md](./INSTALL-ZH.md)
-- English install guide: [INSTALL.md](./INSTALL.md)
-- Agent 专用操作文档:[INSTALL-AGENT.md](./INSTALL-AGENT.md)
+| 文档 | 说明 |
+|------|------|
+| [INSTALL-ZH.md](./INSTALL-ZH.md) | 完整安装、升级、卸载指南 |
+| [INSTALL.md](./INSTALL.md) | English install guide |
+| [INSTALL-AGENT.md](./INSTALL-AGENT.md) | Agent 专用操作文档 |
----
+> **插件 vs Skill**:本页面是 `@openviking/openclaw-plugin`(context-engine 插件)。**不要**使用 `clawhub install openviking`——那安装的是另一个 AgentSkill。
-## 技术概述
+---
-使用 [OpenViking](https://github.com/volcengine/OpenViking) 作为 [OpenClaw](https://github.com/openclaw/openclaw) 的长期记忆后端。在 OpenClaw 中,此插件注册为 `openviking` 上下文引擎。
+<details>
+<summary><b>技术细节(面向集成方和工程师)</b></summary>
-以下内容是面向集成方和工程师的实现设计说明。
+在 OpenClaw 中,此插件注册为 `openviking` 上下文引擎。
## 设计定位
@@ -311,3 +334,5 @@ ov tui
---
安装、升级、卸载请查看 [INSTALL-ZH.md](./INSTALL-ZH.md)。
+
+</details>
diff --git a/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md b/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md
index 18840ca72..0bc32c86d 100644
--- a/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md
+++ b/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md
@@ -231,7 +231,7 @@ Tell the user:
Run:
```bash
-openclaw plugins install @openviking/openclaw-plugin
+openclaw plugins install clawhub:@openviking/openclaw-plugin
```
Trigger fallback to Path B only if the output contains any of these strings: