volcengine · qin-ctx · Apr 9, 2026 · Apr 9, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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