Update docs

examples/openclaw-plugin/INSTALL-ZH.md

@@ -2,23 +2,18 @@
 
 通过 [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 界面验证记忆写入的说明，欢迎试用和反馈。
 
-> **⚠️ OpenClaw >= 2026.3.12 兼容性问题**
+> **ℹ️ 历史兼容性说明**
 >
-> OpenClaw `2026.3.12` 及更高版本存在已知兼容性问题，会导致加载插件后对话卡死无响应。
-> 这不是本插件的 bug——根因是 OpenClaw 3.12 的 slug generator（会话自动命名）有硬编码 15s 超时，
-> 当 LLM provider 响应较慢时会逐个 profile 超时重试，阻塞整个会话初始化管线。
-> 此外 3.12 新增的插件信任机制也可能影响本地插件的加载时序。
-> 另一个已知问题：`before_agent_start` 中的 auto-recall 缺少超时保护，可能导致 agent 静默挂起（[#673](https://github.com/volcengine/OpenViking/issues/673)）。
->
-> **临时方案：** 回退到 `2026.3.11`：`npm install -g openclaw@2026.3.11`
->
-> 上游修复 PR：openclaw/openclaw#34673、openclaw/openclaw#33547。
-> 详见 [#591](https://github.com/volcengine/OpenViking/issues/591)。
+> 旧版 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。
 
-> **🚀 插件 2.0 设计中**
+> **🚀 插件 2.0（context-engine 架构）**
 >
-> 我们正在设计基于 context-engine 架构重构的插件 2.0 版本，将作为 OpenViking 接入 AI 编程助手的最佳实践。
-> 欢迎参与讨论：https://github.com/volcengine/OpenViking/discussions/525
+> 当前文档介绍的是基于 context-engine 架构的 OpenViking 插件 2.0 方案，也是 OpenViking 接入 AI 编程助手的推荐实践。
+> 更多背景和演进讨论可见：https://github.com/volcengine/OpenViking/discussions/525
 
 ---
 
@@ -28,7 +23,7 @@
 
 ### 从旧版 `memory-openviking` 升级到新版 `openviking` 前置操作步骤
 
-如果当前环境里已经安装过旧版插件 `memory-openviking`，建议先完成以下前置操作，再执行新版安装，避免旧版和新版插件同时存在。
+如果当前环境里已经安装过旧版插件 `memory-openviking`，建议先完成以下前置操作，再执行新版安装。插件 2.0 与旧版插件/旧版配置不兼容，避免旧版和新版插件同时存在。
 
 1. 停止 OpenClaw gateway：
 

examples/openclaw-plugin/INSTALL.md

@@ -2,24 +2,18 @@
 
 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.
 
-> **⚠️ OpenClaw >= 2026.3.12 Compatibility Issue**
+> **ℹ️ Historical Compatibility Note**
 >
-> OpenClaw `2026.3.12` and later have a known issue that causes conversations to hang after loading the plugin.
-> This is not a bug in our plugin — the root cause is OpenClaw 3.12's slug generator (automatic conversation naming),
-> which has a hardcoded 15s timeout that cascades when the LLM provider responds slowly, blocking the entire
-> session initialization pipeline. Additionally, 3.12's new plugin trust mechanism may affect loading order for
-> locally installed plugins. A separate issue: the `before_agent_start` auto-recall hook lacks timeout protection,
-> which can cause the agent to hang silently ([#673](https://github.com/volcengine/OpenViking/issues/673)).
->
-> **Workaround:** Downgrade to `2026.3.11`: `npm install -g openclaw@2026.3.11`
->
-> Upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.
-> See [#591](https://github.com/volcengine/OpenViking/issues/591) for details.
+> 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 In Design**
+> **🚀 Plugin 2.0 (Context-Engine Architecture)**
 >
-> We are designing Plugin 2.0, rebuilt on the context-engine architecture — the best practice for integrating
-> OpenViking with AI coding assistants. Join the discussion:
+> 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
 
 ---
@@ -30,7 +24,7 @@ Provide long-term memory capabilities for [OpenClaw](https://github.com/openclaw
 
 ### Prerequisite Steps for Upgrading from Legacy `memory-openviking` to New `openviking`
 
-If the current environment already has the legacy `memory-openviking` plugin installed, complete the following prerequisite steps before installing the new version to avoid having both plugins active at the same time.
+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.
 
 1. Stop the OpenClaw gateway:
 

examples/openclaw-plugin/README.md

@@ -2,24 +2,18 @@
 
 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.
 
-> **⚠️ OpenClaw >= 2026.3.12 Compatibility Issue**
+> **ℹ️ Historical Compatibility Note**
 >
-> OpenClaw `2026.3.12` and later have a known issue that causes conversations to hang after loading the plugin.
-> This is not a bug in our plugin — the root cause is OpenClaw 3.12's slug generator (automatic conversation naming),
-> which has a hardcoded 15s timeout that cascades when the LLM provider responds slowly, blocking the entire
-> session initialization pipeline. Additionally, 3.12's new plugin trust mechanism may affect loading order for
-> locally installed plugins. A separate issue: the `before_agent_start` auto-recall hook lacks timeout protection,
-> which can cause the agent to hang silently ([#673](https://github.com/volcengine/OpenViking/issues/673)).
->
-> **Workaround:** Downgrade to `2026.3.11`: `npm install -g openclaw@2026.3.11`
->
-> Upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.
-> See [#591](https://github.com/volcengine/OpenViking/issues/591) for details.
+> 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 In Design**
+> **🚀 Plugin 2.0 (Context-Engine Architecture)**
 >
-> We are designing Plugin 2.0, rebuilt on the context-engine architecture — the best practice for integrating
-> OpenViking with AI coding assistants. Join the discussion:
+> 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
 
 ---
@@ -104,7 +98,7 @@ openclaw --version   # installed
 
 - Python: https://www.python.org/downloads/
 - Node.js: https://nodejs.org/
-- OpenClaw: `npm install -g openclaw@2026.3.11 && openclaw onboard`
+- OpenClaw: `npm install -g openclaw && openclaw onboard`
 
 ---
 
@@ -418,7 +412,8 @@ Open http://127.0.0.1:8020 in your browser.
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| Conversation hangs, no response | OpenClaw >= 2026.3.12 compatibility issue | Downgrade to `2026.3.11`: `npm install -g openclaw@2026.3.11`. See [#591](https://github.com/volcengine/OpenViking/issues/591) |
+| 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 |