OpenViking OpenClaw 插件 Recall Trace 召回可观测实践：从配置、工具到 Gateway API 的完整排障指南

OpenViking OpenClaw 插件 Recall Trace 召回可观测实践：从配置、工具到 Gateway API 的完整排障指南

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

本文面向插件使用者、集成方与排障同学，完整讲解 OpenViking OpenClaw 插件中召回可观测能力 Recall Trace 的启用配置、数据模型、Agent 工具、Slash 命令、Gateway HTTP API 与典型排障路径。读完你将掌握：如何打开 trace 记录、如何用一条命令定位“为什么没有召回”“为什么结果不符合预期”，以及如何理解内存环形缓存与 JSONL 持久化两条查询链路。

1. Recall Trace 是什么

Recall Trace 是 OpenViking 插件的召回可观测能力：启用后，插件会把每一次自动召回（auto recall）、显式记忆召回（memory recall）、资源搜索（ov_search）、归档搜索（ov_archive_search）记录成结构化 trace，让“这轮到底查了什么、查到了什么、为什么没查出来”不再是黑盒。

核心实现位于 recall-trace.ts，插件注册阶段通过 openviking-runtime-state.ts 创建RecallTraceRecorder，其围绕四个问题展开：

• 本轮到底搜索了哪些范围：resource、user、agent？
• 每个范围请求的目标 URI、limit、阈值和耗时是多少？
• 候选结果有哪些？最终哪些被注入 prompt 或展示给用户？
• 为什么没有召回：没有 session 上下文、低于分数阈值、预算不足，还是搜索失败？

此外，启用持久化后，即便 Gateway 重启，也能从 JSONL 文件查到近期 trace。

2. 启用方式与配置项

2.1 最小启用配置

关键点：必须显式设置traceRecall: true。只配置recallResources或recallTargetTypes只会改变召回范围，不会启用 trace 记录。

{ "plugins": { "entries": { "openviking": { "config": { "traceRecall": true } } } } }

traceRecall在配置解析中只有等于布尔值true才会启用（见 config.ts 的cfg.traceRecall === true）；插件注册阶段也只有启用后才创建RecallTraceRecorder（见 openviking-runtime-state.ts）。若未启用，查询接口返回空结果并带traceRecall is disabledwarning（见 openviking-recall-trace-runtime.ts）。

2.2 推荐排障配置

{ "plugins": { "entries": { "openviking": { "config": { "traceRecall": true, "traceRecallPersist": true, "traceRecallDir": "~/.openclaw/openviking/recall-traces", "traceRecallRetentionDays": 14, "traceRecallMaxEntries": 1000, "traceRecallMaxResultsPerSearch": 20, "traceRecallPreviewChars": 240, "traceRecallQueryMaxChars": 4000, "traceRecallQueryMaxDays": 14, "recallTargetTypes": ["user", "agent", "resource"] } } } } }

2.3 Trace 配置项一览

下表所有默认值均来自 config.ts 的常量定义，解析逻辑在 config.ts：

其中traceRecallDir在写入时会自动mkdir -p创建目录（见 recall-trace.ts）；traceRecallQueryMaxChars的截断由boundTraceQuery实现，并同步设置queryTruncated标记（见 openviking-runtime-utils.ts）。

2.4 召回范围配置与 Trace 的关系

Trace 会记录实际召回范围，但召回范围本身由recallTargetTypes/recallResources决定：

目标类型会被解析为 context type 搜索计划；自动召回把该计划合并进一次服务端 context search：

3. Trace 记录来源

四种来源覆盖插件内全部召回路径：

从源码实现看，自动召回的 trace 记录遵循“诊断尽力而为”原则：注释明确说明“Trace persistence is diagnostic best-effort; never put JSONL flush latency on the auto-recall critical path”（见 auto-recall.ts），即记录 trace 不会阻塞回复主流程。

4. Trace 数据结构

4.1RecallTraceEntry

RecallTraceEntry的完整类型定义在 recall-trace.ts。

4.2searches[]

字段定义见 recall-trace.ts。

4.3results[]

字段定义见 recall-trace.ts。

4.4selected[]

字段定义见 recall-trace.ts。

4.5 返回示例

