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
docs(openclaw-plugin): add health check tools guide (#1326)
mrj666f6a4b4e3a785
diff --git a/examples/openclaw-plugin/INSTALL-AGENT.md b/examples/openclaw-plugin/INSTALL-AGENT.mdindex 39831c932..66207b61b 100644--- a/examples/openclaw-plugin/INSTALL-AGENT.md+++ b/examples/openclaw-plugin/INSTALL-AGENT.md@@ -175,6 +175,16 @@ OpenViking service log, default local path:cat ~/.openviking/data/log/openviking.log```+### Pipeline Health Check (Optional)++If the checks above all pass and you want to further verify the full Gateway → OpenViking pipeline, run the health check script:++```bash+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py+```++This injects a real conversation through Gateway and verifies from the OpenViking side that the session was captured, committed, archived, and had memories extracted. See [health_check_tools/HEALTHCHECK.md](./health_check_tools/HEALTHCHECK.md) for full details.+### Start commandsLocal mode:diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.mdindex 7a3282560..4ca32b88e 100644--- a/examples/openclaw-plugin/INSTALL-ZH.md+++ b/examples/openclaw-plugin/INSTALL-ZH.md@@ -179,6 +179,16 @@ cat ~/.openviking/data/log/openviking.logov-install --current-version```+### 链路检查(可选)++如果上述验证都正常,还想进一步确认从 Gateway 到 OpenViking 的完整链路是否通畅,可以使用插件自带的健康检查脚本:++```bash+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py+```++该脚本会进行一次真实的对话注入,然后从 OpenViking 侧验证会话是否被正确捕获、提交、归档并提取出记忆。详细说明见 [health_check_tools/HEALTHCHECK-ZH.md](./health_check_tools/HEALTHCHECK-ZH.md)。+## 卸载只卸载 OpenClaw 插件、保留 OpenViking 运行时:diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.mdindex 9f87d8228..785fb761b 100644--- a/examples/openclaw-plugin/INSTALL.md+++ b/examples/openclaw-plugin/INSTALL.md@@ -186,6 +186,16 @@ Check installed versions:ov-install --current-version```+### Pipeline Health Check (Optional)++If the steps above all look good and you want to further verify the full Gateway → OpenViking pipeline, run the plugin's health check script:++```bash+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py+```++This script injects a real conversation through Gateway and then verifies from the OpenViking side that the session was captured, committed, archived, and had memories extracted. See [health_check_tools/HEALTHCHECK.md](./health_check_tools/HEALTHCHECK.md) for full details.+## UninstallTo remove only the OpenClaw plugin and keep the OpenViking runtime:diff --git a/examples/openclaw-plugin/health_check_tools/HEALTHCHECK-ZH.md b/examples/openclaw-plugin/health_check_tools/HEALTHCHECK-ZH.mdindex 78c9fea4c..b2e045dee 100644--- a/examples/openclaw-plugin/health_check_tools/HEALTHCHECK-ZH.md+++ b/examples/openclaw-plugin/health_check_tools/HEALTHCHECK-ZH.md@@ -10,6 +10,41 @@ python examples/openclaw-plugin/ov-healthcheck.py只依赖 Python 标准库。地址和 token 会从 `openclaw.json` 自动读取。+## 前置要求++### 必须启用 Gateway HTTP 端点++Phase 1 对话注入依赖 Gateway 的 `/v1/responses` 接口,该接口**默认关闭**,需要在 `openclaw.json` 中启用:++```json+{+ "gateway": {+ "http": {+ "endpoints": {+ "chatCompletions": {+ "enabled": true+ },+ "responses": {+ "enabled": true+ }+ }+ }+ }+}+```++启用后重启 Gateway 使配置生效:++```bash+openclaw gateway restart+```++若未启用,Phase 1 会失败并报错:++```+[FAIL] Chat turn 1 failed (POST http://127.0.0.1:18789/v1/responses failed with HTTP 404: Not Found)+```+## 期望输出正常运行结果如下:@@ -127,6 +162,29 @@ cat ~/.openviking/ov.conf检查 `storage.workspace/log/openviking.log`。+### `Chat turn 1 failed (POST /v1/responses failed with HTTP 404: Not Found)`++这是最常见的 Phase 1 失败原因。Gateway 的 `/v1/responses` 和 `/v1/chat/completions` 接口**默认关闭**,需要在 `openclaw.json` 的 `gateway.http.endpoints` 下启用:++```json+{+ "gateway": {+ "http": {+ "endpoints": {+ "chatCompletions": { "enabled": true },+ "responses": { "enabled": true }+ }+ }+ }+}+```++重启 Gateway:++```bash+openclaw gateway restart+```+### `Probe session not found in OpenViking`会话已发出但插件未写入 OpenViking。@@ -168,9 +226,10 @@ curl "http://127.0.0.1:<端口>/api/v1/sessions/<session_id>/context?token_budge## 建议排查顺序-1. 检查 `plugins.slots.contextEngine` 是否为 `openviking`-2. 检查 Gateway `/health`-3. 检查 OpenViking `/health`-4. 看 `openclaw logs --follow`-5. 看 OpenViking 日志-6. 看脚本输出里失败的具体阶段+1. 确认已按前置要求启用 `gateway.http.endpoints`+2. 检查 `plugins.slots.contextEngine` 是否为 `openviking`+3. 检查 Gateway `/health`+4. 检查 OpenViking `/health`+5. 看 `openclaw logs --follow`+6. 看 OpenViking 日志+7. 看脚本输出里失败的具体阶段diff --git a/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md b/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.mdindex 7cf98efe9..e5409f8d6 100644--- a/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md+++ b/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md@@ -10,6 +10,41 @@ python examples/openclaw-plugin/ov-healthcheck.pyNo extra dependencies — standard library only. Addresses and tokens are auto-discovered from `openclaw.json`.+## Prerequisites++### Gateway HTTP Endpoints Must Be Enabled++Phase 1 conversation injection requires the Gateway's `/v1/responses` endpoint, which is **disabled by default**. Enable it in `openclaw.json`:++```json+{+ "gateway": {+ "http": {+ "endpoints": {+ "chatCompletions": {+ "enabled": true+ },+ "responses": {+ "enabled": true+ }+ }+ }+ }+}+```++Restart Gateway to apply:++```bash+openclaw gateway restart+```++Without this, Phase 1 will fail with:++```+[FAIL] Chat turn 1 failed (POST http://127.0.0.1:18789/v1/responses failed with HTTP 404: Not Found)+```+## Expected OutputA successful run looks like this:@@ -127,6 +162,29 @@ cat ~/.openviking/ov.confCheck `storage.workspace/log/openviking.log` for errors.+### `Chat turn 1 failed (POST /v1/responses failed with HTTP 404: Not Found)`++The most common Phase 1 failure. Gateway's `/v1/responses` and `/v1/chat/completions` endpoints are **disabled by default**. Enable them under `gateway.http.endpoints` in `openclaw.json`:++```json+{+ "gateway": {+ "http": {+ "endpoints": {+ "chatCompletions": { "enabled": true },+ "responses": { "enabled": true }+ }+ }+ }+}+```++Restart Gateway:++```bash+openclaw gateway restart+```+### `Probe session not found in OpenViking`The conversation completed but the plugin did not persist it.@@ -168,9 +226,10 @@ This is `INFO`, not a failure. If fresh-session recall answers correctly, the pi## Recommended Debug Order-1. Check `plugins.slots.contextEngine` is `openviking`-2. Check Gateway `/health`-3. Check OpenViking `/health`-4. Check `openclaw logs --follow`-5. Check OpenViking log-6. Look at the specific failed phase in script output+1. Confirm `gateway.http.endpoints` is configured as described in Prerequisites+2. Check `plugins.slots.contextEngine` is `openviking`+3. Check Gateway `/health`+4. Check OpenViking `/health`+5. Check `openclaw logs --follow`+6. Check OpenViking log+7. Look at the specific failed phase in script output