diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md index 3548337e..478503a2 100644 --- a/examples/openclaw-plugin/INSTALL-ZH.md +++ b/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： diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.md index 5e1ae750..eab355d1 100644 --- a/examples/openclaw-plugin/INSTALL.md +++ b/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: diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md index 6feee23c..104ffbe4 100644 --- a/examples/openclaw-plugin/README.md +++ b/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 |