{ "schemaVersion": "1.0", "traceId": "ov_search-1780329600000-a1b2c3d4", "ts": 1780329600000, "sessionId": "test-session", "sessionKey": "agent:main:example", "ovSessionId": "8d6e...", "agentId": "main", "source": "ov_search", "operationType": "semantic_find", "resourceTypes": ["resource"], "trigger": { "query": "OpenViking trace API" }, "searches": [ { "resourceType": "resource", "targetUriInput": "viking://resources", "targetUriResolved": "viking://resources", "limit": 20, "scoreThreshold": 0, "durationMs": 35, "total": 1, "results": [ { "uri": "viking://resources/project/spec.md", "resourceType": "resource", "score": 0.88, "abstractPreview": "Recall trace design spec", "resultType": "resource" } ] } ], "selected": [ { "uri": "viking://resources/project/spec.md", "resourceType": "resource", "score": 0.88, "abstractPreview": "Recall trace design spec", "displayed": true } ], "stats": { "candidateCount": 1, "selectedCount": 1, "injectedCount": 0 } }

5. Agent 工具：ov_recall_trace

5.1 用途

ov_recall_trace用于在 Agent 内部查询已记录的 trace。它不会重新调用 OpenViking 搜索接口，只查询插件记录；仅当传入includeContent: true或配置了traceRecallIncludeContentByDefault: true时，才会额外调用 OpenVikingread给 selected 结果补充内容预览。工具注册见 openviking-recall-trace-tools.ts。

5.2 参数

参数类型定义见 openviking-recall-trace-tools.ts：

当前接口不支持自由文本模糊查询 trace trigger。需要按source、sessionId、ovSessionId、resourceTypes、traceId或时间范围过滤。

5.3 调用示例

查询当前 session 最新一条 trace：

{ "turn": "latest" }

查询当前 session 内最近 10 条ov_searchtrace：

{ "turn": "all", "source": "ov_search", "limit": 10 }

查询某条 trace 并补充 selected 内容预览：

{ "traceId": "ov_search-1780329600000-a1b2c3d4", "includeContent": true }

按时间范围和召回类型查询：

{ "turn": "all", "resourceTypes": ["user"], "since": 1780320000000, "until": 1780406399999, "limit": 50 }

5.4 返回值

工具返回 OpenClaw ToolResult：

{ "content": [ { "type": "text", "text": "## Trace 1: ov_search\ntraceId: ...\nquery: ..." } ], "details": { "action": "queried", "count": 1, "lookupLayer": "memory", "warnings": [], "entries": [] } }

6. Slash 命令：/ov-recall-trace

6.1 用途

用户可以在 OpenClaw 会话中直接执行/ov-recall-trace查询 trace。命令注册见 openviking-command-definitions.ts。

6.2 参数

Slash 命令使用--kebab-case参数，解析逻辑parseRecallTraceCommandArgs见 openviking-command-definitions.ts：

6.3 示例

/ov-recall-trace --turn all --source auto_recall --limit 5

/ov-recall-trace --trace-id ov_search-1780329600000-a1b2c3d4 --include-content

/ov-recall-trace --turn all --resource-types user,agent --since 1780320000000 --until 1780406399999

6.4 返回值

Slash 命令返回：

{ "text": "## Trace 1: auto_recall\ntraceId: ...", "details": { "count": 1, "lookupLayer": "memory", "warnings": [], "entries": [] } }

返回结构与ov_recall_trace的details基本一致；text是人类可读摘要，details.entries是机器可读数据。

7. Gateway HTTP API

插件 service 启动时会尝试注册 Recall Trace Gateway 路由（见 openviking-services.ts）。如果当前 Gateway 不支持 route adapter，日志会提示使用ov_recall_trace工具或/ov-recall-trace命令替代。路由定义集中在 recall-trace-routes.ts，除了本文讲解的列表与单条查询外，还提供/api/openviking/recall-traces/latest-ov-search-list与/api/openviking/uri-detail两个辅助端点。

7.1GET /api/openviking/recall-traces

用途

查询多条 trace。路由 handler 见 openviking-recall-trace-runtime.ts。

Query 参数

请求示例

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?turn=all&source=ov_search&limit=10'

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?turn=all&resourceTypes=user,agent&since=1780320000000&until=1780406399999'

返回值

Handler 返回：

{ "status": 200, "body": { "ok": true, "entries": [], "lookupLayer": "memory", "warnings": [] } }

根据 Gateway 适配层，客户端通常会看到body中的 JSON：

{ "ok": true, "entries": [], "lookupLayer": "memory", "warnings": [] }

7.2GET /api/openviking/recall-traces/:traceId

用途

按traceId查询单条 trace。实现上该路由把 path 参数转换为列表接口的traceIdquery 后复用同一 handler（见 recall-trace-routes.ts）。

Path 参数

Query 参数

除traceId外，支持与列表接口相同的 query 参数，例如includeContent=true。

请求示例

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces/ov_search-1780329600000-a1b2c3d4?includeContent=true'

返回值

{ "ok": true, "entries": [ { "traceId": "ov_search-1780329600000-a1b2c3d4", "source": "ov_search" } ], "lookupLayer": "memory", "warnings": [] }

