Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(openclaw-plugin): simplify install flow and harden helpers (#1095)
Qin Haojiebfc11a395520
diff --git a/examples/openclaw-plugin/INSTALL-AGENT.md b/examples/openclaw-plugin/INSTALL-AGENT.mdindex 7f89d4eed..39831c932 100644--- a/examples/openclaw-plugin/INSTALL-AGENT.md+++ b/examples/openclaw-plugin/INSTALL-AGENT.md@@ -1,248 +1,244 @@-# OpenViking Memory Plugin — Agent Install Guide+# OpenViking Plugin Agent Install Guide-> For AI Agents (Claude Code, Cursor, etc.) to follow step-by-step.-> Principle: auto-detect what you can; only ask the user when detection fails.+This guide is for AI agents such as Claude Code, Cursor, or similar operator flows. Prefer automation. Ask the user only when detection fails or a choice materially changes the outcome.----+For user-facing installation details, see [INSTALL.md](./INSTALL.md) or [INSTALL-ZH.md](./INSTALL-ZH.md).-## Step 0: Choose Target OpenClaw Instance+## Goal-Check if the user has multiple OpenClaw instances:+Choose the smallest action that matches the user's intent:-```bash-ls -d ~/.openclaw* 2>/dev/null-```--If multiple directories exist (e.g. `~/.openclaw`, `~/.openclaw-openclaw-second`), ask the user which instance to install to. Pass the chosen directory via `--workdir`:--```bash-npx ./examples/openclaw-plugin/setup-helper --workdir ~/.openclaw-openclaw-second-```+| User intent | Command |+| --- | --- |+| Fresh install, latest | `npm install -g openclaw-openviking-setup-helper@latest && ov-install` |+| Upgrade plugin + OpenViking to latest | `npm install -g openclaw-openviking-setup-helper@latest && ov-install -y` |+| Install or upgrade a specific release | `npm install -g openclaw-openviking-setup-helper@latest && ov-install -y --version 0.2.9` |+| Upgrade only the plugin | `ov-install --update` |+| Show installed versions | `ov-install --current-version` |+| Operate on a specific OpenClaw instance | add `--workdir <path>` |-If only `~/.openclaw` exists, proceed with the default.+Default rule: when upgrading, refresh the setup helper first unless the user explicitly asks to pin the helper itself.-## Step 1: Choose Deployment Mode+## Detection Rules-Ask the user: "How do you want to use OpenViking?"+### 1. Detect OpenClaw instance-- **A) Local** — Run OpenViking on this machine (requires Python >= 3.10)-- **B) Remote** — Connect to an existing OpenViking server (only needs the server URL and API Key)+If the user did not specify a workdir, check for multiple OpenClaw instances:-→ A: Go to [Local Deployment Path](#local-deployment-path)-→ B: Go to [Remote Connection Path](#remote-connection-path)-------## Local Deployment Path+```bash+ls -d ~/.openclaw* 2>/dev/null+```-### Step L1: Check Environment+- If only one instance exists, use it.+- If multiple instances exist, ask which instance to operate on, or pass `--workdir`.-Run each check. Every check must pass before continuing.+### 2. Detect environment-**1. Python**+Verify:```bashpython3 --version+node -v+openclaw --version```-- Pass: >= 3.10-- Fail: Tell user "Python >= 3.10 is required. Install from https://www.python.org/downloads/"-- Multiple versions: Ask user which Python path to use+Requirements:-**2. Node.js**+- Python >= 3.10+- Node.js >= 22+- OpenClaw >= 2026.3.7++If OpenClaw is missing, tell the user to run:```bash-node -v+npm install -g openclaw && openclaw onboard```-- Pass: >= v22-- Fail: Tell user "Node.js >= 22 is required. Install from https://nodejs.org/"+### 3. Detect existing install state-**3. OpenClaw**+Use:```bash-openclaw --version+ov-install --current-version```-- Pass: Version output present-- Fail: Tell user to run `npm install -g openclaw && openclaw onboard`+This reports:-### Step L2: Install OpenViking+- installed plugin release+- requested plugin ref+- installed OpenViking version+- installation time-```bash-python3 -m pip install openviking --upgrade-```+## Standard Workflows-- Pass: Continue-- Fail with `externally-managed`:- ```bash- python3 -m venv ~/.openviking/venv- ~/.openviking/venv/bin/pip install openviking --upgrade- ```- Set `OPENVIKING_PYTHON=~/.openviking/venv/bin/python` for later steps-- Fail with `No matching distribution`: Python is below 3.10, tell user to upgrade-- Other failure: Print full error, ask user+### Latest Install-Verify:+Use for fresh installs:```bash-python3 -c "import openviking; print('ok')"+npm install -g openclaw-openviking-setup-helper@latest+ov-install```-### Step L3: Configure+Notes:++- `ov-install` is interactive on first install.+- In local mode, it generates `~/.openviking/ov.conf` and `~/.openclaw/openviking.env`.+- In remote mode, it stores remote connection settings in `plugins.entries.openviking.config`.-Check if `~/.openviking/ov.conf` already exists:+### Latest Upgrade-- **Exists**: Ask user "Found existing config at ~/.openviking/ov.conf. Keep it?"- - Yes: Skip to Step L4- - No: Continue with configuration below+Use when the user wants both the plugin and OpenViking runtime upgraded:++```bash+npm install -g openclaw-openviking-setup-helper@latest+ov-install -y+```-- **Does not exist**: Collect configuration+Current behavior:-**Ask user for API Key:**+- plugin version defaults to the latest repo tag+- OpenViking runtime is upgraded through pip during install+- `-y` runs the non-interactive path; verify the resulting plugin config after upgrade if the target instance has custom settings-> "Please provide your Volcengine Ark API Key (used for Embedding and VLM model calls).-> Get one at https://console.volcengine.com/ark if you don't have one."+### Release-Pinned Install or Upgrade-Run the setup helper:+Use when the user names a release such as `0.2.9`:```bash-npm install -g openclaw-openviking-setup-helper-ov-install+npm install -g openclaw-openviking-setup-helper@latest+ov-install -y --version 0.2.9```-At the interactive prompts:-- Workspace: Press Enter for default path-- API Key: Enter the user's key-- VLM model: Press Enter for default `doubao-seed-2-0-pro-260215`-- Embedding model: Press Enter for default `doubao-embedding-vision-251215`-- Ports: Press Enter for default 1933/1833+This is shorthand for:++- plugin version `v0.2.9`+- OpenViking version `0.2.9`-Wait for `Setup complete!`+### Plugin-Only Upgrade-### Step L4: Start and Verify+Use only when the user explicitly wants to keep the current OpenViking runtime version unchanged:```bash-source ~/.openclaw/openviking.env && openclaw gateway+ov-install --update```-- Pass: Output contains `openviking: local server started`-- Fail with `port occupied`:- The port is used by another process. Change port:- ```bash- openclaw config set plugins.entries.openviking.config.port 1934- source ~/.openclaw/openviking.env && openclaw gateway- ```-- Fail with `subprocess exited`: Check stderr for Python errors — usually wrong API Key or openviking not installed properly+Do not combine `--update` with `--version` or `--openviking-version`.-Verify:+### Legacy Plugin Cleanup++If the machine previously used `memory-openviking`, run the bundled cleanup script from this repository:```bash-openclaw status+bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh```-ContextEngine line should show `enabled (plugin openviking)`.+Then continue with install or upgrade.-Tell user: "OpenViking memory is active. I'll automatically remember important facts from our conversations and recall them when relevant."+## Verification----+### Check plugin slot-## Remote Connection Path+```bash+openclaw config get plugins.slots.contextEngine+```-### Step R1: Collect Connection Info+Expected output:-Ask user for:+```text+openviking+```-1. **OpenViking server URL** (e.g. `http://10.0.0.1:1933`)- > This is the OpenViking HTTP API address.+### Check plugin config-2. **OpenViking API Key** (optional)- > Required if the server has `root_api_key` configured. This authenticates to the OpenViking server — it is NOT a Volcengine Ark API Key.+```bash+openclaw config get plugins.entries.openviking.config+```-### Step R2: Check Environment+### Check logs-**1. Node.js**+OpenClaw log:```bash-node -v+openclaw logs --follow```-- Pass: >= v22-- Fail: Tell user to install Node.js >= 22+Look for:-**2. OpenClaw**+```text+openviking: registered context-engine+```++OpenViking service log, default local path:```bash-openclaw --version+cat ~/.openviking/data/log/openviking.log```-- Pass: Version output present-- Fail: `npm install -g openclaw && openclaw onboard`+### Start commands-> Remote mode does **not** require Python — OpenViking runs on the remote server.--### Step R3: Install Plugin and Configure+Local mode:```bash-npm install -g openclaw-openviking-setup-helper-ov-install-# Select remote mode, enter OpenViking server URL and API Key+source ~/.openclaw/openviking.env && openclaw gateway restart```-Alternatively, configure manually (substitute user-provided values). If targeting a non-default instance, prefix each command with `OPENCLAW_STATE_DIR=<workdir>`:+Remote mode:```bash-openclaw config set plugins.enabled true --json-openclaw config set plugins.slots.contextEngine openviking-openclaw config set plugins.entries.openviking.config.mode remote-openclaw config set plugins.entries.openviking.config.baseUrl "<user's server URL>"-openclaw config set plugins.entries.openviking.config.apiKey "<user's API Key>"-openclaw config set plugins.entries.openviking.config.autoRecall true --json-openclaw config set plugins.entries.openviking.config.autoCapture true --json+openclaw gateway restart```-If user has no API Key (server auth not enabled), skip the apiKey line.+## Plugin Config Reference-### Step R4: Start and Verify+### Local Mode++Check the whole config first:```bash-openclaw gateway+openclaw config get plugins.entries.openviking.config```-- Pass: Output contains `openviking: initialized`-- Fail with connection error: Verify server is reachable — `curl <baseUrl>/health` should return `{"status":"ok"}`+Core OpenClaw plugin fields:++- `mode=local`+- `configPath`+- `port`+- `agentId`++Service-side model configuration is not stored in the OpenClaw plugin config. It lives in `~/.openviking/ov.conf`, especially:++- `vlm.api_key`+- `vlm.model`+- `embedding.dense.api_key`+- `embedding.dense.model`+- `server.port`++### Remote Mode++Check the whole config first:```bash-openclaw status+openclaw config get plugins.entries.openviking.config```-ContextEngine line should show `enabled (plugin openviking)`.--Tell user: "OpenViking memory is connected to the remote server. I'll automatically remember important facts and recall them when relevant."+Core OpenClaw plugin fields:----+- `mode=remote`+- `baseUrl`+- `apiKey`+- `agentId`-## Field Reference+## Uninstall-| Field | Meaning | Required For |-|-------|---------|-------------|-| Volcengine Ark API Key | Embedding + VLM model access | Local |-| OpenViking API Key | Server authentication key | Remote (if server has auth enabled) |-| agentId | Identifies this agent to OpenViking | Both (auto-generated if not set) |-| baseUrl | OpenViking HTTP address | Remote |-| workspace | Data storage directory | Local |-| server port | OpenViking HTTP port (default 1933) | Local |-| VLM model | Memory extraction model | Local |-| Embedding model | Text vectorization model | Local |+Plugin only:----+```bash+bash examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh+```-## Troubleshooting+Plugin + local OpenViking runtime:-| Error | Cause | Fix |-|-------|-------|-----|-| `port occupied` | Port used by another process | Change port in config, e.g. `openclaw config set plugins.entries.openviking.config.port 1934` |-| `extracted 0 memories` | Wrong API Key or model name | Check `api_key` and `model` in `~/.openviking/ov.conf` |-| `externally-managed-environment` | Python PEP 668 restriction | Install via venv |-| `ECONNREFUSED` | Remote server unreachable | Verify baseUrl and network connectivity |-| Plugin not loaded | Env file not sourced | `source ~/.openclaw/openviking.env` (local mode) |+```bash+python3 -m pip uninstall openviking -y && rm -rf ~/.openviking+```diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.mdindex 53aa99329..7a3282560 100644--- a/examples/openclaw-plugin/INSTALL-ZH.md+++ b/examples/openclaw-plugin/INSTALL-ZH.md@@ -1,562 +1,202 @@# 为 OpenClaw 安装 OpenViking 记忆功能-通过 [OpenViking](https://github.com/volcengine/OpenViking) 为 [OpenClaw](https://github.com/openclaw/openclaw) 提供长效记忆能力。安装完成后,OpenClaw 将自动**记住**对话中的重要信息,并在回复前**回忆**相关内容。OpenViking 最新版本发布了 [WebConsole](https://github.com/volcengine/OpenViking/tree/main/openviking/console),方便调试和运维。文档方式三也提供了如何在 WebConsole 界面验证记忆写入的说明,欢迎试用和反馈。+通过 [OpenViking](https://github.com/volcengine/OpenViking) 为 [OpenClaw](https://github.com/openclaw/openclaw) 提供长效记忆能力。安装完成后,OpenClaw 会自动记住对话中的重要信息,并在回复前回忆相关内容。-> **ℹ️ 历史兼容性说明**->-> 旧版 OpenViking/OpenClaw 集成方案在 OpenClaw `2026.3.12` 附近曾出现过已知兼容性问题,表现为加载插件后对话卡死无响应。-> 该问题主要影响旧版本插件链路;当前文档介绍的 context-engine 插件 2.0 已不再受此问题影响,新的安装流程无需因此回退 OpenClaw。-> 同时,插件 2.0 与旧版 `memory-openviking` 插件及其配置不兼容,升级时需要按本文迁移步骤完成替换,不能混装。-> 插件 2.0 也依赖 OpenClaw 的 context-engine 能力,不支持旧版 OpenClaw;请升级到当前安装助手支持的较新 OpenClaw 版本后再安装。-> 如需排查旧版本部署,可参考 [#591](https://github.com/volcengine/OpenViking/issues/591) 以及上游修复 PR:openclaw/openclaw#34673、openclaw/openclaw#33547。+> 当前文档介绍的是基于 `context-engine` 架构的新版 OpenViking 插件。-> **🚀 插件 2.0(context-engine 架构)**->-> 当前文档介绍的是基于 context-engine 架构的 OpenViking 插件 2.0 方案,也是 OpenViking 接入 AI 编程助手的推荐实践。-> 更多背景和演进讨论可见:https://github.com/volcengine/OpenViking/discussions/525-------## 一键安装--该安装方式支持您从 安装 - 验证 - 读取 - 写入 - 查看 一站式了解OpenViking。--**前置条件:** Python >= 3.10,Node.js >= 22。安装助手会自动检查并提示安装缺少的组件。--### 从旧版 `memory-openviking` 升级到新版 `openviking` 前置操作步骤--- 如果当前环境里已经安装过旧版插件 `memory-openviking`,建议先完成以下前置操作,再执行新版安装。+## 前置条件-- 如果您之前没有安装过,可以跳过此步骤,直接查看 **“正式安装”** 环节。+| 组件 | 版本要求 |+| --- | --- |+| Python | >= 3.10 |+| Node.js | >= 22 |+| OpenClaw | >= 2026.3.7 |-- 插件 2.0 与旧版插件/旧版配置不兼容,需避免旧版和新版插件同时存在。+快速检查:-#### 方式 A:下载并执行旧版插件清理脚本 (推荐)```bash-curl -O https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh-bash cleanup-memory-openviking.sh+python3 --version+node -v+openclaw --version```-#### 方式 B:手动执行命令清理旧版本插件配置-1. 停止 OpenClaw gateway:+## 旧版升级说明-```bash-openclaw gateway stop-```+如果你之前安装过旧版 `memory-openviking`,先清理旧插件,再执行下面的安装或升级命令。-2. 备份旧版本配置和插件目录:+- 新版 `openviking` 与旧版 `memory-openviking` 不兼容,不能混装。+- 如果你从未安装过旧版插件,可以跳过本节。```bash-cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-openviking-upgrade.bak-mkdir -p ~/.openclaw/disabled-extensions-mv ~/.openclaw/extensions/memory-openviking ~/.openclaw/disabled-extensions/memory-openviking-upgrade-backup+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh+bash cleanup-memory-openviking.sh```-3. 修改 OpenClaw 配置,移除旧版本配置参数:--编辑 `~/.openclaw/openclaw.json`,删除 `plugins.allow` 中的 `"memory-openviking"`,删除 `plugins.entries.memory-openviking`,并将 `plugins.slots.memory` 改为 `"none"`,将 `plugins.load.paths`中旧版本 `memory-openviking` 插件路径修改为`openviking`。--按照上述方式清理完成旧版插件配置后,参考下面安装方式A或者安装方式B的操作步骤,安装新版插件;--保留并迁移旧版本运行参数到新版本配置(新版本默认可用,旧版本参数按需迁移):--如果旧版本原来使用的是 `plugins.entries.memory-openviking.config`,请将第二步备份的openclaw配置文件中的 `mode`、`configPath`、`port`、`baseUrl`、`apiKey`、`agentId` 等参数按需迁移到新版 `plugins.entries.openviking.config`。+## 安装-前置步骤根据您的个人情况按需执行,完成以后,即可进入2.0的安装环节,在此我们暂时不建议直接自然语言安装,推荐使用 npm 一键安装。--### 正式安装--#### 方式 A:npm 安装(推荐,含 Windows)--**Windows** 与 macOS / Linux 相同:在 **PowerShell** 或 **cmd** 中执行下面的 `npm`、`npx`、`ov-install` 即可(需已安装 Node.js ≥ 22)。指定其它 OpenClaw 数据目录时,把 `--workdir` 换成本机路径(例如 `%USERPROFILE%\.openclaw-second`)。+推荐使用 `npm` + `ov-install`。macOS、Linux、Windows 的流程相同。```bashnpm install -g openclaw-openviking-setup-helper-ov-install-```-非交互模式(使用默认配置):--```bash-ov-install -y-```--安装到指定 OpenClaw 实例:+# 安装插件+ov-install-```bash+# 安装插件到指定 OpenClaw 实例ov-install --workdir ~/.openclaw-second```-#### 指定版本(npm / `ov-install`)+## 升级-npm 上的安装助手包名为 [`openclaw-openviking-setup-helper`](https://www.npmjs.com/package/openclaw-openviking-setup-helper)。默认安装最新版;若需固定 **npm 上某一发布版本**,在包名后追加 `@VERSION`(VERSION 为 npm 上可见的 dist-tag 或版本号):+要把 OpenViking 和插件一起升级到最新版本,执行:```bash-npm install -g openclaw-openviking-setup-helper-ov-install -y+npm install -g openclaw-openviking-setup-helper@latest && ov-install -y```-不全局安装、用 npx 直接跑(同样可在包名后加 `@VERSION` 固定安装助手版本):+## 安装或升级到指定版本++如果要安装或升级到某个正式发布版本,执行:```bash-npx -y -p openclaw-openviking-setup-helper ov-install -y+ov-install -y --version 0.2.9```-使用 **`ov-install`** 可指定 **插件代码对应的 Git 引用** 以及 **PyPI 上的 OpenViking 版本**:+## 参数说明| 参数 | 含义 || --- | --- |-| `--github-repo owner/repo` | 从哪个 GitHub 仓库拉取插件文件(默认:`volcengine/OpenViking`) |-| `--plugin-version REF` | 分支、tag 或 commit,用于拉取插件(默认:`volcengine/OpenViking` 仓库中的最新 tag) |-| `--openviking-version VER` | 固定为 `pip install openviking==VER`(不写则安装 PyPI 最新版) |--示例:--```bash-# 安装指定 tag 版本的插件(例如 v0.2.9)-ov-install -y --plugin-version v0.2.9--# 固定 PyPI 上的 OpenViking 版本,插件默认仍跟随仓库最新 tag-ov-install -y --openviking-version 0.2.9--# 同时指定插件 tag 和 OpenViking PyPI 版本-ov-install -y --plugin-version v0.2.9 --openviking-version 0.2.9--# 安装旧版插件链路(如需使用旧插件,请在 v0.2.3-v0.2.6 范围内选择版本)-ov-install -y --plugin-version <legacy-version>-```--等价环境变量:`REPO`(同 `--github-repo`)、`PLUGIN_VERSION` / `BRANCH`、`OPENVIKING_VERSION`。--#### 升级与回滚(`ov-install`)--使用 `--update` / `--upgrade-plugin` 时,只会升级**插件本身**到指定 `--plugin-version`,不会升级 OpenViking 服务版本。该模式会:--- 保留现有的 OpenViking 服务版本-- 保留现有的 `~/.openviking/ov.conf`-- 保留当前插件运行配置-- 本地模式下保留 `configPath` 和 `port`-- 远端模式下保留 `baseUrl`、`apiKey`、`agentId`-- 只清理 `openclaw.json` 中 OpenViking 自己的插件配置,不影响其它插件-- 在替换插件前备份 `openclaw.json` 和上一版插件目录-- 在命令输出中记录升级路径和回滚审计文件位置--不要把 `--update` 和 `--openviking-version` 一起使用;如果需要修改 OpenViking 服务版本,请走完整安装流程。--```bash-# 只升级插件到指定 tag-ov-install --update --plugin-version v0.2.9+| `--workdir PATH` | 指定 OpenClaw 数据目录 |+| `--version VER` | 同时指定插件版本和 OpenViking 版本,例如 `0.2.9` 会对应插件 `v0.2.9` |+| `--current-version` | 查看当前已安装的插件版本和 OpenViking 版本 |+| `--plugin-version REF` | 指定插件版本,支持 tag、分支或 commit |+| `--openviking-version VER` | 指定 PyPI 上的 OpenViking 版本 |+| `--github-repo owner/repo` | 指定插件来源仓库,默认 `volcengine/OpenViking` |+| `--update` | 只升级插件,不升级 OpenViking 服务版本 |+| `-y` | 非交互模式,使用默认配置 |-# 只升级插件到指定分支-ov-install --update --plugin-version dev-branch+## OpenClaw 插件参数说明-# 从指定 GitHub 仓库 + 分支升级插件-ov-install --update --github-repo yourname/OpenViking --plugin-version dev-branch+插件配置写在 `plugins.entries.openviking.config` 下。通常安装助手会自动写好,只有在你需要手动调整时,才需要关注下面这些参数。-# 回滚最近一次插件升级-ov-install --rollback-```--升级备份默认保存在:--- `~/.openclaw/.openviking-upgrade-backup/openclaw.json.bak`-- `~/.openclaw/.openviking-upgrade-backup/last-upgrade.json`-- `~/.openclaw/disabled-extensions/<pluginId>-upgrade-backup-*`--`--rollback` 会恢复最近一次 `--update` 生成的 `openclaw.json` 备份和插件目录备份。--**Windows:** 升级与回滚命令与上表相同,在 PowerShell / cmd 中执行即可。--备注:在运行 `npm install -g openclaw-openviking-setup-helper` 命令时,可能会出现没有安装创建虚拟环境的工具的报错提示,可以直接复制报错提示中的解决方案执行:--```bash-apt update-apt install -y software-properties-common-add-apt-repository universe-apt update-apt install -y python3-venv-```-运行完上面这几行命令后,再次执行你的安装命令:--```bash-ov-install-```--这次脚本就能成功创建一个隔离的虚拟环境,并顺利把 OpenViking 安装进去了,而且不会破坏你的系统环境。--出现`installation completed`即代表安装成功。--#### 方式 B(可选):curl 一键安装(Linux / macOS)--**Windows** 请优先使用上文 **方式 A(`npm` / `ov-install`)**。`curl | bash` 需要 Bash 环境;若已在 **Git Bash** 或 **WSL** 中操作,可执行本节命令。+查看当前插件整体配置:```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash+openclaw config get plugins.entries.openviking.config```-非交互模式:+### Local 模式-```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- -y-```--安装到指定 OpenClaw 实例:+适用于由 OpenClaw 插件在本机拉起 OpenViking 服务的场景。-```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- --workdir ~/.openclaw-second -y-```+| 参数 | 默认值 | 含义 |+| --- | --- | --- |+| `mode` | `local` | `local` 表示由插件拉起本机 OpenViking;`remote` 表示连接已有远端 OpenViking 服务 |+| `agentId` | `default` | 当前 OpenClaw 实例在 OpenViking 侧使用的标识 |+| `configPath` | `~/.openviking/ov.conf` | 本机 OpenViking 配置文件路径 |+| `port` | `1933` | 本机 OpenViking HTTP 端口 |-#### 指定版本(`install.sh`)+`local` 模式下,VLM、Embedding、API Key 等服务端配置写在 `~/.openviking/ov.conf`,不写在 OpenClaw 插件参数里。常见项包括:-| 参数 / 环境变量 | 含义 |+| 配置项 | 含义 || --- | --- |-| `--repo owner/repo`、`REPO` | 从哪个 GitHub 仓库拉取插件文件(默认:`volcengine/OpenViking`) |-| `--plugin-version REF`、`PLUGIN_VERSION` | 分支、tag 或 commit(默认:最新 tag;兼容旧变量 `BRANCH`) |-| `--openviking-version VER`、`OPENVIKING_VERSION` | `pip install openviking==VER`(不写则安装 PyPI 最新版) |+| `vlm.api_key` / `vlm.model` / `vlm.api_base` | 记忆抽取使用的 VLM 模型配置 |+| `embedding.dense.api_key` / `embedding.dense.model` / `embedding.dense.api_base` | 向量化使用的 Embedding 模型配置 |+| `server.port` | OpenViking 服务监听端口 |-示例:+常见设置:```bash-# 安装指定 tag 版本的插件(例如 v0.2.9)-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --plugin-version v0.2.9 -y--# 固定 PyPI 上的 OpenViking 版本-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --openviking-version 0.2.9 -y--# 同时指定插件 tag 和 OpenViking PyPI 版本-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --plugin-version v0.2.9 --openviking-version 0.2.9 -y+openclaw config set plugins.entries.openviking.config.mode local+openclaw config set plugins.entries.openviking.config.configPath ~/.openviking/ov.conf+openclaw config set plugins.entries.openviking.config.port 1933```-#### 升级与回滚(`install.sh`)--`curl | bash` 入口现在直接由 `install.sh` 原生执行升级和回滚逻辑,不依赖机器上预先安装全局安装助手,也支持“只升级插件”和“回滚最近一次插件升级”:+### Remote 模式-```bash-# 只升级插件到指定 tag-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --update --plugin-version v0.2.9+适用于连接已有远端 OpenViking 服务的场景。-# 只升级插件到指定分支-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --update --plugin-version dev-branch+| 参数 | 默认值 | 含义 |+| --- | --- | --- |+| `mode` | `remote` | 使用已有远端 OpenViking 服务 |+| `baseUrl` | `http://127.0.0.1:1933` | 远端 OpenViking 服务地址 |+| `apiKey` | 空 | 远端 OpenViking API Key;服务端未开启认证时可不填 |+| `agentId` | `default` | 当前 OpenClaw 实例在远端 OpenViking 上的标识 |-# 从指定 GitHub 仓库 + 分支升级插件-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --update --repo yourname/OpenViking --plugin-version dev-branch+常见设置:-# 回滚最近一次插件升级-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --rollback+```bash+openclaw config set plugins.entries.openviking.config.mode remote+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.apiKey your-api-key+openclaw config set plugins.entries.openviking.config.agentId your-agent-id```-`--update` 模式只改插件,不改 OpenViking 服务版本,因此不要搭配 `--openviking-version`。+## 启动-Shell 原生升级行为:--- 保留当前 local / remote 模式下的插件配置-- 不会重写 `~/.openviking/ov.conf`-- 会把 `openclaw.json` 备份到 `~/.openclaw/.openviking-upgrade-backup/openclaw.json.bak`-- 会把回滚审计写到 `~/.openclaw/.openviking-upgrade-backup/last-upgrade.json`-- 每个插件只保留一份最新的目录备份,位置在 `~/.openclaw/disabled-extensions/`-- 升级成功后会打印 `Upgrade path: <from> -> <to>`--`install.sh` 会检测本机多个 OpenClaw 实例并供选择;首次安装会询问 local/remote;仅升级插件时会复用现有模式与配置。--### 启动OpenClaw + OpenViking--安装成功以后,运行以下命令启动 OpenClaw + OpenViking+安装完成后,运行:```bashsource ~/.openclaw/openviking.env && openclaw gateway restart```-Windows PowerShell 可使用:+Windows PowerShell:```powershell. "$HOME/.openclaw/openviking.env.ps1"openclaw gateway restart```-出现 `openviking: registered context-engine` 代表拉取成功。--接着,执行--```bash-openclaw config get plugins.slots.contextEngine-```--出现 `openviking`,则验证启动成功。--### 验证读取和写入--现在可以自由和 OpenClaw 进行交互和对话,过程中,你可以通过以下命令查看 OpenViking 运行状态,验证读取和写入:--验证读取:`cat 填入您的日志文件路径(如:/tmp/openclaw/openclaw-2026-03-20.log) |grep auto-capture`--验证写入:`cat 填入您的日志文件路径(如:/tmp/openclaw/openclaw-2026-03-20.log) |grep inject`--OpenClaw日志查看:`openclaw logs --follow`,出现 `openviking: auto-captured 2 new messages, extracted 1 memories` 说明状态正常--### 通过 ov tui 查看您的记忆文件--我们提供了命令行查看 OpenViking 中虚拟文件的方式,首先 `cd` 到您的 OpenViking 目录,`source venv/bin/activate`激活虚拟环境--输入 `ov --help`了解 OpenViking 具体命令,输入 `ov tui`即可进入文件界面,按`.`可打开文件夹,支持方向键上下查看文件,按`q`退出。-------## 前置条件--| 组件 | 版本要求 | 用途 |-|------|----------|------|-| **Python** | >= 3.10 | OpenViking 运行时 |-| **Node.js** | >= 22 | OpenClaw 运行时 |-| **火山引擎 Ark API Key** | — | Embedding + VLM 模型调用 |--快速检查:--```bash-python3 --version # >= 3.10-node -v # >= v22-openclaw --version # 已安装-```--- Python: https://www.python.org/downloads/-- Node.js: https://nodejs.org/-- OpenClaw: `npm install -g openclaw && openclaw onboard`-------## 方式一:本地部署(推荐)--在本机启动 OpenViking 服务,适合个人使用。--### Step 1: 安装 OpenViking--```bash-python3 -m pip install openviking --upgrade-```--验证:`python3 -c "import openviking; print('ok')"`--> 遇到 `externally-managed-environment`?使用一键安装脚本(自动处理 venv)或手动创建:-> `python3 -m venv ~/.openviking/venv && ~/.openviking/venv/bin/pip install openviking`--### Step 2: 运行安装助手--```bash-# 方式 A:npm 安装(推荐,全平台)-npm install -g openclaw-openviking-setup-helper-ov-install--# 方式 B:curl 一键安装(Linux / macOS)-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash-```--安装助手会提示输入 Ark API Key 并自动生成配置文件。--### Step 3: 启动--```bash-source ~/.openclaw/openviking.env && openclaw gateway-```--看到 `openviking: local server started` 表示成功。--### Step 4: 验证--```bash-openclaw status-# Memory 行应显示:enabled (plugin openviking)-```-------## 方式二:连接远端 OpenViking--已有运行中的 OpenViking 服务?只需配置 OpenClaw 插件指向远端,**不需要安装 Python / OpenViking**。--**前置:** 已有 OpenViking 服务地址 + API Key(如服务端启用了认证)。--### Step 1: 安装插件--```bash-npm install -g openclaw-openviking-setup-helper-ov-install-# 选择 remote 模式,填入 OpenViking 服务地址和 API Key-```-### Step 2: 启动并验证+## 验证-```bash-openclaw gateway restart-openclaw status-```--<details>-<summary>手动配置(不使用安装助手)</summary>+检查插件是否已接管 `contextEngine`:```bash-openclaw config set plugins.enabled true --json-openclaw config set plugins.slots.contextEngine openviking-openclaw config set plugins.entries.openviking.config.mode remote-openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"-openclaw config set plugins.entries.openviking.config.apiKey "your-api-key"-openclaw config set plugins.entries.openviking.config.agentId "your-agent-id"-openclaw config set plugins.entries.openviking.config.autoRecall true --json-openclaw config set plugins.entries.openviking.config.autoCapture true --json+openclaw config get plugins.slots.contextEngine```-</details>--## 方式三 火山引擎 ECS 版 Openclaw 接入 OpenViking+输出 `openviking` 即表示插件已生效。-本部分主要介绍如何在火山引擎ECS上接入OpenViking,并使用WebConsole验证写入。详情可见[文档](https://www.volcengine.com/docs/6396/2249500?lang=zh)。--需注意 ECS 实例为了保护系统 Python 不被弄坏,在根目录(root)部署会有限制,不能直接用 pip 装全局包,推荐先创建虚拟环境,在虚拟环境下完成以下操作步骤。--**前置:** 已有 ECS OpenClaw实例。--### Step 1: npm 安装--```python-npm install -g openclaw-openviking-setup-helper-ov-install-```-本安装模式已经在OpenViking内置了vlm和embedding模型,若不需要修改,直接按回车,按照指引填入API key即可. 安装完成后,会自动生成配置文件,如需修改,输入 vim ~/.openviking/ov.conf,按 i 进入编辑模式,按 esc 键退出编辑模式,输入 :wq 按回车键,保存并退出文件。--终端加载 OpenClaw 环境变量:+查看运行日志:```bash-source /root/.openclaw/openviking.env-```-### Step 2: 启动OpenViking--先启动 OpenViking Server:--```python-python -m openviking.server.bootstrap+openclaw logs --follow```-然后启动 web 控制台,启动之前,需要确认本实例安全组是否已经在入向规则处开放 TCP 8020 端口,若没有,需先点击实例安全组配置:-```python-python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933-```-在实例中,找到你的服务器公网IP,用你的服务器公网IP访问: http://你的服务器公网IP:8020--即可开始体验 web console 🎉+日志中出现 `openviking: registered context-engine`,表示插件已成功加载。-你可以直接在web界面查询文件信息,验证OpenViking memory-plugin记忆写入是否生效;也可以可以在OpenClaw日志中验证openviking是否读取记忆,验证方式:+查看 OpenViking 自身日志:+默认日志文件在你的 `workspace/data/log/openviking.log`。如果使用默认配置,通常对应:```bash-grep -i inject /tmp/openclaw/openclaw-2026-03-13.log | awk -F'"' '{for(i=1;i<=NF;i++) if($i ~ /^[0-9]{2}:[0-9]{2}:[0-9]{2}/) {time=$i; break}} /injecting [0-9]+ memories/ {print time, "openviking:", gensub(/.*(injecting [0-9]+ memories).*/, "\\1", "1")}'-```--也可以直接运行grep "inject" /tmp/openclaw/openclaw-2026-03-13.log查看全部信息。--------## 配置参考--### `~/.openviking/ov.conf`(本地模式)--```json-{- "root_api_key": null,- "server": { "host": "127.0.0.1", "port": 1933 },- "storage": {- "workspace": "/home/yourname/.openviking/data",- "vectordb": { "backend": "local" },- "agfs": { "backend": "local", "port": 1833 }- },- "embedding": {- "dense": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-embedding-vision-251215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "dimension": 1024,- "input": "multimodal"- }- },- "vlm": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-seed-2-0-pro-260215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3"- }-}+cat ~/.openviking/data/log/openviking.log```-> `root_api_key`:设置后,所有 HTTP 请求须携带 `X-API-Key` 头。本地模式默认为 `null`(不启用认证)。--### `agentId` 配置(插件配置)--通过 `X-OpenViking-Agent` header 传给服务端的 Agent 标识,用于区分不同的 OpenClaw 实例。--自定义方式:+查看当前已安装版本:```bash-# 在插件配置中指定-openclaw config set plugins.entries.openviking.config.agentId "my-agent"+ov-install --current-version```-如果未配置,插件会自动生成一个随机唯一的 ID(格式:`openclaw-<hostname>-<random>`)。--### `~/.openclaw/openviking.env`+## 卸载-由安装器自动生成,记录 Python 路径等环境变量:+只卸载 OpenClaw 插件、保留 OpenViking 运行时:```bash-export OPENVIKING_PYTHON='/usr/local/bin/python3'+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh -o uninstall-openviking.sh+bash uninstall-openviking.sh```-在 Windows PowerShell 下,安装器会生成 `~/.openclaw/openviking.env.ps1`。-------## 日常使用+如果你的 OpenClaw 数据目录不是默认路径:```bash-# 启动-source ~/.openclaw/openviking.env && openclaw gateway--# 检查当前 context-engine-openclaw status-openclaw config get plugins.slots.contextEngine--# 关闭记忆-openclaw config set plugins.slots.contextEngine legacy--# 开启记忆-openclaw config set plugins.slots.contextEngine openviking+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh -o uninstall-openviking.sh+bash uninstall-openviking.sh --workdir ~/.openclaw-second```------## 常见问题--| 症状 | 原因 | 修复 |-|------|------|------|-| `port occupied` | 端口被其他进程占用 | 换端口:`openclaw config set plugins.entries.openviking.config.port 1934` |-| `extracted 0 memories` | API Key 或模型名配置错误 | 检查 `ov.conf` 中 `api_key` 和 `model` 字段 |-| 插件未加载 | 未加载环境变量 | 启动前执行 `source ~/.openclaw/openviking.env` |-| `externally-managed-environment` | Python PEP 668 限制 | 使用 venv 或一键安装脚本 |-| `TypeError: unsupported operand type(s) for \|` | Python < 3.10 | 升级 Python 至 3.10+ |-------## 卸载+如果还要一并删除本机 OpenViking 运行时和数据,再执行:```bash-lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9python3 -m pip uninstall openviking -y && rm -rf ~/.openviking```-------**另见:** [INSTALL.md](./INSTALL.md)(English) · [INSTALL-AGENT.md](./INSTALL-AGENT.md)(Agent Install Guide)diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.mdindex c652492a1..9f87d8228 100644--- a/examples/openclaw-plugin/INSTALL.md+++ b/examples/openclaw-plugin/INSTALL.md@@ -1,595 +1,213 @@# Installing OpenViking for OpenClaw-Provide long-term memory capabilities for [OpenClaw](https://github.com/openclaw/openclaw) via [OpenViking](https://github.com/volcengine/OpenViking). After installing, OpenClaw will automatically **remember** important information from conversations and **recall** relevant content before replying. The latest version of OpenViking includes a [WebConsole](https://github.com/volcengine/OpenViking/tree/main/openviking/console) for debugging and operations. Method 3 in this document also provides instructions on how to verify that memories are written via the WebConsole interface. We welcome you to try it out and provide feedback.--> **ℹ️ Historical Compatibility Note**->-> Legacy OpenViking/OpenClaw integrations had a known issue around OpenClaw `2026.3.12` where conversations could hang after the plugin loaded.-> That issue affected the legacy plugin path; the current context-engine Plugin 2.0 described in this document is not affected, so new installations do not need to downgrade OpenClaw for this reason.-> Plugin 2.0 is also not backward-compatible with the legacy `memory-openviking` plugin and its configuration, so upgrades must replace the old setup instead of mixing the two versions.-> Plugin 2.0 also depends on OpenClaw's context-engine capability and does not support older OpenClaw releases; upgrade OpenClaw first before following this guide.-> If you are troubleshooting a legacy deployment, see [#591](https://github.com/volcengine/OpenViking/issues/591) and upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.--> **🚀 Plugin 2.0 (Context-Engine Architecture)**->-> This document covers the current OpenViking Plugin 2.0 built on the context-engine architecture, which is the recommended integration path for AI coding assistants.-> For design background and earlier discussion, see:-> https://github.com/volcengine/OpenViking/discussions/525+Use [OpenViking](https://github.com/volcengine/OpenViking) as the long-term memory backend for [OpenClaw](https://github.com/openclaw/openclaw). After installation, OpenClaw will automatically remember important facts from conversations and recall relevant context before replying.------## One-Click Installation--**Prerequisites:** Python >= 3.10, Node.js >= 22. The setup helper will automatically check and prompt you to install any missing components.--### Prerequisite Steps for Upgrading from Legacy `memory-openviking` to New `openviking`+> This document covers the current OpenViking plugin built on OpenClaw's `context-engine` architecture.-- If the current environment already has the legacy `memory-openviking` plugin installed, complete the following prerequisite steps before installing the new version. Plugin 2.0 is not backward-compatible with the legacy plugin/configuration, so do not keep both versions active at the same time.--- If you have never installed the legacy plugin before, you can skip this section and go straight to installation.+## Prerequisites-- Plugin 2.0 is not backward-compatible with the legacy plugin/configuration, so do not keep both versions active at the same time.+| Component | Required Version |+| --- | --- |+| Python | >= 3.10 |+| Node.js | >= 22 |+| OpenClaw | >= 2026.3.7 |-#### Method A: Download and Run the Legacy Plugin Cleanup Script (Recommended)+Quick check:```bash-curl -fsSLO https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh-bash cleanup-memory-openviking.sh+python3 --version+node -v+openclaw --version```-#### Method B: Manually Clean Up the Legacy Plugin Configuration-1. Stop the OpenClaw gateway:+## Legacy Upgrade Note-```bash-openclaw gateway stop-```+If you previously installed the legacy `memory-openviking` plugin, remove it first, then continue with the install or upgrade commands below.-2. Back up the legacy configuration and plugin directory:+- The new `openviking` plugin is not compatible with the legacy `memory-openviking` plugin.+- If you never installed the legacy plugin, skip this section.```bash-cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-openviking-upgrade.bak-mkdir -p ~/.openclaw/disabled-extensions-mv ~/.openclaw/extensions/memory-openviking ~/.openclaw/disabled-extensions/memory-openviking-upgrade-backup+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh+bash cleanup-memory-openviking.sh```-3. Update the OpenClaw configuration and remove legacy settings:--Edit `~/.openclaw/openclaw.json`, remove `"memory-openviking"` from `plugins.allow`, remove `plugins.entries.memory-openviking`, change `plugins.slots.memory` to `"none"`, and remove the legacy `memory-openviking` plugin path from `plugins.load.paths`.+## Install-After cleaning up the legacy plugin configuration using either approach above, install the new plugin by following Method A or Method B below.--Preserve and migrate legacy runtime settings into the new configuration if needed (the new version works with defaults; legacy parameters are optional to migrate):--If the legacy plugin was using `plugins.entries.memory-openviking.config`, migrate `mode`, `configPath`, `port`, `baseUrl`, `apiKey`, `agentId`, and any other needed parameters from the backup `openclaw.json` file created in Step 2 into `plugins.entries.openviking.config`.--Run the prerequisite steps above only if they apply to your environment. Once finished, continue with the Plugin 2.0 installation flow. For now, we do not recommend direct natural-language installation; the npm one-click installer is the preferred path.--### Method A: npm Installation (Recommended, Including Windows)--**Windows:** use the same `npm`, `npx`, and `ov-install` commands in **PowerShell** or **cmd** (Node.js ≥ 22 required). For a non-default OpenClaw state directory, pass a real path to `--workdir` (e.g. `%USERPROFILE%\.openclaw-second`).+The recommended path is `npm` + `ov-install`.```bashnpm install -g openclaw-openviking-setup-helperov-install--```--If the installation fails because the system is missing tools to create a virtual environment, operate these commands below and re-run `ov-install`:--```bash-apt update-apt install -y software-properties-common-add-apt-repository universe-apt update-apt install -y python3-venv-```--Non-interactive mode (uses default configuration):--```bash-ov-install -y-```-Install to a specific OpenClaw instance:+Common variant:```bashov-install --workdir ~/.openclaw-second-```-#### Pinning versions (npm / `ov-install`)+## Upgrade-The published helper package is [`openclaw-openviking-setup-helper`](https://www.npmjs.com/package/openclaw-openviking-setup-helper). Install globally (latest by default), or append `@VERSION` with a published dist-tag or version from npm when you need to pin the installer:+To upgrade both OpenViking and the plugin to the latest version:```bash-npm install -g openclaw-openviking-setup-helper-ov-install -y+npm install -g openclaw-openviking-setup-helper@latest && ov-install -y```-Run **without** global install (same optional `@VERSION` pin):--```bash-npx -y -p openclaw-openviking-setup-helper ov-install -y-```+## Install or Upgrade a Specific Release-Use **`ov-install`** to install a **specific archived plugin version** or pin the **OpenViking PyPI version**:--| Flag | Meaning |-| --- | --- |-| `--github-repo owner/repo` | GitHub repo for plugin raw downloads (default: `volcengine/OpenViking`) |-| `--plugin-version REF` | Git branch, tag, or commit for plugin files (default: latest Git tag in `volcengine/OpenViking`) |-| `--openviking-version VER` | Pin `pip install openviking==VER` (omit for latest PyPI release) |--Examples:+To install or upgrade to a specific release:```bash-# Install a specific tagged plugin version (e.g. v0.2.9)-ov-install -y --plugin-version v0.2.9--# Pin OpenViking on PyPI, plugin still follows the repo's latest tag by default-ov-install -y --openviking-version 0.2.9--# Pin both plugin tag and OpenViking PyPI version-ov-install -y --plugin-version v0.2.9 --openviking-version 0.2.9--# Legacy plugin line (use a release in the v0.2.3-v0.2.6 range if you need the old plugin line)-ov-install -y --plugin-version <legacy-version>+ov-install -y --version 0.2.9```-Environment variables (same semantics): `REPO` (same as `--github-repo`), `PLUGIN_VERSION` / `BRANCH`, `OPENVIKING_VERSION`.+## Parameters-#### Upgrade and rollback (`ov-install`)--Use `--update` / `--upgrade-plugin` to upgrade **only the plugin** to a specific plugin ref. This mode:--- keeps the existing OpenViking service version-- keeps the existing `~/.openviking/ov.conf`-- preserves the current plugin runtime settings-- for local mode, keeps `configPath` and `port`-- for remote mode, keeps `baseUrl`, `apiKey`, and `agentId`-- cleans only the OpenViking plugin entries from `openclaw.json`, without touching unrelated plugins-- backs up `openclaw.json` and the previous plugin directory before replacing the plugin-- records the upgrade path and rollback audit file in the command output+| Parameter | Meaning |+| --- | --- |+| `--workdir PATH` | Target OpenClaw data directory |+| `--version VER` | Set both plugin version and OpenViking version. For example, `0.2.9` maps to plugin `v0.2.9` |+| `--current-version` | Print the currently installed plugin version and OpenViking version |+| `--plugin-version REF` | Set only the plugin version. Supports tag, branch, or commit |+| `--openviking-version VER` | Set only the PyPI OpenViking version |+| `--github-repo owner/repo` | Use a different GitHub repository for plugin files. Default: `volcengine/OpenViking` |+| `--update` | Upgrade only the plugin, without upgrading the OpenViking runtime |+| `-y` | Non-interactive mode, use default values |-Do **not** combine `--update` with `--openviking-version`; changing the OpenViking service version still requires a full install flow.+If you need to pin the installer itself:```bash-# Upgrade only the plugin to a tagged release-ov-install --update --plugin-version v0.2.9--# Upgrade only the plugin to a branch-ov-install --update --plugin-version dev-branch--# Upgrade only the plugin from a specific GitHub repo + branch-ov-install --update --github-repo yourname/OpenViking --plugin-version dev-branch--# Roll back the last plugin upgrade-ov-install --rollback+npm install -g openclaw-openviking-setup-helper@VERSION```-Upgrade backups are stored under:--- `~/.openclaw/.openviking-upgrade-backup/openclaw.json.bak`-- `~/.openclaw/.openviking-upgrade-backup/last-upgrade.json`-- `~/.openclaw/disabled-extensions/<pluginId>-upgrade-backup-*`--`--rollback` restores the latest saved `openclaw.json` snapshot and the previous plugin directory created by the last `--update`.--**Windows:** the same `ov-install` upgrade and rollback commands work in PowerShell or cmd.--### Method B: curl One-Click Installation (Linux / macOS)--On **Windows**, prefer **Method A** (`npm` / `ov-install`). `curl | bash` needs a Bash environment (**Git Bash** or **WSL**) if you use this section.--```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash+## OpenClaw Plugin Configuration-```+The plugin configuration lives under `plugins.entries.openviking.config`.-Non-interactive mode:+Get the current full plugin configuration:```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- -y-+openclaw config get plugins.entries.openviking.config```-Install to a specific OpenClaw instance:+### Local Mode-```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- --workdir ~/.openclaw-second -y+Use this mode when the OpenClaw plugin should start and manage a local OpenViking process.-```+| Parameter | Default | Meaning |+| --- | --- | --- |+| `mode` | `local` | Start a local OpenViking process |+| `agentId` | `default` | Logical identifier used by this OpenClaw instance in OpenViking |+| `configPath` | `~/.openviking/ov.conf` | Path to the local OpenViking config file |+| `port` | `1933` | Local OpenViking HTTP port |-#### Pinning versions (`install.sh`)+In `local` mode, service-side settings such as VLM, embedding, API keys, and storage live in `~/.openviking/ov.conf`, not in the OpenClaw plugin config. The most important `ov.conf` fields are:-| Flag / env | Meaning |+| Config Key | Meaning || --- | --- |-| `--repo owner/repo` / `REPO` | GitHub repo for plugin raw files (default: `volcengine/OpenViking`) |-| `--plugin-version REF` / `PLUGIN_VERSION` | Git branch, tag, or commit (default: latest Git tag; legacy: `BRANCH`) |-| `--openviking-version VER` / `OPENVIKING_VERSION` | `pip install openviking==VER` (omit for latest) |+| `vlm.api_key` / `vlm.model` / `vlm.api_base` | VLM used for memory extraction |+| `embedding.dense.api_key` / `embedding.dense.model` / `embedding.dense.api_base` | Embedding model used for vectorization |+| `server.port` | OpenViking service port |-Examples:+Common local-mode settings:```bash-# Install a specific tagged plugin version (e.g. v0.2.9)-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --plugin-version v0.2.9 -y--# Pin OpenViking on PyPI-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --openviking-version 0.2.9 -y--# Pin both plugin tag and OpenViking PyPI version-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --plugin-version v0.2.9 --openviking-version 0.2.9 -y+openclaw config set plugins.entries.openviking.config.mode local+openclaw config set plugins.entries.openviking.config.configPath ~/.openviking/ov.conf+openclaw config set plugins.entries.openviking.config.port 1933```-#### Upgrade and rollback (`install.sh`)+### Remote Mode-The `curl | bash` entry point now runs the same upgrade and rollback logic natively in `install.sh`. The target machine does not need a preinstalled global installer helper for plugin-only upgrade or rollback.+Use this mode when you already have a running OpenViking server and want OpenClaw to connect to it.-```bash-# Upgrade only the plugin to a tagged release-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --update --plugin-version v0.2.9--# Upgrade only the plugin to a branch-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --update --plugin-version dev-branch+| Parameter | Default | Meaning |+| --- | --- | --- |+| `mode` | `remote` | Connect to an existing OpenViking server |+| `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |+| `apiKey` | empty | Optional OpenViking API key |+| `agentId` | `default` | Logical identifier used by this OpenClaw instance on the remote server |-# Upgrade only the plugin from a specific GitHub repo + branch-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --update --repo yourname/OpenViking --plugin-version dev-branch+Common remote-mode settings:-# Roll back the last plugin upgrade-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash -s -- \- --rollback+```bash+openclaw config set plugins.entries.openviking.config.mode remote+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.apiKey your-api-key+openclaw config set plugins.entries.openviking.config.agentId your-agent-id```-`--update` only changes the plugin release. Do not pass `--openviking-version` in upgrade mode.--Native shell upgrade behavior:+## Start-- keeps the current local or remote plugin settings-- does not rewrite `~/.openviking/ov.conf`-- backs up `openclaw.json` to `~/.openclaw/.openviking-upgrade-backup/openclaw.json.bak`-- writes rollback audit data to `~/.openclaw/.openviking-upgrade-backup/last-upgrade.json`-- keeps only the latest plugin directory backup per plugin under `~/.openclaw/disabled-extensions/`-- prints `Upgrade path: <from> -> <to>` after a successful upgrade--The script will automatically detect multiple OpenClaw instances and let you choose. During a fresh install it also prompts you to select local or remote mode. During plugin-only upgrade it reuses the existing mode and config instead of prompting again.--### Start OpenClaw + OpenViking+After installation:```bashsource ~/.openclaw/openviking.env && openclaw gateway restart```-On Windows PowerShell:+Windows PowerShell:```powershell. "$HOME/.openclaw/openviking.env.ps1"openclaw gateway restart```-Seeing `openviking: registered context-engine` indicates the plugin was loaded.+## Verify-Then verify:+Check that the plugin owns the `contextEngine` slot:```bashopenclaw config get plugins.slots.contextEngine```-If it shows `openviking`, the startup is successful.+If the output is `openviking`, the plugin is active.-### Verify Read and Write--Use OpenClaw logs to verify memory capture and recall:+Follow OpenClaw logs:```bashopenclaw logs --follow```-Look for:--```-openviking: auto-captured 2 new messages, extracted 1 memories-```--You can also check a specific log file:--```bash-cat <your-log-file> | grep auto-capture-cat <your-log-file> | grep inject-```--Example:--```bash-cat /tmp/openclaw/openclaw-2026-03-20.log | grep auto-capture-cat /tmp/openclaw/openclaw-2026-03-20.log | grep inject-```--### View Memories with `ov tui`--In your OpenViking directory, activate the virtual environment and open the TUI:--```bash-source venv/bin/activate-ov --help-ov tui-```--Press `.` to expand folders, use arrow keys to navigate, and press `q` to quit.-------## Prerequisites--| Component | Version Requirement | Purpose |-| --- | --- | --- |-| **Python** | >= 3.10 | OpenViking Runtime |-| **Node.js** | >= 22 | OpenClaw Runtime |-| **Volcengine Ark API Key** | — | Embedding + VLM model calls |--Quick check:--```bash-python3 --version # >= 3.10-node -v # >= v22-openclaw --version # Installed--```--* Python: [https://www.python.org/downloads/](https://www.python.org/downloads/)-* Node.js: [https://nodejs.org/](https://nodejs.org/)-* OpenClaw: `npm install -g openclaw && openclaw onboard`-------## Method 1: Local Deployment (Recommended)--Start the OpenViking service locally, suitable for personal use.--### Step 1: Install OpenViking--```bash-python3 -m pip install openviking --upgrade--```--Verification: `python3 -c "import openviking; print('ok')"`--> Encountered `externally-managed-environment`? Use the one-click installation script (which handles venv automatically) or create it manually:-> `python3 -m venv ~/.openviking/venv && ~/.openviking/venv/bin/pip install openviking`--### Step 2: Run the Setup Helper--```bash-# Method A: npm install (recommended, cross-platform)-npm install -g openclaw-openviking-setup-helper-ov-install--# Method B: curl one-click (Linux / macOS)-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash-```--The setup helper will prompt you to enter your Ark API Key and automatically generate a configuration file.--### Step 3: Start--```bash-source ~/.openclaw/openviking.env && openclaw gateway--```--Seeing `openviking: local server started` indicates success.--### Step 4: Verify--```bash-openclaw status-# The ContextEngine row should display: enabled (plugin openviking)--```-------## Method 2: Connecting to Remote OpenViking--Already have a running OpenViking service? Simply configure the OpenClaw plugin to point to the remote address; **no Python / OpenViking installation is required**.--**Prerequisites:** An existing OpenViking service address + API Key (if authentication is enabled on the server side).--### Step 1: Install Plugin--```bash-npm install -g openclaw-openviking-setup-helper-ov-install-# Select remote mode, enter your OpenViking server URL and API Key-```--### Step 2: Start and Verify--```bash-openclaw gateway restart-openclaw status-```--<details>-<summary>Manual configuration (without setup helper)</summary>--```bash-openclaw plugins enable openviking-openclaw config set gateway.mode local-openclaw config set plugins.slots.contextEngine openviking-openclaw config set plugins.entries.openviking.config.mode remote-openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"-openclaw config set plugins.entries.openviking.config.apiKey "your-api-key"-openclaw config set plugins.entries.openviking.config.agentId "your-agent-id"-openclaw config set plugins.entries.openviking.config.autoRecall true --json-openclaw config set plugins.entries.openviking.config.autoCapture true --json-```--</details>--## Method 3: Integrating Openclaw with OpenViking on Volcengine ECS--This section primarily introduces how to connect Openclaw to OpenViking on Volcengine ECS and use the WebConsole to verify the data write. For details, please refer to the [documentation](https://www.volcengine.com/docs/6396/2249500?lang=zh).--Please note that to protect the system Python from being corrupted, the ECS instance has restrictions on deployments in the root directory and does not allow installing global packages directly using `pip`. It is recommended to create a virtual environment first and complete the following steps within it.--**Prerequisites:** An existing ECS OpenClaw instance.--### Step 1: npm Installation--```bash-npm install -g openclaw-openviking-setup-helper-ov-install--```--This installation mode already includes built-in VLM and embedding models in OpenViking. If no modifications are needed, simply press Enter and follow the prompts to enter your API key. After the installation is complete, a configuration file will be automatically generated. To modify it, enter `vim ~/.openviking/ov.conf`, press `i` to enter edit mode, press the `Esc` key to exit edit mode, then type `:wq` and press Enter to save and exit the file.--Load the OpenClaw environment variables in the terminal:--```bash-source /root/.openclaw/openviking.env--```--### Step 2: Start OpenViking--First, start the OpenViking Server:--```bash-python -m openviking.server.bootstrap--```--Next, start the web console. Before starting, you need to confirm whether the instance's security group has opened TCP port 8020 in the inbound rules. If not, please configure the instance security group first:+If you see `openviking: registered context-engine`, the plugin loaded successfully.-```bash-python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933+Check the OpenViking service log:-```--In the instance, find your server's public IP, and use it to access: `http://<your-server-public-ip>:8020`--You can now start experiencing the web console 🎉--You can directly query file information on the web interface to verify whether the openclaw-plugin memory write is effective; you can also verify if openclaw-plugin is reading memories in the OpenClaw logs. The verification method is as follows:+By default the log file lives under `workspace/data/log/openviking.log`. With the default setup this is usually:```bash-grep -i inject /tmp/openclaw/openclaw-2026-03-13.log | awk -F'"' '{for(i=1;i<=NF;i++) if($i ~ /^[0-9]{2}:[0-9]{2}:[0-9]{2}/) {time=$i; break}} /injecting [0-9]+ memories/ {print time, "openviking:", gensub(/.*(injecting [0-9]+ memories).*/, "\\1", "1")}'--```--Alternatively, you can directly run `grep "inject" /tmp/openclaw/openclaw-2026-03-13.log` to view all the information.-------## Configuration Reference--### `~/.openviking/ov.conf` (Local Mode)--```json-{- "root_api_key": null,- "server": { "host": "127.0.0.1", "port": 1933 },- "storage": {- "workspace": "/home/yourname/.openviking/data",- "vectordb": { "backend": "local" },- "agfs": { "backend": "local", "port": 1833 }- },- "embedding": {- "dense": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-embedding-vision-251215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "dimension": 1024,- "input": "multimodal"- }- },- "vlm": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-seed-2-0-pro-260215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3"- }-}-+cat ~/.openviking/data/log/openviking.log```-> `root_api_key`: Once set, all HTTP requests must carry the `X-API-Key` header. Defaults to `null` in local mode (authentication disabled).--### `agentId` Configuration (Plugin Configuration)--The Agent identifier passed to the server via the `X-OpenViking-Agent` header, used to distinguish different OpenClaw instances.--Customization method:+Check installed versions:```bash-# Specify in the plugin configuration-openclaw config set plugins.entries.openviking.config.agentId "my-agent"-+ov-install --current-version```-If not configured, the plugin auto-generates a unique ID in the format `openclaw-<hostname>-<random>`.--### `~/.openclaw/openviking.env`+## Uninstall-Automatically generated by the installer, recording environment variables such as the Python path:+To remove only the OpenClaw plugin and keep the OpenViking runtime:```bash-export OPENVIKING_PYTHON='/usr/local/bin/python3'-+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh -o uninstall-openviking.sh+bash uninstall-openviking.sh```-On Windows PowerShell, the installer writes `~/.openclaw/openviking.env.ps1` instead.-------## Daily Usage+For a non-default OpenClaw state directory:```bash-# Start-source ~/.openclaw/openviking.env && openclaw gateway--# Disable the context engine-openclaw config set plugins.slots.contextEngine legacy--# Enable OpenViking as the context engine-openclaw config set plugins.slots.contextEngine openviking-+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh -o uninstall-openviking.sh+bash uninstall-openviking.sh --workdir ~/.openclaw-second```------## Troubleshooting--| Symptom | Cause | Fix |-| --- | --- | --- |-| `port occupied` | Port occupied by another process | Change port: `openclaw config set plugins.entries.openviking.config.port 1934` |-| `extracted 0 memories` | API Key or model name configured incorrectly | Check the `api_key` and `model` fields in `ov.conf` |-| Plugin not loaded | Environment variables not loaded | Execute `source ~/.openclaw/openviking.env` before starting |-| `externally-managed-environment` | Python PEP 668 restriction | Use venv or the one-click installation script |-| `TypeError: unsupported operand type(s) for|` | Python < 3.10 | Upgrade Python to 3.10+ |-------## Uninstallation+To also remove the local OpenViking runtime and data:```bash-lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9python3 -m pip uninstall openviking -y && rm -rf ~/.openviking-```----**See also:** [INSTALL-ZH.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-ZH.md) (Chinese) · [INSTALL-AGENT.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md) (Agent Install Guide)-----+See also: [INSTALL-ZH.md](./INSTALL-ZH.md)diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.mdindex e6516f00a..fe9de4e2c 100644--- a/examples/openclaw-plugin/README.md+++ b/examples/openclaw-plugin/README.md@@ -1,456 +1,251 @@# OpenClaw + OpenViking Context-Engine Plugin-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. Once installed, OpenClaw will automatically **remember** important information from conversations and **recall** relevant context before responding.--> **ℹ️ Historical Compatibility Note**->-> Legacy OpenViking/OpenClaw integrations had a known issue around OpenClaw `2026.3.12` where conversations could hang after the plugin loaded.-> That issue affected the legacy plugin path; the current context-engine Plugin 2.0 described in this document is not affected, so new installations do not need to downgrade OpenClaw for this reason.-> Plugin 2.0 is also not backward-compatible with the legacy `memory-openviking` plugin and its configuration, so upgrades must replace the old setup instead of mixing the two versions.-> Plugin 2.0 also depends on OpenClaw's context-engine capability and does not support older OpenClaw releases; upgrade OpenClaw first before using this plugin.-> If you are troubleshooting a legacy deployment, see [#591](https://github.com/volcengine/OpenViking/issues/591) and upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.--> **🚀 Plugin 2.0 (Context-Engine Architecture)**->-> This document covers the current OpenViking Plugin 2.0 built on the context-engine architecture, which is the recommended integration path for AI coding assistants.-> For design background and earlier discussion, see:-> https://github.com/volcengine/OpenViking/discussions/525+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.----+## Documentation-## Table of Contents--- [One-Click Installation](#one-click-installation)-- [Manual Setup](#manual-setup)- - [Prerequisites](#prerequisites)- - [Local Mode (Personal Use)](#local-mode-personal-use)- - [Remote Mode (Team Sharing)](#remote-mode-team-sharing)- - [Volcengine ECS Deployment](#volcengine-ecs-deployment)-- [Starting & Verification](#starting--verification)-- [Configuration Reference](#configuration-reference)-- [Daily Usage](#daily-usage)-- [Web Console (Visualization)](#web-console-visualization)-- [Troubleshooting](#troubleshooting)-- [Uninstallation](#uninstallation)+- Install and upgrade: [INSTALL.md](./INSTALL.md)+- Chinese install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)+- Agent-oriented operator guide: [INSTALL-AGENT.md](./INSTALL-AGENT.md)----+## Technical Architecture-## One-Click Installation+### Plugin Responsibilities-For users who want a quick local experience. The setup helper handles environment detection, dependency installation, and config file generation automatically.+This plugin is not only a memory retriever. In code it plays four roles at once:-### Method A: npm Install (Recommended, Cross-platform)+- a `context-engine` plugin that implements `assemble`, `afterTurn`, and `compact`+- a hook layer that runs `before_prompt_build`, `session_start`, `session_end`, `agent_end`, and `before_reset`+- a tool provider that registers `memory_recall`, `memory_store`, `memory_forget`, and `ov_archive_expand`+- a runtime manager that can start and monitor a local OpenViking subprocess in `local` mode-```bash-npm install -g openclaw-openviking-setup-helper-ov-install-```+OpenClaw still owns the agent runtime and prompt orchestration. OpenViking owns long-term memory retrieval, session archiving, and memory extraction.-### Method B: curl One-Click (Linux / macOS)+### Identity and Routing-```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash-```+The plugin does not send a single global agent ID to OpenViking. It keeps OpenClaw session identity and OpenViking routing aligned:-The setup helper will walk you through:+- `sessionId` or `sessionKey` is converted into an OpenViking-safe session ID+- UUID session IDs are reused directly; other IDs fall back to a stable SHA-256 form when needed+- `X-OpenViking-Agent` is resolved per session, not per process+- if `plugins.entries.openviking.config.agentId` is not `default`, it becomes a prefix like `<configAgentId>_<sessionAgent>`+- routing and tenant headers are emitted by the client layer, and can be logged with `logFindRequests`-1. **Environment check** — Detects Python >= 3.10, Node.js, cmake, etc.-2. **Select OpenClaw instance** — If multiple instances are installed locally, lists them for you to choose-3. **Select deployment mode** — Local or Remote (see below)-4. **Generate config** — Writes `~/.openviking/ov.conf` and `~/.openclaw/openviking.env` automatically+This matters because the plugin supports multi-agent and multi-session OpenClaw flows without mixing memory across sessions.-<details>-<summary>Setup helper options</summary>+### Session Lifecycle-```-ov-install [options]+Session handling is the core design, and it spans both hooks and the context engine.- -y, --yes Non-interactive, use defaults- --workdir <path> OpenClaw config directory (default: ~/.openclaw)- -h, --help Show help+1. OpenClaw session identity is mapped to an OpenViking session ID.+2. `assemble()` asks OpenViking for session context with a token budget.+3. Returned archive summaries are rewritten into `[Session History Summary]` and `[Archive Index]`.+4. Active OpenViking messages are converted back into OpenClaw messages.+5. Tool calls and tool results are repaired so transcript structure stays provider-safe.+6. `afterTurn()` extracts only the new turn, sanitizes it, and appends it to the OpenViking session.+7. Once pending session tokens cross `commitTokenThreshold`, the plugin commits the OpenViking session and lets Phase 2 memory extraction continue asynchronously.+8. `compact()` performs a blocking commit, waits for archive generation, then re-reads compacted session context.-Env vars:- OPENVIKING_PYTHON Python path- OPENVIKING_CONFIG_FILE ov.conf path- OPENVIKING_REPO Local OpenViking repo path- OPENVIKING_ARK_API_KEY Volcengine API Key (skip prompt in -y mode)-```+The result is a session model where OpenClaw sees a reduced working context, while OpenViking keeps the long-form archive and extracted memories.-</details>+### What `assemble()` Actually Builds----+The assembled context is more than “old chat history”.-## Manual Setup+- archive overviews become a compact session summary block+- earlier archives are exposed as an ordered archive index+- active session messages stay uncompressed+- when precise details are missing, the model can call `ov_archive_expand` to reopen a specific archive-### Prerequisites+This is why the plugin can survive long sessions: it does not keep replaying the entire raw transcript into OpenClaw.-| Component | Version | Purpose |-|-----------|---------|---------|-| **Python** | >= 3.10 | OpenViking runtime (Local mode) |-| **Node.js** | >= 22 | OpenClaw runtime |-| **Volcengine Ark API Key** | — | Embedding + VLM model calls |+### Recall and Capture Pipeline-```bash-python3 --version # >= 3.10-node -v # >= v22-openclaw --version # installed-```+There are two memory loops around each turn.-- Python: https://www.python.org/downloads/-- Node.js: https://nodejs.org/-- OpenClaw: `npm install -g openclaw && openclaw onboard`+Before generation:----+- `before_prompt_build` extracts the latest user text+- it searches both `viking://user/memories` and `viking://agent/memories`+- results are deduplicated, reranked, and trimmed to a token budget+- the selected memories are injected as a `<relevant-memories>` block-### Local Mode (Personal Use)+After generation:-The simplest option — nearly zero configuration. The memory service runs alongside your OpenClaw agent locally. You only need a Volcengine Ark API Key.+- `afterTurn` formats the new turn into capture text+- assistant text, `toolUse`, and `toolResult` content are preserved+- metadata noise and injected memory blocks are stripped before capture+- OpenViking session commit triggers archive + extraction-#### Step 1: Install OpenViking+The reranking logic is query-aware. It boosts preferences, events, leaf memories, and lexical overlap instead of trusting vector score alone.-```bash-python3 -m pip install openviking --upgrade-```+### Transcript Ingest Assist-Verify: `python3 -c "import openviking; print('ok')"`+The plugin also has a special path for transcript-like user input.-> Hit `externally-managed-environment`? Use the one-click installer (handles venv automatically) or create one manually:-> ```bash-> python3 -m venv ~/.openviking/venv && ~/.openviking/venv/bin/pip install openviking-> ```+- multi-speaker text is detected with speaker-turn and length thresholds+- command text, metadata blocks, and pure question prompts are filtered out+- when a transcript-like ingest is detected, the plugin prepends a lightweight instruction so the model returns a short usable reply instead of `NO_REPLY`-#### Step 2: Run the Setup Helper+This is aimed at memory ingestion workflows where the user pastes chat transcripts or conversation dumps.-```bash-# Method A: npm install (recommended, cross-platform)-npm install -g openclaw-openviking-setup-helper-ov-install+### Local and Remote Runtime-# Method B: curl one-click (Linux / macOS)-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash-```+#### Local Mode-Select **local** mode, keep defaults, and enter your Ark API Key.+In `local` mode, the plugin starts OpenViking itself.-Generated config files:-- `~/.openviking/ov.conf` — OpenViking service config-- `~/.openclaw/openviking.env` — Environment variables (Python path, etc.)+- resolves Python from `OPENVIKING_PYTHON`, env files, or system defaults+- prepares the port before boot+- kills stale OpenViking processes on the same port+- auto-picks the next free port if the configured port is occupied by another process+- waits for `/health` before treating the service as ready+- caches the local client so multiple OpenClaw plugin contexts do not spawn duplicate runtimes-#### Step 3: Start+#### Remote Mode-```bash-source ~/.openclaw/openviking.env && openclaw gateway restart-```+In `remote` mode, the plugin only uses the HTTP API.-> In Local mode you must `source` the env file first — the plugin auto-starts an OpenViking subprocess.+- no subprocess is started+- `baseUrl` and optional `apiKey` come from OpenClaw plugin config+- the same session, recall, archive, and tool flow still applies-#### Step 4: Verify+### Tools and Operator Surfaces-```bash-openclaw status-# ContextEngine row should show: enabled (plugin openviking)-```+The plugin exposes more than automatic memory behavior.----+- `memory_recall`: search long-term memory explicitly+- `memory_store`: write text into an OpenViking session and force extraction+- `memory_forget`: delete a known memory URI or search and delete a strong single match+- `ov_archive_expand`: reopen a compressed session archive when the summary is not enough-### Remote Mode (Team Sharing)--For multiple OpenClaw instances or team use. Deploy a standalone OpenViking service that is shared across agents. **No Python/OpenViking needed on the client side.**--#### Step 1: Deploy the OpenViking Service--Edit `~/.openviking/ov.conf` — set `root_api_key` to enable multi-tenancy:--```json-{- "server": {- "host": "127.0.0.1",- "port": 1933,- "root_api_key": "<your-root-api-key>",- "cors_origins": ["*"]- },- "storage": {- "workspace": "~/.openviking/data",- "vectordb": {- "name": "context",- "backend": "local"- },- "agfs": {- "log_level": "warn",- "backend": "local"- }- },- "embedding": {- "dense": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-embedding-vision-251215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "dimension": 1024,- "input": "multimodal"- }- },- "vlm": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-seed-2-0-pro-260215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "temperature": 0.1,- "max_retries": 3- }-}-```+For operators, the main surfaces are:-Start the service:+- Web Console: inspect OpenViking files and memory state+- `ov tui`: browse local OpenViking data in terminal+- `ov-install --current-version`: show installed plugin version and OpenViking version+- `openclaw config get plugins.entries.openviking.config`: inspect current plugin config-```bash-openviking-server-```+## Tools-#### Step 2: Create Team & Users+### Web Console-```bash-# Create team + admin-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-api-key>" \- -d '{- "account_id": "my-team",- "admin_user_id": "admin"- }'--# Add member-curl -X POST http://localhost:1933/api/v1/admin/accounts/my-team/users \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-or-admin-key>" \- -d '{- "user_id": "xiaomei",- "role": "user"- }'-```+OpenViking includes a Web Console for inspecting stored files, debugging ingestion, and checking memory state.-#### Step 3: Configure the OpenClaw Plugin+Example startup:```bash-openclaw plugins enable openviking-openclaw config set gateway.mode local-openclaw config set plugins.slots.contextEngine openviking-openclaw config set plugins.entries.openviking.config.mode remote-openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"-openclaw config set plugins.entries.openviking.config.apiKey "<user-api-key>"-openclaw config set plugins.entries.openviking.config.agentId "<agent-id>"-openclaw config set plugins.entries.openviking.config.autoRecall true --json-openclaw config set plugins.entries.openviking.config.autoCapture true --json+python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933```-#### Step 4: Start & Verify+### `ov tui`++Use the terminal UI to browse OpenViking files locally:```bash-# Remote mode — no env sourcing needed-openclaw gateway restart-openclaw status+ov tui```------### Volcengine ECS Deployment--Deploy OpenClaw + OpenViking on Volcengine ECS. See [Volcengine docs](https://www.volcengine.com/docs/6396/2249500?lang=zh) for details.+### Version Inspection-> ECS instances restrict global pip installs under root to protect system Python. Create a venv first.+Show the installed plugin version and OpenViking version:```bash-# 1. Install-npm install -g openclaw-openviking-setup-helper-ov-install--# 2. Load environment-source /root/.openclaw/openviking.env--# 3. Start OpenViking server-python -m openviking.server.bootstrap--# 4. Start Web Console (ensure security group allows TCP 8020 inbound)-python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933+ov-install --current-version```-Access `http://<public-ip>:8020` to use the Web Console.+### Plugin Config Inspection------## Starting & Verification--### Local Mode+Print the full current OpenClaw plugin config:```bash-source ~/.openclaw/openviking.env && openclaw gateway restart+openclaw config get plugins.entries.openviking.config```-### Remote Mode+### Logs-```bash-openclaw gateway restart-```--### Check Plugin Status+OpenClaw plugin log stream:```bash-openclaw status-# ContextEngine row should show: enabled (plugin openviking)+openclaw logs --follow```-### View Plugin Config+OpenViking service log, default local path:```bash-openclaw config get plugins.entries.openviking.config-```-------## Configuration Reference--### `~/.openviking/ov.conf` (Local Mode)--```json-{- "root_api_key": null,- "server": { "host": "127.0.0.1", "port": 1933 },- "storage": {- "workspace": "~/.openviking/data",- "vectordb": { "backend": "local" },- "agfs": { "backend": "local", "port": 1833 }- },- "embedding": {- "dense": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-embedding-vision-251215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "dimension": 1024,- "input": "multimodal"- }- },- "vlm": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-seed-2-0-pro-260215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3"- }-}+cat ~/.openviking/data/log/openviking.log```-> `root_api_key`: When set, all HTTP requests must include the `X-API-Key` header. Defaults to `null` in Local mode (auth disabled).+## Troubleshooting-### Plugin Config Options+| Symptom | Likely Cause | What to Check |+| --- | --- | --- |+| `plugins.slots.contextEngine` is not `openviking` | Plugin slot was not set or was replaced | `openclaw config get plugins.slots.contextEngine` |+| Local mode does not start correctly | Python path, env file, or `ov.conf` is wrong | `source ~/.openclaw/openviking.env && openclaw gateway restart` |+| `port occupied` | Local OpenViking port is already used | Change `plugins.entries.openviking.config.port` or free the port |+| Recall works inconsistently across sessions | Agent/session routing is not what you expected | Enable `logFindRequests` and check `openclaw logs --follow` |+| Memory is not being captured after long chats | Pending tokens stay below `commitTokenThreshold` or extraction failed server-side | Check plugin config, OpenClaw logs, and `~/.openviking/data/log/openviking.log` |+| Session summaries are too lossy | You need archive expansion instead of summary-only context | Use `ov_archive_expand` with an ID from `[Archive Index]` |+| Installed versions are not what you expected | Plugin and OpenViking runtime versions diverged | Run `ov-install --current-version` |-| Option | Default | Description |-|--------|---------|-------------|-| `mode` | `remote` | `local` (start local server) or `remote` (connect to remote) |-| `baseUrl` | `http://127.0.0.1:1933` | OpenViking server URL (Remote mode) |-| `apiKey` | — | OpenViking API Key (optional) |-| `agentId` | auto-generated | Agent identifier, distinguishes OpenClaw instances. Auto-generates `openclaw-<hostname>-<random>` if unset |-| `configPath` | `~/.openviking/ov.conf` | Config file path (Local mode) |-| `port` | `1933` | Local server port (Local mode) |-| `targetUri` | `viking://user/memories` | Default memory search scope |-| `autoCapture` | `true` | Auto-extract memories after conversations |-| `captureMode` | `semantic` | Extraction mode: `semantic` (full semantic) / `keyword` (trigger-word only) |-| `captureMaxLength` | `24000` | Max text length per capture |-| `autoRecall` | `true` | Auto-recall relevant memories before conversations |-| `recallLimit` | `6` | Max memories injected during auto-recall |-| `recallScoreThreshold` | `0.01` | Minimum relevance score for recall |-| `ingestReplyAssist` | `true` | Add reply guidance when multi-party conversation text is detected |+## Usage Tutorials-### `~/.openclaw/openviking.env`+### Inspect the Current Setup-Auto-generated by the setup helper, stores environment variables like the Python path:+Use these commands together:```bash-export OPENVIKING_PYTHON='/usr/local/bin/python3'+ov-install --current-version+openclaw config get plugins.entries.openviking.config+openclaw config get plugins.slots.contextEngine```----+### Follow Recall and Capture-## Daily Usage+Watch the OpenClaw side:```bash-# Start (Local mode — source env first)-source ~/.openclaw/openviking.env && openclaw gateway--# Start (Remote mode — no env needed)-openclaw gateway--# Disable the context engine-openclaw config set plugins.slots.contextEngine legacy--# Re-enable OpenViking as the context engine-openclaw config set plugins.slots.contextEngine openviking+openclaw logs --follow```-> Restart the gateway after changing the context-engine slot.-------## Web Console (Visualization)--OpenViking provides a Web Console for debugging and inspecting stored memories.+Then inspect the OpenViking side:```bash-python -m openviking.console.bootstrap \- --host 127.0.0.1 \- --port 8020 \- --openviking-url http://127.0.0.1:1933 \- --write-enabled+cat ~/.openviking/data/log/openviking.log```-Open http://127.0.0.1:8020 in your browser.-------## Troubleshooting--### Common Issues+This is the fastest way to see session commit, archive generation, memory recall, and memory extraction.-| Symptom | Cause | Fix |-|---------|-------|-----|-| Conversation hangs, no response | Usually a legacy pre-2.0 integration affected by the historical OpenClaw `2026.3.12` issue | If you are on the legacy path, see [#591](https://github.com/volcengine/OpenViking/issues/591) and temporarily downgrade to `2026.3.11`; for current installs, migrate to Plugin 2.0 |-| `registerContextEngine is unavailable` in logs | OpenClaw version is too old and does not expose the context-engine API required by Plugin 2.0 | Upgrade OpenClaw to a current release, then restart the gateway and verify `openclaw status` shows `openviking` as the ContextEngine |-| Agent hangs silently, no output | auto-recall missing timeout protection | Disable auto-recall temporarily: `openclaw config set plugins.entries.openviking.config.autoRecall false --json`, or apply the patch in [#673](https://github.com/volcengine/OpenViking/issues/673) |-| ContextEngine is not `openviking` | Plugin slot not configured | `openclaw config set plugins.slots.contextEngine openviking` |-| `memory_store failed: fetch failed` | OpenViking not running | Check `ov.conf` and Python path; verify service is up |-| `health check timeout` | Port held by stale process | `lsof -ti tcp:1933 \| xargs kill -9`, then restart |-| `extracted 0 memories` | Wrong API Key or model name | Check `api_key` and `model` in `ov.conf` |-| `port occupied` | Port used by another process | Change port: `openclaw config set plugins.entries.openviking.config.port 1934` |-| Plugin not loaded | Env file not sourced | Run `source ~/.openclaw/openviking.env` before starting |-| `externally-managed-environment` | Python PEP 668 restriction | Use venv or the one-click installer |-| `TypeError: unsupported operand type(s) for \|` | Python < 3.10 | Upgrade Python to 3.10+ |+### Switch to Remote Mode-### Viewing Logs+If you already have a remote OpenViking service:```bash-# OpenViking logs-cat ~/.openviking/data/log/openviking.log+openclaw config set plugins.entries.openviking.config.mode remote+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.apiKey your-api-key+openclaw config set plugins.entries.openviking.config.agentId your-agent-id+openclaw gateway restart+```-# OpenClaw gateway logs-cat ~/.openclaw/logs/gateway.log-cat ~/.openclaw/logs/gateway.err.log+### Inspect Archived Session Details-# Check if OpenViking process is alive-lsof -i:1933+When the model only has a session summary, reopen a concrete archive:-# Quick connectivity check-curl http://localhost:1933-# Expected: {"detail":"Not Found"}+```text+Use ov_archive_expand with an archive ID from [Archive Index]```----+### Browse Stored Memory-## Uninstallation+Use the local terminal UI:```bash-lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9-python3 -m pip uninstall openviking -y && rm -rf ~/.openviking+ov tui```+Or use Web Console if you want a browser-based view of the stored memory data.+----**See also:** [INSTALL-ZH.md](./INSTALL-ZH.md) (中文详细安装指南) · [INSTALL.md](./INSTALL.md) (English Install Guide) · [INSTALL-AGENT.md](./INSTALL-AGENT.md) (Agent Install Guide)+For installation, upgrade, and uninstall operations, use [INSTALL.md](./INSTALL.md).diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.mdindex be46421af..9c0079c89 100644--- a/examples/openclaw-plugin/README_CN.md+++ b/examples/openclaw-plugin/README_CN.md@@ -1,456 +1,251 @@# OpenClaw + OpenViking 上下文引擎插件-使用 [OpenViking](https://github.com/volcengine/OpenViking) 作为 [OpenClaw](https://github.com/openclaw/openclaw) 的长期记忆后端。在 OpenClaw 中,此插件注册为 `openviking` 上下文引擎。安装后,OpenClaw 将自动**记忆**对话中的重要信息,并在响应前**召回**相关上下文。--> **ℹ️ 历史兼容性说明**->-> 传统的 OpenViking/OpenClaw 集成在 OpenClaw `2026.3.12` 附近存在一个已知问题,即对话可能在插件加载后挂起。-> 该问题仅影响传统插件路径;本文档中描述的当前上下文引擎插件 2.0 不受此影响,因此新安装无需因此降级 OpenClaw。-> 插件 2.0 也不向后兼容传统的 `memory-openviking` 插件及其配置,因此升级必须替换旧设置,而不是混合使用两个版本。-> 插件 2.0 还依赖于 OpenClaw 的上下文引擎功能,不支持旧版 OpenClaw;使用此插件前请先升级 OpenClaw。-> 如果您正在排查传统部署的问题,请参阅 [#591](https://github.com/volcengine/OpenViking/issues/591) 和上游修复 PR:openclaw/openclaw#34673、openclaw/openclaw#33547。--> **🚀 插件 2.0(上下文引擎架构)**->-> 本文档涵盖当前基于上下文引擎架构的 OpenViking 插件 2.0,这是 AI 编码助手的推荐集成路径。-> 有关设计背景和早期讨论,请参阅:-> https://github.com/volcengine/OpenViking/discussions/525+使用 [OpenViking](https://github.com/volcengine/OpenViking) 作为 [OpenClaw](https://github.com/openclaw/openclaw) 的长期记忆后端。在 OpenClaw 中,此插件注册为 `openviking` 上下文引擎。----+## 文档入口-## 目录--- [一键安装](#一键安装)-- [手动设置](#手动设置)- - [前置要求](#前置要求)- - [本地模式(个人使用)](#本地模式个人使用)- - [远程模式(团队共享)](#远程模式团队共享)- - [火山引擎 ECS 部署](#火山引擎-ecs-部署)-- [启动与验证](#启动与验证)-- [配置参考](#配置参考)-- [日常使用](#日常使用)-- [Web 控制台(可视化)](#web-控制台可视化)-- [故障排除](#故障排除)-- [卸载](#卸载)+- 安装与升级:[INSTALL-ZH.md](./INSTALL-ZH.md)+- English install guide: [INSTALL.md](./INSTALL.md)+- Agent 专用操作文档:[INSTALL-AGENT.md](./INSTALL-AGENT.md)----+## 技术架构-## 一键安装+### 插件承担了什么职责-适用于想要快速获得本地体验的用户。安装助手会自动处理环境检测、依赖安装和配置文件生成。+这个插件不只是“查记忆”的一层封装。按代码职责看,它同时扮演四个角色:-### 方法 A:npm 安装(推荐,跨平台)+- `context-engine` 插件:实现 `assemble`、`afterTurn`、`compact`+- Hook 层:接管 `before_prompt_build`、`session_start`、`session_end`、`agent_end`、`before_reset`+- Tool 提供者:注册 `memory_recall`、`memory_store`、`memory_forget`、`ov_archive_expand`+- 运行时管理器:在 `local` 模式下负责拉起并监控 OpenViking 子进程-```bash-npm install -g openclaw-openviking-setup-helper-ov-install-```+OpenClaw 仍然负责 agent 运行时和 prompt 编排,OpenViking 负责长期记忆检索、会话归档和记忆抽取。-### 方法 B:curl 一键安装(Linux / macOS)+### 身份与路由-```bash-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash-```+插件并不是把所有请求都打到一个固定的 agent ID 上,而是尽量保持 OpenClaw 会话身份和 OpenViking 路由一致:-安装助手将引导您完成:+- `sessionId` 或 `sessionKey` 会被映射成 OpenViking 可接受的 session ID+- UUID 会直接复用;不安全的 ID 会退化成稳定的 SHA-256+- `X-OpenViking-Agent` 是按会话解析的,不是按进程写死的+- 如果 `plugins.entries.openviking.config.agentId` 不是 `default`,它会作为前缀,形成 `<configAgentId>_<sessionAgent>`+- 实际 HTTP 请求由 client 层补全 `X-OpenViking-*` 头,打开 `logFindRequests` 后可以看到详细路由日志-1. **环境检查** — 检测 Python >= 3.10、Node.js、cmake 等-2. **选择 OpenClaw 实例** — 如果本地安装了多个实例,列出供您选择-3. **选择部署模式** — 本地或远程(见下文)-4. **生成配置** — 自动写入 `~/.openviking/ov.conf` 和 `~/.openclaw/openviking.env`+这样做的目的,是支持多 agent、多 session 场景下的记忆隔离,避免不同会话串到一起。-<details>-<summary>安装助手选项</summary>+### Session 生命周期-```-ov-install [options]+Session 是这套设计的核心,不只是“保留一段历史”这么简单。- -y, --yes 非交互式,使用默认值- --workdir <path> OpenClaw 配置目录(默认:~/.openclaw)- -h, --help 显示帮助+1. OpenClaw 会话标识先被映射成 OpenViking session ID。+2. `assemble()` 按 token budget 向 OpenViking 拉取会话上下文。+3. 归档摘要会被改写成 `[Session History Summary]` 和 `[Archive Index]`。+4. 当前活跃消息会重新转换回 OpenClaw 可消费的消息格式。+5. tool call / tool result 会做一次修复,保证 transcript 对各模型提供方更稳。+6. `afterTurn()` 只提取当前这一轮新增内容,清洗后追加进 OpenViking session。+7. 当 `pending_tokens` 超过 `commitTokenThreshold`,插件会提交 session,后端异步跑 Phase 2 记忆抽取。+8. `compact()` 会阻塞等待归档完成,再回读压缩后的上下文。-环境变量:- OPENVIKING_PYTHON Python 路径- OPENVIKING_CONFIG_FILE ov.conf 路径- OPENVIKING_REPO 本地 OpenViking 仓库路径- OPENVIKING_ARK_API_KEY 火山引擎 API Key(-y 模式下跳过提示)-```+因此,OpenClaw 侧拿到的是适合推理的精简上下文,OpenViking 侧保存的是长会话归档和抽取后的长期记忆。-</details>+### `assemble()` 实际组装了什么----+这里并不是简单地“把旧聊天记录塞回来”。-## 手动设置+- archive overview 会变成压缩后的 session summary+- 历史 archive 会变成有顺序的 archive index+- 当前活跃消息保持未压缩状态+- 如果摘要不够精确,模型可以调用 `ov_archive_expand` 打开某个 archive 的原始消息-### 前置要求+这也是插件能撑长会话的原因:它不会把整段原始 transcript 永远重复喂回 OpenClaw。-| 组件 | 版本 | 用途 |-|-----------|---------|---------|-| **Python** | >= 3.10 | OpenViking 运行时(本地模式) |-| **Node.js** | >= 22 | OpenClaw 运行时 |-| **火山引擎 Ark API Key** | — | Embedding + VLM 模型调用 |+### 记忆召回与写入链路-```bash-python3 --version # >= 3.10-node -v # >= v22-openclaw --version # 已安装-```+每一轮对话前后,其实有两条记忆链路。-- Python: https://www.python.org/downloads/-- Node.js: https://nodejs.org/-- OpenClaw: `npm install -g openclaw && openclaw onboard`+生成前:----+- `before_prompt_build` 提取最后一条用户文本+- 同时检索 `viking://user/memories` 和 `viking://agent/memories`+- 结果会先去重,再重排,再按 token budget 截断+- 最终以 `<relevant-memories>` 的形式注入上下文-### 本地模式个人使用+生成后:-最简单的选项 — 几乎无需配置。记忆服务与您的OpenClaw一起在本地运行。您只需要一个火山引擎Ark API Key。+- `afterTurn` 把本轮新增内容格式化成可写入文本+- assistant 文本、`toolUse`、`toolResult` 都会保留+- 注入过的记忆块和元数据噪音会先被剥掉+- OpenViking session commit 会触发 archive + memory extraction-#### 步骤 1:安装 OpenViking+这里的重排不是纯看向量分数。代码里还会额外提升 preference、event、leaf memory 以及 query 词面重合度。-```bash-python3 -m pip install openviking --upgrade-```+### Transcript Ingest Assist-验证:`python3 -c "import openviking; print('ok')"`+插件对“用户贴了一段多说话人转录文本”这种场景也单独做了处理。-> 遇到 `externally-managed-environment`?使用一键安装程序(自动处理 venv)或手动创建一个:-> ```bash-> python3 -m venv ~/.openviking/venv && ~/.openviking/venv/bin/pip install openviking-> ```+- 通过说话人数阈值和文本长度判断是否像 transcript+- 命令文本、元数据块、纯提问型文本会被排除+- 一旦判断为 transcript-like ingest,会额外注入一段轻量提示,减少模型直接返回 `NO_REPLY`-#### 步骤 2:运行安装助手+这主要服务于“把聊天记录、会议记录、对话转录灌进记忆系统”这类使用方式。-```bash-# 方法 A:npm 安装(推荐,跨平台)-npm install -g openclaw-openviking-setup-helper-ov-install+### Local 和 Remote 运行模式-# 方法 B:curl 一键安装(Linux / macOS)-curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash-```+#### Local 模式-选择 **本地** 模式,保持默认设置,并输入您的 Ark API Key。+`local` 模式下,插件自己拉起 OpenViking。-生成的配置文件:-- `~/.openviking/ov.conf` — OpenViking 服务配置-- `~/.openclaw/openviking.env` — 环境变量(Python 路径等)+- 会从 `OPENVIKING_PYTHON`、env 文件或系统默认值解析 Python+- 启动前先处理端口+- 如果端口上残留旧 OpenViking,会主动清理+- 如果端口被别的进程占用,会自动找下一个空闲端口+- 只有 `/health` 检查通过后,才认为服务可用+- 会缓存 local client,避免多个 OpenClaw 插件上下文重复拉起运行时-#### 步骤 3:启动+#### Remote 模式-```bash-source ~/.openclaw/openviking.env && openclaw gateway restart-```+`remote` 模式下,插件只走 HTTP API。-> 在本地模式下,您必须先 `source` 环境文件 — 插件会自动启动一个 OpenViking子进程。+- 不会启动本地子进程+- `baseUrl` 和可选的 `apiKey` 来自 OpenClaw 插件配置+- session、召回、archive、tool 的整体逻辑保持不变-#### 步骤 4:验证+### 工具与运维入口-```bash-openclaw status-# ContextEngine 行应显示:enabled (plugin openviking)-```+除了自动记忆行为,插件还直接暴露了几类工具:----+- `memory_recall`:显式检索长期记忆+- `memory_store`:写入文本到 OpenViking session 并立即触发抽取+- `memory_forget`:按 URI 删除,或先搜索再删除唯一高置信候选+- `ov_archive_expand`:当摘要不够时,展开某个压缩 archive 的原始消息-### 远程模式团队共享--适用于多个OpenClaw实例或团队使用。部署一个独立的OpenViking服务,供多个agents共享。**客户端无需 Python/OpenViking。**--#### 步骤 1:部署 OpenViking 服务--编辑 `~/.openviking/ov.conf` — 设置 `root_api_key` 以启用多租户:--```json-{- "server": {- "host": "127.0.0.1",- "port": 1933,- "root_api_key": "<your-root-api-key>",- "cors_origins": ["*"]- },- "storage": {- "workspace": "~/.openviking/data",- "vectordb": {- "name": "context",- "backend": "local"- },- "agfs": {- "log_level": "warn",- "backend": "local"- }- },- "embedding": {- "dense": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-embedding-vision-251215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "dimension": 1024,- "input": "multimodal"- }- },- "vlm": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-seed-2-0-pro-260215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "temperature": 0.1,- "max_retries": 3- }-}-```+对运维和调试来说,常用入口有:-启动服务:+- Web Console:看 OpenViking 文件和记忆状态+- `ov tui`:在终端里浏览本地数据+- `ov-install --current-version`:查看插件版本和 OpenViking 版本+- `openclaw config get plugins.entries.openviking.config`:查看当前插件配置-```bash-openviking-server-```+## 工具-#### 步骤 2:创建团队和用户+### Web Console-```bash-# 创建团队 + 管理员-curl -X POST http://localhost:1933/api/v1/admin/accounts \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-api-key>" \- -d '{- "account_id": "my-team",- "admin_user_id": "admin"- }'--# 添加成员-curl -X POST http://localhost:1933/api/v1/admin/accounts/my-team/users \- -H "Content-Type: application/json" \- -H "X-API-Key: <root-or-admin-key>" \- -d '{- "user_id": "xiaomei",- "role": "user"- }'-```+OpenViking 自带 Web Console,可用于查看存储文件、调试写入和观察记忆状态。-#### 步骤 3:配置 OpenClaw 插件+示例启动命令:```bash-openclaw plugins enable openviking-openclaw config set gateway.mode local-openclaw config set plugins.slots.contextEngine openviking-openclaw config set plugins.entries.openviking.config.mode remote-openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"-openclaw config set plugins.entries.openviking.config.apiKey "<user-api-key>"-openclaw config set plugins.entries.openviking.config.agentId "<agent-id>"-openclaw config set plugins.entries.openviking.config.autoRecall true --json-openclaw config set plugins.entries.openviking.config.autoCapture true --json+python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933```-#### 步骤 4:启动与验证+### `ov tui`++可以用终端界面浏览本地 OpenViking 文件:```bash-# 远程模式 — 无需 source 环境文件-openclaw gateway restart-openclaw status+ov tui```------### 火山引擎 ECS 部署--在火山引擎 ECS 上部署 OpenClaw + OpenViking。详见 [火山引擎文档](https://www.volcengine.com/docs/6396/2249500?lang=zh)。+### 查看版本-> ECS 实例限制在 root 下全局 pip 安装以保护系统 Python。请先创建 venv。+查看当前已安装的插件版本和 OpenViking 版本:```bash-# 1. 安装-npm install -g openclaw-openviking-setup-helper-ov-install--# 2. 加载环境-source /root/.openclaw/openviking.env--# 3. 启动 OpenViking 服务器-python -m openviking.server.bootstrap--# 4. 启动 Web 控制台(确保入站安全组允许 TCP 8020)-python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933+ov-install --current-version```-访问 `http://<public-ip>:8020` 使用 Web 控制台。-------## 启动与验证+### 查看插件配置-### 本地模式+查看当前 OpenClaw 插件整体配置:```bash-source ~/.openclaw/openviking.env && openclaw gateway restart+openclaw config get plugins.entries.openviking.config```-### 远程模式--```bash-openclaw gateway restart-```+### 日志-### 检查插件状态+OpenClaw 插件侧日志:```bash-openclaw status-# ContextEngine 行应显示:enabled (plugin openviking)+openclaw logs --follow```-### 查看插件配置+OpenViking 服务侧日志,默认本地路径:```bash-openclaw config get plugins.entries.openviking.config-```-------## 配置参考--### `~/.openviking/ov.conf`(本地模式)--```json-{- "root_api_key": null,- "server": { "host": "127.0.0.1", "port": 1933 },- "storage": {- "workspace": "~/.openviking/data",- "vectordb": { "backend": "local" },- "agfs": { "backend": "local", "port": 1833 }- },- "embedding": {- "dense": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-embedding-vision-251215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3",- "dimension": 1024,- "input": "multimodal"- }- },- "vlm": {- "provider": "volcengine",- "api_key": "<your-ark-api-key>",- "model": "doubao-seed-2-0-pro-260215",- "api_base": "https://ark.cn-beijing.volces.com/api/v3"- }-}+cat ~/.openviking/data/log/openviking.log```-> `root_api_key`:设置后,所有 HTTP 请求必须包含 `X-API-Key` 头。本地模式下默认为 `null`(禁用身份验证)。+## 故障排查-### 插件配置选项+| 现象 | 常见原因 | 排查方式 |+| --- | --- | --- |+| `plugins.slots.contextEngine` 不是 `openviking` | 插件槽位未设置,或被其它插件占用 | `openclaw config get plugins.slots.contextEngine` |+| `local` 模式启动异常 | Python 路径、env 文件或 `ov.conf` 有问题 | `source ~/.openclaw/openviking.env && openclaw gateway restart` |+| `port occupied` | 本地 OpenViking 端口已被占用 | 修改 `plugins.entries.openviking.config.port` 或释放端口 |+| 不同 session 的 recall 表现不稳定 | agent/session 路由和预期不一致 | 打开 `logFindRequests`,再看 `openclaw logs --follow` |+| 长对话后没有继续写入记忆 | `pending_tokens` 没达到阈值,或服务端抽取失败 | 检查插件配置、OpenClaw 日志和 `~/.openviking/data/log/openviking.log` |+| session summary 过于模糊 | 你需要 archive 级别细节,不是只看摘要 | 用 `[Archive Index]` 里的 ID 调用 `ov_archive_expand` |+| 当前版本和预期不一致 | 插件版本和 OpenViking 运行时版本未对齐 | 运行 `ov-install --current-version` |-| 选项 | 默认值 | 描述 |-|--------|---------|-------------|-| `mode` | `remote` | `local`(启动本地服务器)或 `remote`(连接远程服务器) |-| `baseUrl` | `http://127.0.0.1:1933` | OpenViking 服务器 URL(远程模式) |-| `apiKey` | — | OpenViking API Key(可选) |-| `agentId` | 自动生成 | agent标识符,用于区分 OpenClaw 实例。如果未设置则自动生成 `openclaw-<hostname>-<random>` |-| `configPath` | `~/.openviking/ov.conf` | 配置文件路径(本地模式) |-| `port` | `1933` | 本地服务器端口(本地模式) |-| `targetUri` | `viking://user/memories` | 默认记忆搜索范围 |-| `autoCapture` | `true` | 对话后自动提取记忆 |-| `captureMode` | `semantic` | 提取模式:`semantic`(完整语义)/ `keyword`(仅触发词) |-| `captureMaxLength` | `24000` | 每次提取的最大文本长度 |-| `autoRecall` | `true` | 对话前自动召回相关记忆 |-| `recallLimit` | `6` | 自动召回期间注入的最大记忆数 |-| `recallScoreThreshold` | `0.01` | 召回的最低相关性分数 |-| `ingestReplyAssist` | `true` | 检测到多方对话文本时添加回复指导 |+## 使用教程-### `~/.openclaw/openviking.env`+### 查看当前整体状态-由安装助手自动生成,存储环境变量(如 Python 路径):+建议一起执行:```bash-export OPENVIKING_PYTHON='/usr/local/bin/python3'+ov-install --current-version+openclaw config get plugins.entries.openviking.config+openclaw config get plugins.slots.contextEngine```----+### 观察召回和写入链路-## 日常使用+先看 OpenClaw 侧日志:```bash-# 启动(本地模式 — 先 source 环境文件)-source ~/.openclaw/openviking.env && openclaw gateway--# 启动(远程模式 — 无需环境文件)-openclaw gateway--# 禁用上下文引擎-openclaw config set plugins.slots.contextEngine legacy--# 重新启用 OpenViking 作为上下文引擎-openclaw config set plugins.slots.contextEngine openviking+openclaw logs --follow```-> 更改上下文引擎插槽后请重启网关。-------## Web-控制台可视化--OpenViking 提供 Web 控制台用于调试和检查存储的记忆。+再看 OpenViking 侧日志:```bash-python -m openviking.console.bootstrap \- --host 127.0.0.1 \- --port 8020 \- --openviking-url http://127.0.0.1:1933 \- --write-enabled+cat ~/.openviking/data/log/openviking.log```-在浏览器中打开 http://127.0.0.1:8020。-------## 故障排除--### 常见问题+这是判断 session commit、archive 生成、记忆召回和记忆抽取是否正常的最快方式。-| 症状 | 原因 | 解决方案 |-|---------|-------|-----|-| 对话挂起,无响应 | 通常是受历史 OpenClaw `2026.3.12` 问题影响的 2.0 之前传统集成 | 如果您使用传统路径,请参阅 [#591](https://github.com/volcengine/OpenViking/issues/591) 并临时降级到 `2026.3.11`;对于当前安装,请迁移到插件 2.0 |-| 日志中出现 `registerContextEngine is unavailable` | OpenClaw 版本过旧,未暴露插件 2.0 所需的上下文引擎 API | 升级 OpenClaw 到当前版本,然后重启网关并验证 `openclaw status` 显示 `openviking` 作为 ContextEngine |-| agent静默挂起,无输出 | 自动召回缺少超时保护 | 临时禁用自动召回:`openclaw config set plugins.entries.openviking.config.autoRecall false --json`,或应用 [#673](https://github.com/volcengine/OpenViking/issues/673) 中的补丁 |-| ContextEngine 不是 `openviking` | 插件插槽未配置 | `openclaw config set plugins.slots.contextEngine openviking` |-| `memory_store failed: fetch failed` | OpenViking 未运行 | 检查 `ov.conf` 和 Python 路径;验证服务是否运行 |-| `health check timeout` | 端口被陈旧进程占用 | `lsof -ti tcp:1933 \| xargs kill -9`,然后重启 |-| `extracted 0 memories` | API Key 或模型名称错误 | 检查 `ov.conf` 中的 `api_key` 和 `model` |-| `port occupied` | 端口被其他进程占用 | 更改端口:`openclaw config set plugins.entries.openviking.config.port 1934` |-| 插件未加载 | 环境文件未 source | 启动前运行 `source ~/.openclaw/openviking.env` |-| `externally-managed-environment` | Python PEP 668 限制 | 使用 venv 或一键安装程序 |-| `TypeError: unsupported operand type(s) for \|` | Python < 3.10 | 升级 Python 到 3.10+ |+### 切换到 Remote 模式-### 查看日志+如果已经有远端 OpenViking 服务:```bash-# OpenViking 日志-cat ~/.openviking/data/log/openviking.log+openclaw config set plugins.entries.openviking.config.mode remote+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.apiKey your-api-key+openclaw config set plugins.entries.openviking.config.agentId your-agent-id+openclaw gateway restart+```-# OpenClaw 网关日志-cat ~/.openclaw/logs/gateway.log-cat ~/.openclaw/logs/gateway.err.log+### 查看压缩会话的原始细节-# 检查 OpenViking 进程是否存活-lsof -i:1933+当模型只拿到了摘要,但你需要更精确的命令、路径或代码内容时:-# 快速连接检查-curl http://localhost:1933-# 预期:{"detail":"Not Found"}+```text+使用 [Archive Index] 里的 archive ID 调用 ov_archive_expand```----+### 浏览记忆内容-## 卸载+可以使用本地终端界面:```bash-lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9-python3 -m pip uninstall openviking -y && rm -rf ~/.openviking+ov tui```+如果希望用浏览器查看,也可以使用 Web Console。+----**另见:** [INSTALL-ZH.md](./INSTALL-ZH.md)(中文详细安装指南)· [INSTALL.md](./INSTALL.md)(英文安装指南)· [INSTALL-AGENT.md](./INSTALL-AGENT.md)(Agent 安装指南)+安装、升级、卸载请查看 [INSTALL-ZH.md](./INSTALL-ZH.md)。diff --git a/examples/openclaw-plugin/install.sh b/examples/openclaw-plugin/install.shindex ef7ae6a8f..b62887708 100755--- a/examples/openclaw-plugin/install.sh+++ b/examples/openclaw-plugin/install.sh@@ -5,6 +5,7 @@## Options:# --repo <owner/repo> - GitHub repository (default: volcengine/OpenViking)+# --version <ver> - Shorthand for --plugin-version v<ver> + --openviking-version <ver># --plugin-version <tag> - Plugin version (Git tag, e.g. v0.2.9, default: latest tag)# --openviking-version <ver> - OpenViking PyPI version (e.g. 0.2.9, default: latest)# --workdir <path> - OpenClaw config directory (default: ~/.openclaw)@@ -52,6 +53,10 @@ if [[ -n "${PLUGIN_VERSION:-}" || -n "${BRANCH:-}" ]]; thenfiPLUGIN_VERSION="${PLUGIN_VERSION:-${BRANCH:-}}"OPENVIKING_VERSION="${OPENVIKING_VERSION:-}"+VERSION_ALIAS=""+VERSION_ALIAS_EXPLICIT="0"+PLUGIN_VERSION_ARG_EXPLICIT="0"+OPENVIKING_VERSION_ARG_EXPLICIT="0"INSTALL_YES="${OPENVIKING_INSTALL_YES:-0}"UPGRADE_PLUGIN_ONLY="${OPENVIKING_UPGRADE_PLUGIN_ONLY:-0}"ROLLBACK_LAST_UPGRADE="${OPENVIKING_ROLLBACK_LAST_UPGRADE:-0}"@@ -110,6 +115,7 @@ UPGRADE_AUDIT_PLUGIN_BACKUPS=()_expect_workdir=""_expect_plugin_version=""_expect_ov_version=""+_expect_version_alias=""_expect_repo=""for arg in "$@"; doif [[ -n "$_expect_workdir" ]]; then@@ -120,14 +126,22 @@ for arg in "$@"; doif [[ -n "$_expect_plugin_version" ]]; thenPLUGIN_VERSION="$arg"PLUGIN_VERSION_EXPLICIT="1"+ PLUGIN_VERSION_ARG_EXPLICIT="1"_expect_plugin_version=""continuefiif [[ -n "$_expect_ov_version" ]]; thenOPENVIKING_VERSION="$arg"+ OPENVIKING_VERSION_ARG_EXPLICIT="1"_expect_ov_version=""continuefi+ if [[ -n "$_expect_version_alias" ]]; then+ VERSION_ALIAS="$arg"+ VERSION_ALIAS_EXPLICIT="1"+ _expect_version_alias=""+ continue+ fiif [[ -n "$_expect_repo" ]]; thenREPO="$arg"_expect_repo=""@@ -140,12 +154,17 @@ for arg in "$@"; do[[ "$arg" == "--workdir" ]] && { _expect_workdir="1"; continue; }[[ "$arg" == "--plugin-version" ]] && { _expect_plugin_version="1"; continue; }[[ "$arg" == "--openviking-version" ]] && { _expect_ov_version="1"; continue; }+ [[ "$arg" == "--version" ]] && { _expect_version_alias="1"; continue; }+ [[ "$arg" == --plugin-version=* ]] && { PLUGIN_VERSION="${arg#--plugin-version=}"; PLUGIN_VERSION_EXPLICIT="1"; PLUGIN_VERSION_ARG_EXPLICIT="1"; continue; }+ [[ "$arg" == --openviking-version=* ]] && { OPENVIKING_VERSION="${arg#--openviking-version=}"; OPENVIKING_VERSION_ARG_EXPLICIT="1"; continue; }+ [[ "$arg" == --version=* ]] && { VERSION_ALIAS="${arg#--version=}"; VERSION_ALIAS_EXPLICIT="1"; continue; }[[ "$arg" == "--repo" ]] && { _expect_repo="1"; continue; }[[ "$arg" == "-h" || "$arg" == "--help" ]] && {echo "Usage: curl -fsSL <INSTALL_URL> | bash [-s -- OPTIONS]"echo ""echo "Options:"echo " --repo <owner/repo> GitHub repository (default: volcengine/OpenViking)"+ echo " --version <v> Shorthand for --plugin-version v<v> and --openviking-version <v>"echo " --plugin-version <tag> Plugin version (Git tag, e.g. v0.2.9, default: latest tag)"echo " --openviking-version <v> OpenViking PyPI version (e.g. 0.2.9, default: latest)"echo " --workdir <path> OpenClaw config directory (default: ~/.openclaw)"@@ -160,6 +179,9 @@ for arg in "$@"; doecho " # Install latest version"echo " curl -fsSL <URL> | bash"echo ""+ echo " # Install a specific release version"+ echo " curl -fsSL <URL> | bash -s -- --version 0.2.9"+ echo ""echo " # Install from a fork repository"echo " curl -fsSL <URL> | bash -s -- --repo yourname/OpenViking --plugin-version dev-branch"echo ""@@ -177,6 +199,28 @@ for arg in "$@"; do}done+normalize_combined_version() {+ local value="${1:-}"+ local normalized="${value#v}"+ if [[ ! "$normalized" =~ ^[0-9]+(\.[0-9]+){1,2}$ ]]; then+ err "--version requires a semantic version like 0.2.9 or v0.2.9"+ exit 1+ fi+ COMBINED_PLUGIN_VERSION="v${normalized}"+ COMBINED_OPENVIKING_VERSION="${normalized}"+}++if [[ "$VERSION_ALIAS_EXPLICIT" == "1" ]]; then+ if [[ "$PLUGIN_VERSION_ARG_EXPLICIT" == "1" || "$OPENVIKING_VERSION_ARG_EXPLICIT" == "1" ]]; then+ err "--version cannot be used together with --plugin-version or --openviking-version"+ exit 1+ fi+ normalize_combined_version "$VERSION_ALIAS"+ PLUGIN_VERSION="${COMBINED_PLUGIN_VERSION}"+ OPENVIKING_VERSION="${COMBINED_OPENVIKING_VERSION}"+ PLUGIN_VERSION_EXPLICIT="1"+fi+if [[ "$UPGRADE_PLUGIN_ONLY" == "1" && "$ROLLBACK_LAST_UPGRADE" == "1" ]]; thenecho "[ERROR] --update/--upgrade-plugin and --rollback cannot be used together"exit 1@@ -290,7 +334,7 @@ validate_requested_plugin_version() {ensure_plugin_only_operation_args() {if [[ ("${UPGRADE_PLUGIN_ONLY}" == "1" || "${ROLLBACK_LAST_UPGRADE}" == "1") && -n "${OPENVIKING_VERSION}" ]]; then- err "--update/--upgrade-plugin and --rollback only operate on the plugin. Do not use --openviking-version with these modes."+ err "--update/--upgrade-plugin and --rollback only operate on the plugin. Do not use --openviking-version or --version with these modes."exit 1fi}@@ -1474,9 +1518,9 @@ install_openviking() {local pkg_spec="openviking"if [[ -n "$OPENVIKING_VERSION" ]]; thenpkg_spec="openviking==${OPENVIKING_VERSION}"- info "$(tr "Installing OpenViking ${OPENVIKING_VERSION} from PyPI..." "正在安装 OpenViking ${OPENVIKING_VERSION} (PyPI)...")"+ info "$(tr "Installing or upgrading OpenViking ${OPENVIKING_VERSION} from PyPI..." "正在安装或升级 OpenViking ${OPENVIKING_VERSION} (PyPI)...")"else- info "$(tr "Installing OpenViking (latest) from PyPI..." "正在安装 OpenViking (最新版) (PyPI)...")"+ info "$(tr "Installing or upgrading OpenViking (latest) from PyPI..." "正在安装或升级 OpenViking (最新版) (PyPI)...")"fiinfo "$(tr "Using pip index: ${PIP_INDEX_URL}" "使用 pip 镜像: ${PIP_INDEX_URL}")"@@ -1487,7 +1531,7 @@ install_openviking() {local pip_logpip_log=$(mktemp)"$py" -m pip install --upgrade pip -q -i "${PIP_INDEX_URL}" >/dev/null 2>&1 || true- if run_pip_install_capture "${pip_log}" "$py" -m pip install --progress-bar on "$pkg_spec" -i "${PIP_INDEX_URL}"; then+ if run_pip_install_capture "${pip_log}" "$py" -m pip install --upgrade --progress-bar on "$pkg_spec" -i "${PIP_INDEX_URL}"; thenrm -f "${pip_log}" 2>/dev/null || trueOPENVIKING_PYTHON_PATH="$(command -v "$py" || true)"[[ -z "$OPENVIKING_PYTHON_PATH" ]] && OPENVIKING_PYTHON_PATH="$py"@@ -1506,7 +1550,7 @@ install_openviking() {# Opt-in: allow install with --break-system-packages when venv is not available (PEP 668 only, default off)if [[ "${OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES}" == "1" ]]; theninfo "Installing OpenViking with --break-system-packages (OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES=1)"- if "$py" -m pip install --progress-bar on --break-system-packages "$pkg_spec" -i "${PIP_INDEX_URL}"; then+ if "$py" -m pip install --upgrade --progress-bar on --break-system-packages "$pkg_spec" -i "${PIP_INDEX_URL}"; thenOPENVIKING_PYTHON_PATH="$(command -v "$py" || true)"[[ -z "$OPENVIKING_PYTHON_PATH" ]] && OPENVIKING_PYTHON_PATH="$py"info "OpenViking installed (system)"diff --git a/examples/openclaw-plugin/setup-helper/install.js b/examples/openclaw-plugin/setup-helper/install.jsold mode 100644new mode 100755index 16f13fda8..c53ebca80--- a/examples/openclaw-plugin/setup-helper/install.js+++ b/examples/openclaw-plugin/setup-helper/install.js@@ -11,7 +11,7 @@** Direct run:* node install.js [ -y | --yes ] [ --zh ] [ --workdir PATH ] [ --upgrade-plugin ]- * [ --plugin-version=TAG ] [ --openviking-version=V ] [ --repo=PATH ]+ * [ --plugin-version=TAG ] [ --openviking-version=V ] [ --version=V ] [ --repo=PATH ]** Environment variables:* REPO, PLUGIN_VERSION (or BRANCH), OPENVIKING_INSTALL_YES, SKIP_OPENCLAW, SKIP_OPENVIKING@@ -109,6 +109,11 @@ let openvikingRepo = process.env.OPENVIKING_REPO || "";let workdirExplicit = false;let upgradePluginOnly = false;let rollbackLastUpgrade = false;+let combinedVersion = "";+let combinedVersionExplicit = false;+let pluginVersionArgExplicit = false;+let openvikingVersionArgExplicit = false;+let showCurrentVersion = false;let selectedMode = "local";let selectedServerPort = DEFAULT_SERVER_PORT;@@ -131,6 +136,10 @@ for (let i = 0; i < argv.length; i++) {langZh = true;continue;}+ if (arg === "--current-version") {+ showCurrentVersion = true;+ continue;+ }if (arg === "--upgrade-plugin" || arg === "--update" || arg === "--upgrade") {upgradePluginOnly = true;continue;@@ -158,6 +167,7 @@ for (let i = 0; i < argv.length; i++) {}PLUGIN_VERSION = version;pluginVersionExplicit = true;+ pluginVersionArgExplicit = true;continue;}if (arg === "--plugin-version") {@@ -168,11 +178,13 @@ for (let i = 0; i < argv.length; i++) {}PLUGIN_VERSION = version;pluginVersionExplicit = true;+ pluginVersionArgExplicit = true;i += 1;continue;}if (arg.startsWith("--openviking-version=")) {openvikingVersion = arg.slice("--openviking-version=".length).trim();+ openvikingVersionArgExplicit = true;continue;}if (arg === "--openviking-version") {@@ -182,6 +194,28 @@ for (let i = 0; i < argv.length; i++) {process.exit(1);}openvikingVersion = version;+ openvikingVersionArgExplicit = true;+ i += 1;+ continue;+ }+ if (arg.startsWith("--version=")) {+ const version = arg.slice("--version=".length).trim();+ if (!version) {+ console.error("--version requires a value");+ process.exit(1);+ }+ combinedVersion = version;+ combinedVersionExplicit = true;+ continue;+ }+ if (arg === "--version") {+ const version = argv[i + 1]?.trim();+ if (!version) {+ console.error("--version requires a value");+ process.exit(1);+ }+ combinedVersion = version;+ combinedVersionExplicit = true;i += 1;continue;}@@ -209,18 +243,44 @@ for (let i = 0; i < argv.length; i++) {}}+if (combinedVersionExplicit) {+ if (pluginVersionArgExplicit || openvikingVersionArgExplicit) {+ console.error("--version cannot be used together with --plugin-version or --openviking-version");+ process.exit(1);+ }+ const normalizedVersion = normalizeCombinedVersion(combinedVersion);+ PLUGIN_VERSION = normalizedVersion.pluginVersion;+ openvikingVersion = normalizedVersion.openvikingVersion;+ pluginVersionExplicit = true;+}+function setOpenClawDir(dir) {OPENCLAW_DIR = dir;}+function normalizeCombinedVersion(version) {+ const value = (version || "").trim();+ if (!/^(v)?\d+(\.\d+){1,2}$/.test(value)) {+ console.error("--version requires a semantic version like 0.2.9 or v0.2.9");+ process.exit(1);+ }+ const openvikingVersionValue = value.startsWith("v") ? value.slice(1) : value;+ return {+ pluginVersion: `v${openvikingVersionValue}`,+ openvikingVersion: openvikingVersionValue,+ };+}+function printHelp() {console.log("Usage: node install.js [ OPTIONS ]");console.log("");console.log("Options:");console.log(" --github-repo=OWNER/REPO GitHub repository (default: volcengine/OpenViking)");+ console.log(" --version=V Shorthand for --plugin-version=vV and --openviking-version=V");console.log(" --plugin-version=TAG Plugin version (Git tag, e.g. v0.2.9, default: latest tag)");console.log(" --openviking-version=V OpenViking PyPI version (e.g. 0.2.9, default: latest)");console.log(" --workdir PATH OpenClaw config directory (default: ~/.openclaw)");+ console.log(" --current-version Print installed plugin/OpenViking versions and exit");console.log(" --repo=PATH Use local OpenViking repo at PATH (pip -e + local plugin)");console.log(" --update, --upgrade-plugin");console.log(" Upgrade only the plugin to the requested --plugin-version; keep ov.conf and do not change the OpenViking service");@@ -234,6 +294,12 @@ function printHelp() {console.log(" # Install latest version");console.log(" node install.js");console.log("");+ console.log(" # Show installed versions");+ console.log(" node install.js --current-version");+ console.log("");+ console.log(" # Install a specific release version");+ console.log(" node install.js --version=0.2.9");+ console.log("");console.log(" # Install from a fork repository");console.log(" node install.js --github-repo=yourname/OpenViking --plugin-version=dev-branch");console.log("");@@ -442,6 +508,10 @@ async function selectWorkdir() {const instances = detectOpenClawInstances();if (instances.length <= 1) return;+ if (showCurrentVersion) {+ setOpenClawDir(instances[0]);+ return;+ }if (installYes) return;console.log("");@@ -581,8 +651,8 @@ function ensurePluginOnlyOperationArgs() {if ((upgradePluginOnly || rollbackLastUpgrade) && openvikingVersion) {err(tr(- "Plugin-only upgrade/rollback does not support --openviking-version. Use --plugin-version to choose the plugin release, and run a full install if you need to change the OpenViking service version.",- "仅插件升级或回滚不支持 --openviking-version。请使用 --plugin-version 指定插件版本;如果需要调整 OpenViking 服务版本,请执行完整安装流程。",+ "Plugin-only upgrade/rollback does not support --openviking-version or --version. Use --plugin-version to choose the plugin release, and run a full install if you need to change the OpenViking service version.",+ "仅插件升级或回滚不支持 --openviking-version 或 --version。请使用 --plugin-version 指定插件版本;如果需要调整 OpenViking 服务版本,请执行完整安装流程。",),);process.exit(1);@@ -935,9 +1005,9 @@ async function installOpenViking() {// Determine package specconst pkgSpec = openvikingVersion ? `openviking==${openvikingVersion}` : "openviking";if (openvikingVersion) {- info(tr(`Installing OpenViking ${openvikingVersion} from PyPI...`, `正在安装 OpenViking ${openvikingVersion} (PyPI)...`));+ info(tr(`Installing or upgrading OpenViking ${openvikingVersion} from PyPI...`, `正在安装或升级 OpenViking ${openvikingVersion} (PyPI)...`));} else {- info(tr("Installing OpenViking (latest) from PyPI...", "正在安装 OpenViking (最新版) (PyPI)..."));+ info(tr("Installing or upgrading OpenViking (latest) from PyPI...", "正在安装或升级 OpenViking (最新版) (PyPI)..."));}info(tr(`Using pip index: ${PIP_INDEX_URL}`, `使用 pip 镜像源: ${PIP_INDEX_URL}`));@@ -945,7 +1015,7 @@ async function installOpenViking() {await runCapture(py, ["-m", "pip", "install", "--upgrade", "pip", "-q", "-i", PIP_INDEX_URL], { shell: false });const installResult = await runLiveCapture(py,- ["-m", "pip", "install", "--progress-bar", "on", pkgSpec, "-i", PIP_INDEX_URL],+ ["-m", "pip", "install", "--upgrade", "--progress-bar", "on", pkgSpec, "-i", PIP_INDEX_URL],{ shell: false },);if (installResult.code === 0) {@@ -1001,7 +1071,7 @@ async function installOpenViking() {await runCapture(venvPy, ["-m", "pip", "install", "--upgrade", "pip", "-q", "-i", PIP_INDEX_URL], { shell: false });const venvInstall = await runLiveCapture(venvPy,- ["-m", "pip", "install", "--progress-bar", "on", pkgSpec, "-i", PIP_INDEX_URL],+ ["-m", "pip", "install", "--upgrade", "--progress-bar", "on", pkgSpec, "-i", PIP_INDEX_URL],{ shell: false },);if (venvInstall.code === 0) {@@ -1018,7 +1088,7 @@ async function installOpenViking() {if (process.env.OPENVIKING_ALLOW_BREAK_SYSTEM_PACKAGES === "1") {const systemInstall = await runLiveCapture(py,- ["-m", "pip", "install", "--progress-bar", "on", "--break-system-packages", pkgSpec, "-i", PIP_INDEX_URL],+ ["-m", "pip", "install", "--upgrade", "--progress-bar", "on", "--break-system-packages", pkgSpec, "-i", PIP_INDEX_URL],{ shell: false },);if (systemInstall.code === 0) {@@ -1129,6 +1199,66 @@ function getInstallStatePathForPlugin(pluginId) {return join(OPENCLAW_DIR, "extensions", pluginId, ".ov-install-state.json");}+async function detectInstalledOpenVikingVersion() {+ const pythonCandidates = [];+ const configuredPython = process.env.OPENVIKING_PYTHON?.trim();+ if (configuredPython) {+ pythonCandidates.push(configuredPython);+ }++ const envCandidates = IS_WIN+ ? [join(OPENCLAW_DIR, "openviking.env.ps1"), join(OPENCLAW_DIR, "openviking.env.bat")]+ : [join(OPENCLAW_DIR, "openviking.env")];++ for (const envPath of envCandidates) {+ if (!existsSync(envPath)) continue;+ const raw = await readFile(envPath, "utf8").catch(() => "");+ if (!raw) continue;+ const match = raw.match(/OPENVIKING_PYTHON(?:\s*=\s*|=)['"]?([^'"\r\n]+)['"]?/);+ const pythonPath = match?.[1]?.trim();+ if (pythonPath) {+ pythonCandidates.push(pythonPath);+ }+ }++ for (const candidate of IS_WIN ? ["py", "python", "python3"] : ["python3", "python"]) {+ pythonCandidates.push(candidate);+ }++ const seen = new Set();+ for (const candidate of pythonCandidates) {+ if (!candidate || seen.has(candidate)) continue;+ seen.add(candidate);+ const result = await runCapture(candidate, ["-c", "import openviking; print(openviking.__version__)"], { shell: IS_WIN });+ if (result.code === 0) {+ return result.out.trim();+ }+ }++ return "";+}++async function printCurrentVersionInfo() {+ const state = await readJsonFileIfExists(getInstallStatePathForPlugin("openviking"));+ const pluginRequestedRef = state?.requestedRef || "";+ const pluginReleaseId = state?.releaseId || "";+ const pluginInstalledAt = state?.installedAt || "";+ const openvikingInstalledVersion = await detectInstalledOpenVikingVersion();++ console.log("");+ bold(tr("Installed versions", "当前已安装版本"));+ console.log("");+ console.log(`Target: ${OPENCLAW_DIR}`);+ console.log(`Plugin: ${pluginReleaseId || pluginRequestedRef || "not installed"}`);+ if (pluginRequestedRef && pluginReleaseId && pluginRequestedRef !== pluginReleaseId) {+ console.log(`Plugin requested ref: ${pluginRequestedRef}`);+ }+ console.log(`OpenViking: ${openvikingInstalledVersion || "unknown"}`);+ if (pluginInstalledAt) {+ console.log(`Installed at: ${pluginInstalledAt}`);+ }+}+function getUpgradeAuditDir() {return join(OPENCLAW_DIR, ".openviking-upgrade-backup");}@@ -2070,6 +2200,10 @@ async function main() {ensurePluginOnlyOperationArgs();await selectWorkdir();+ if (showCurrentVersion) {+ await printCurrentVersionInfo();+ return;+ }if (rollbackLastUpgrade) {info(tr("Mode: rollback last plugin upgrade", "模式: 回滚最近一次插件升级"));if (pluginVersionExplicit) {diff --git a/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh b/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.shindex e26ebaaca..343544dfc 100644--- a/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh+++ b/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh@@ -93,10 +93,13 @@ if [ ! -f "${CONFIG_FILE}" ]; thenexit 1fi-OC_ENV=()-if [ "${OPENCLAW_DIR}" != "${HOME_DIR}/.openclaw" ]; then- OC_ENV=(env OPENCLAW_STATE_DIR="${OPENCLAW_DIR}")-fi+run_openclaw() {+ if [ "${OPENCLAW_DIR}" != "${HOME_DIR}/.openclaw" ]; then+ OPENCLAW_STATE_DIR="${OPENCLAW_DIR}" openclaw "$@"+ else+ openclaw "$@"+ fi+}info "OpenClaw 目录:${OPENCLAW_DIR}"info "配置文件:${CONFIG_FILE}"@@ -107,7 +110,7 @@ echo ""# Step 1: 停止 OpenClaw gateway# ============================================================info "Step 1: 停止 OpenClaw gateway..."-if "${OC_ENV[@]}" openclaw gateway stop 2>/dev/null; then+if run_openclaw gateway stop 2>/dev/null; theninfo "gateway 已停止"elsewarn "gateway 可能未在运行,继续..."@@ -250,7 +253,7 @@ echo ""# Step 4: 恢复 OpenClaw memory 为 memory-core# ============================================================info "Step 4: 恢复 OpenClaw memory 为 memory-core..."-"${OC_ENV[@]}" openclaw plugins enable memory-core >/dev/null+run_openclaw plugins enable memory-core >/dev/nullinfo "已执行:openclaw plugins enable memory-core"echo ""