OpenViking 插件链路端到端健康检查实战ov-healthcheck.py 五阶段验证方案【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingov-healthcheck.py是 OpenViking 仓库中用于端到端验证「OpenClaw OpenViking 插件链路」的零依赖健康检查脚本。它通过一次真实的 Gateway 对话注入受控数据再回到 OpenViking 侧逐阶段核验捕获、commit、归档、记忆抽取与召回结果最终给出可机器判读的 PASS/FAIL 报告。读完本文你将掌握该脚本的完整用法、五阶段工作原理、全部命令行参数、常见故障定位方法以及插件afterTurn/autoRecall/ commit 机制在源码中的真实实现位置。快速开始与前置要求一行命令启动脚本位于 examples/openclaw-plugin/health_check_tools/ov-healthcheck.py只依赖 Python 标准库argparse、urllib、json、uuid等无需 pip 安装任何第三方包。直接从仓库根目录运行python examples/openclaw-plugin/ov-healthcheck.py地址、token、API key 等连接信息会自动发现脚本会依次尝试定位openclaw.json候选路径包括环境变量OPENCLAW_STATE_DIR指向的目录、./config/.openclaw/openclaw.json、~/.openclaw/openclaw.json及~/.openclaw*/openclaw.json通配路径并从中解析 Gateway 地址、bearer token、插件配置plugins.entries.openviking.config、OpenViking 地址与 API key。手动指定时也可以通过命令行参数覆盖详见下文参数表。从源码看自动发现逻辑集中在 discover_openclaw_config 与 guess_gateway_url / guess_openviking_url 三个函数中环境变量OPENVIKING_BASE_URL/OPENVIKING_URL会优先于配置文件生效。必须启用 Gateway HTTP 端点Phase 1 的对话注入依赖 Gateway 的/v1/responses接口该接口默认关闭需要在openclaw.json中显式启用{ gateway: { http: { endpoints: { chatCompletions: { enabled: true }, responses: { enabled: true } } } } }启用后重启 Gateway 使配置生效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)这是最常见的首跑失败原因排障时优先确认此项。脚本的对话注入请求体为{model: openclaw, input: message, user: user_id}见 send_gateway_message所以两个 HTTP 端点至少要开启responses若你还希望通过/v1/chat/completions验证则一并开启chatCompletions。期望输出一条链路的完整证据链一次成功运行的输出大致如下默认 Phase 3 会等待异步 commit最长 300 秒这是正常的——commit 涉及 LLM 调用做归档和记忆抽取OpenViking Plugin Healthcheck Gateway: http://127.0.0.1:18789 OpenViking: http://127.0.0.1:1933 ... [PASS] OpenClaw config discovered (...) [PASS] plugins.slots.contextEngine is openviking [PASS] Gateway health check succeeded [PASS] OpenViking health check succeeded Phase 1: real conversation [PASS] Chat turn 1 succeeded (reply_len151) [PASS] Chat turn 2 succeeded (reply_len131) [PASS] Chat turn 3 succeeded (reply_len115) [PASS] Chat turn 4 succeeded (reply_len77) Phase 2: OpenViking session inspection [PASS] Probe session located in OpenViking (...) [PASS] Captured session context contains the probe marker [PASS] Captured session context contains seeded facts (go,postgresql,redis,70) Phase 3: commit, context, and memory checks [PASS] OpenViking commit accepted (accepted) Waiting up to 300s for commit, archive, and memory extraction... [PASS] Session commit_count is greater than zero (1) [PASS] Memory extraction produced results (total1) [PASS] Context endpoint returned latest_archive_overview Phase 4: follow-up through Gateway [PASS] Same-session follow-up recalled earlier facts (go,postgresql,redis,70) [PASS] Fresh-session recall returned seeded stack facts (...) Phase 5: cleanup [PASS] Deleted synthetic session (...) [PASS] Deleted synthetic memory (viking://user/default/memories/...) Summary PASS20 WARN0 FAIL0 SKIP0 Healthcheck passed.输出中的状态含义PASS— 确认正常INFO— 补充信息不代表异常WARN— 主链路可用但该项未稳定确认FAIL— 明确故障脚本最终返回非 0 退出码SKIP— 按配置跳过的检查如autoRecall关闭时的新会话召回项。工作原理Probe 标记与五阶段验证脚本的核心思路是「注入一组受控对话 → 追踪其在系统中的流转 → 逐环节断言」。为保证不污染真实用户数据每次运行都会生成一个唯一随机 probe 标记如probe-a1b2c3d4嵌入第一条消息后续所有查找都以它为准绳。从源码看probe 及其派生事实由 HealthcheckRunFacts 与 build_run_facts 统一管理除了 probe 本身还会从 probe token 派生出debug_taghc-token、用户名Lin Zhou tag、项目名order platform tag、本次运行专属 Kafka topicorder_events_token与 callback hostpayment-cb-token.internal:9443。这些值保证了「本次运行的 artifacts 可以被精确识别」也保证了 fresh-session 召回校验的锚点事实是本次独有的。Phase 1对话注入脚本通过 Gateway/v1/responses接口连续发送 4 条带[OPENVIKING-HEALTHCHECK]前缀与 probe 标记的消息模拟一次真实用户对话。消息正文刻意写成「正常的、值得记忆的对话内容」例如自我介绍与技术栈「My name is Lin Zhou hc-xxxx, I am rebuilding order platform hc-xxxx, my backend stack is Go, PostgreSQL, and Redis, and the current project progress is 70 percent.」种子事实go、postgresql、redis、70补充 Kafka topic 与支付回调服务地址probe 派生值补充库存服务连接池修复细节max_open_conns从 80 调到 160、引入 circuit breaker补充一条会话偏好回答简洁、结论先行并重复 debug tag。消息模板见 build_seed_messages。脚本会校验每一轮都拿到 assistant 回复记录reply_len任一轮失败则中止。Phase 2捕获验证等待一小段时间默认--capture-wait 4秒让插件afterTurn钩子完成写入后脚本查询 OpenViking sessions API逐个扫描 session 的 context寻找 probe 标记。找到标记即证明插件的afterTurn钩子成功把 Gateway 对话写入了 OpenViking。扫描逻辑在 find_session_with_text会先排除memory-store-前缀的系统 session按updated_at倒序排列再逐 session 拉取 context 文本匹配。随后脚本还会从捕获到的 context 中检查种子事实关键词go/postgresql/redis/70至少命中 2 个确认 not just 写入了 session还完整保留了可检索的对话内容。从插件侧源码看这一环节对应的是 OpenClaw context-engine 契约中的afterTurn钩子。在 context-engine.ts 中插件通过afterTurnOpenVikingSession把sessionId、sessionKey、messages、prePromptMessageCount等参数交给服务端执行捕获而autoCapture配置项默认开启控制是否从近期对话中抽取记忆captureModesemantic/keyword则决定抽取策略见 openclaw.plugin.json。Phase 3Commit 与记忆验证脚本通过 OpenViking API 主动触发 commit然后轮询最多--commit-wait秒直到三个条件同时满足commit_count 0— commit 已完成latest_archive_overview存在 — 对话已归档、概要已生成memories_extracted 0— 记忆抽取产生了结果。轮询实现在 wait_for_commit_visibility 中每 5 秒检查一次打印commityes/no overviewyes/no memoryyes/no状态commit 请求本身会先拿到task_id再通过/api/v1/tasks/id轮询任务最终状态见 OpenVikingInspector.commit。这三个条件同时满足才确认「对话归档 → 概要生成 → 记忆抽取」这条异步流水线完整跑通。在真实运行中插件侧同样存在自动 commit 机制commitTokenThresholdRatio默认0.5表示当待处理 token 估算达到模型上下文窗口的该比例时自动触发 commit置 0 则每轮都 commit见 openclaw.plugin.json。健康检查脚本选择显式调用 commit API是为了让验证结果不依赖自动触发的时机。Phase 4召回验证脚本通过 Gateway 再发两个问题分别验证「会话内上下文连续性」与「跨会话记忆召回」同 session 追问沿用同一 user id询问此前对话中的事实检查回复是否包含关键词go、postgresql、redis、70中至少 2 个——验证 session 内的上下文连续性新 session 追问使用全新 user id询问只有通过记忆召回才能获得的事实检查回复是否包含由 probe 派生出的本次运行专属 Kafka topic 与 callback host——验证autoRecall是否在新 session 中正确注入了存储的记忆。召回注入在插件侧由 auto-recall.ts 的buildAutoRecallContext负责它会基于当前对话文本构造查询、调用服务端/search/find取回记忆并受recallLimit默认 6、recallScoreThreshold默认 0.15、recallMaxInjectedChars默认 4000等参数约束autoRecall开关默认开启控制该机制是否生效。Phase 5清理默认情况下脚本会在结束时删除本次运行创建的 synthetic session并只删除当前 user space 下命中本次 run probe 派生事实的 leaf memory。memory root 会通过/api/v1/system/status获取当前运行时 user id再解析viking://user/space/memories见 resolve_user_memory_root。清理判断是双重保险的先通过记忆搜索 API 命中「URI 位于 memory root 内且URI 包含 probe token/debug tag」的记忆再通过文件系统枚举递归兜底跳过profile.md、preferences、.abstract.md、.overview.md等共享摘要文件见 collect_healthcheck_memory_candidates_from_fs。这样连续跑 healthcheck 不会把共享 memory 空间越堆越脏也不会误删混有真实用户信息的共享 memory——像profile.md、preferences、.abstract.md这类共享摘要文件即使含有 synthetic 内容也刻意保留。只有显式传入--keep-artifacts时才会保留现场用于排查。关键词匹配的容错设计脚本不要求模型精确复述。它将模型回复转为小写检查目标关键词中是否至少命中 2 个4 个种子事实命中 2 个、2 个 probe 派生事实命中 2 个实现在 count_keyword_hits。这既容忍了 LLM 的改写与润色又能捕捉到完全性的召回失败。完整参数参考参数默认值说明--gateway url自动Gateway 地址也读环境变量OPENCLAW_GATEWAY_URL--openviking url自动OpenViking 地址--token token自动Gateway bearer token自动从openclaw.json的gateway.auth.token或环境变量OPENCLAW_GATEWAY_TOKEN发现--openviking-api-key key自动OpenViking API key依次从插件apiKey、OpenViking 配置server.root_api_key、环境变量OPENVIKING_API_KEY发现支持${ENV_VAR}占位符解析--actor-peer idmainOpenViking 直连检查请求使用的 actor peer对应请求头X-OpenViking-Actor-Peer也读插件peer_prefix--user-id id随机测试会话的 user id默认ov-healthcheck-8位hex--openclaw-config path自动openclaw.json路径--chat-timeout 秒120每次 Gateway 聊天请求的超时--commit-wait 秒300等待 commit、归档、记忆抽取完成的最大时间--capture-wait 秒4聊天结束后等待 OpenViking 捕获的时间--delay 秒1聊天轮次间隔--session-scan-limit n0全部扫描 session 的上限0 扫描全部--insecure关跳过 SSL 证书验证自签证书场景--keep-artifacts关保留本次运行产生的 synthetic session 和 memory便于调试--strict-warnings关有 WARN 时也返回非 0 退出码--json-out path—输出 JSON 报告每条检查项的状态/标签/详情--verbose/-v关打印调试信息扫描过程、回复预览、等待状态等--json-out输出的 JSON 由 Recorder.write_json 生成每条记录形如{status: PASS, label: ..., detail: ...}适合接入 CI 解析。故障处理手册Gateway health check failedopenclaw gateway status curl http://127.0.0.1:端口/health openclaw logs --follow注意脚本对 Gateway/health的判定接受ok/live/healthy或{ok: true}等形态见 gateway_health若你的 Gateway 健康端点返回结构特殊可先手动 curl 确认。OpenViking health check failedcurl http://127.0.0.1:端口/health cat ~/.openviking/ov.conf检查storage.workspace/log/openviking.log脚本会按 OpenViking 配置中的storage.workspace推导该日志路径见 openviking_log_path。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下启用{ gateway: { http: { endpoints: { chatCompletions: { enabled: true }, responses: { enabled: true } } } } }重启 Gatewayopenclaw gateway restartProbe session not found in OpenViking会话已发出但插件未写入 OpenViking。常见原因插件未加载、autoCapture关闭、路由或写入失败。openclaw config get plugins.slots.contextEngine openclaw config get plugins.entries.openviking.config openclaw logs --followcontextEngineslot 必须为openviking才会把 OpenViking 作为上下文引擎接管脚本也会在启动阶段对这项做显式断言plugins.slots.contextEngine is openviking。Session commit_count is still zero after waitingCommit 是异步的涉及 LLM 调用。如果超时检查 commit 任务是否还在运行curl http://127.0.0.1:端口/api/v1/tasks如果还在运行用--commit-wait 600重跑给足异步时间如果卡住检查storage.workspace/log/openviking.log确认 LLM 后端可达且正常响应Context endpoint has no archive overview after waiting归档概要在 commit 过程中生成。如果 commit 成功但概要缺失curl http://127.0.0.1:端口/api/v1/sessions/session_id/context?token_budget128000如果手动请求也为空问题在 OpenViking 侧如果手动正常检查脚本是否指向了错误实例例如多实例部署时地址被自动发现到别的服务。Fresh-session recall was inconclusive通常不是完全故障。常见原因autoRecall关闭、记忆抽取未完成、模型本轮未命中召回内容。先重跑一次若autoRecall被显式关闭脚本会以SKIP跳过该项并明确提示。Direct backend memory search returned no results这是INFO不是失败。脚本在 Phase 3 末尾会直连 OpenViking/api/v1/search/find搜索 probe 派生的记忆查询user_name kafka_topic callback_service debug_tag拿不到结果只说明直接搜索未命中只要 fresh-session recall 能答对插件链路就是正常的。建议排查顺序确认已按前置要求启用gateway.http.endpoints检查plugins.slots.contextEngine是否为openviking检查 Gateway/health检查 OpenViking/health看openclaw logs --follow看 OpenViking 日志看脚本输出里失败的具体阶段是配置/健康检查、对话注入、捕获、commit、还是召回环节源码延伸把健康检查放进 CIov-healthcheck.py的退出码设计天然适合 CI任何FAIL都会让进程返回 1strict-warnings开启时WARN也会返回 1最终判定逻辑见 main 的收尾。配合--json-out生成结构化报告可以很方便地接入流水线做回归验证。如果你需要更细粒度的链路验证仓库的tests/e2e/目录下还提供了test-memory-chain.py记忆链全流程、test-tool-capture.py工具调用捕获、test-archive-expand.py归档展开等 Python 端到端脚本以及tests/ut/下的 TypeScript 单测如 context-engine-afterTurn.test.ts、context-engine-assemble.test.ts可作为理解插件捕获/归档/召回行为的补充参考资料。小结ov-healthcheck.py用「一次真实对话 五阶段追踪断言」的方式把 OpenClaw 与 OpenViking 之间的捕获afterTurn、commit、归档概要、记忆抽取、召回autoRecall与清理这六条关键路径完整地验证了一遍。掌握它的运行前提、参数语义与失败含义你就能在一分钟内判断整条插件链路是否健康并在出问题时按阶段快速定位到 Gateway、插件配置或 OpenViking 侧的具体环节。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考