8. 查询与存储行为

8.1 内存 Ring Buffer

RecallTraceMemoryStore保存最近 N 条 trace，N 由traceRecallMaxEntries控制。从源码看（recall-trace.ts）：

• 超出容量时删除最旧记录（entries.shift()）。
• 查询时先按traceId、source、sessionId、sessionKey、ovSessionId、since/until、resourceTypes过滤，再按ts降序排序。
• turn: 'latest'返回过滤结果中最新一条；turn: 'all'返回最多limit条。

8.2 JSONL 持久化

启用traceRecallPersist: true后，每条 trace 会追加到traceRecallDir/YYYY-MM-DD.jsonl（RecallTraceJsonlStore.append见 recall-trace.ts）：

• 文件名使用 trace 的 UTC 日期（jsonlFileNameForTimestamp）。
• 默认不会持久化trigger.rawUserTextPreview，除非设置traceRecallIncludeRawUserPreview: true（见 recall-trace.ts 的entryForPersistence）。
• 写入新 trace 时会同步清理超过traceRecallRetentionDays的旧 JSONL 文件（pruneExpiredFiles）。
• 查询时如果内存命中，直接返回内存结果；只有内存未命中且存在持久化 store，才 fallback 扫描 JSONL（queryWithFallback见 recall-trace.ts）。
• JSONL 中的损坏行会被跳过，并返回 warning（见 recall-trace.ts）；每条记录写入前还会经过isRecallTraceEntry结构校验。

8.3includeContent行为

默认 trace 只保存摘要预览，不读取完整内容。查询时开启includeContent后，插件会对每个selected[].uri调用 OpenViking read，并把结果压缩到selected[].contentPreview（见 openviking-recall-trace-runtime.ts）；若读取失败，会在该 item 上写入readError并在warnings中补充原因。

建议只在定位具体 trace 时使用includeContent，避免一次查询大量 trace 触发额外读请求。

9. 常见使用场景

9.1 解释为什么自动召回没有注入记忆

1. 打开 trace：traceRecall: true。
2. 复现一轮会话。
3. 查询最新自动召回：

/ov-recall-trace --source auto_recall

重点查看：

• searches[].error是否有搜索失败。
• searches[].total是否为 0。
• stats.candidateCount、stats.selectedCount、stats.injectedCount是否逐步变少。
• trigger.queryTruncated是否为 true。

9.2 查看显式memory_recall查了哪些空间

/ov-recall-trace --turn all --source memory_recall --limit 5

重点查看resourceTypes和searches[].targetUriResolved，确认是否默认查了viking://user/memories与agent recall target，或是否按请求resourceTypes改变范围。

9.3 排查/ov-search或ov_search为什么结果不符合预期

/ov-recall-trace --turn all --source ov_search --include-content --limit 3

重点查看：

• trigger.query是否与预期一致。
• searches[].targetUriInput是否是正确资源目录。
• results[]候选是否包含预期文档但未进入selected[]。
• selected[].contentPreview是否能读到真实内容。

9.4 排查归档搜索没有命中

/ov-recall-trace --turn all --source ov_archive_search --limit 5

重点查看：

• operationType是否为archive_grep。
• searches[].targetUriResolved是否指向正确 session archive。
• searches[].caseInsensitive是否为 true。
• stats.candidateCount与selected[].line。

10. 错误与排障

11. 测试覆盖与二次开发注意点

相关单元测试集中在：

• tests/ut/recall-trace.test.ts：覆盖召回类型归一化、搜索计划、内存 ring buffer、JSONL 持久化、隐私控制（如“不持久化原始用户预览”“JSONL 追加失败时内存仍可查询”“先查内存再 fallback 持久化”等场景，测试见RecallTraceMemoryStore/RecallTraceJsonlStore/RecallTraceRecorder三个 describe 块）。
• tests/ut/tools.test.ts：ov_recall_trace工具、Slash 命令、Gateway 路由、includeContent、显式召回 trace、查询不重新触发搜索。

建议修改 trace 行为后至少运行：

npm run typecheck npm test -- tests/ut/recall-trace.test.ts tests/ut/tools.test.ts

12. 快速参考

开启 trace

{ "traceRecall": true, "traceRecallPersist": true }

查最新 trace

/ov-recall-trace

查最近 10 条自动召回

/ov-recall-trace --turn all --source auto_recall --limit 10

查指定 trace 详情

/ov-recall-trace --trace-id <traceId> --include-content

HTTP 查询

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?turn=all&source=memory_recall&limit=10'

HTTP 查询单条

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces/<traceId>?includeContent=true'

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking