Skip to content

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

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.md
index 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 commands
Local mode:
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md
index 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.log
ov-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.md
index 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.
+
## Uninstall
To 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.md
index 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.md
index 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.py
No 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 Output
A successful run looks like this:
@@ -127,6 +162,29 @@ cat ~/.openviking/ov.conf
Check `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