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配置项类型默认值取值/限制说明traceRecallbooleanfalse必须为true才启用总开关关闭时不记录 trace查询接口返回空并带traceRecall is disabledwarningtraceRecallPersistbooleanfalsetrue/false是否写入本地 JSONL关闭时只保留内存环形缓存traceRecallDirstring~/.openclaw/openviking/recall-traces支持~展开JSONL 文件目录按 UTC 日期写入YYYY-MM-DD.jsonlexpandHomeDir处理见 recall-trace.tstraceRecallRetentionDaysnumber141到3650写入新 trace 时清理超过保留期的 JSONL 文件traceRecallLoadRecentDaysnumber20到3650配置已解析保留当前查询路径主要通过内存 持久化 fallback 获取数据traceRecallMaxEntriesnumber10001到1000000内存 ring buffer 最大条数超出后淘汰最旧记录traceRecallMaxResultsPerSearchnumber201到1000每次子搜索最多保存多少候选结果摘要traceRecallPreviewCharsnumber24020到10000候选摘要、选中摘要的预览字符数traceRecallQueryMaxCharsnumber4000200到200000trace 中保存的 trigger query 最大长度超出会截断并设置queryTruncatedtraceRecallQueryMaxDaysnumber141到3650查询持久化 trace 且未传since/until时最多扫描最近多少天traceRecallIncludeContentByDefaultbooleanfalsetrue/false查询 trace 时是否默认读取 selected URI 的内容预览也可通过查询参数includeContent单次开启traceRecallIncludeRawUserPreviewbooleanfalsetrue/false是否允许把原始用户输入预览持久化到 JSONL默认会脱敏删除其中traceRecallDir在写入时会自动mkdir -p创建目录见 recall-trace.tstraceRecallQueryMaxChars的截断由boundTraceQuery实现并同步设置queryTruncated标记见 openviking-runtime-utils.ts。2.4 召回范围配置与 Trace 的关系Trace 会记录实际召回范围但召回范围本身由recallTargetTypes/recallResources决定配置默认/行为说明recallTargetTypes默认[user, agent]允许值resource、user、agent空值回退默认集合常量见 config.tsrecallResources默认false兼容旧配置仅在未显式配置recallTargetTypes时把resource追加到默认召回集合目标类型会被解析为 context type 搜索计划自动召回把该计划合并进一次服务端 context searchresourceTypecontext type说明resourceresource资源库。usermemory当前用户长期记忆。agentmemory当前 actor 的长期记忆与user合并为一个 memory context type由 actor routing 限定范围。3. Trace 记录来源四种来源覆盖插件内全部召回路径sourceoperationType触发方式selected 语义关键实现auto_recallsemantic_find兼容值Context Engine 在回复前发起服务端 context search服务端组装并注入relevant-memories的记忆或资源injected: trueauto-recall.ts 的buildAutoRecallContext()memory_recallsemantic_findAgent 调用memory_recall工具工具返回给模型的记忆通常injected: true且displayed: trueopenviking-memory-recall-tools.tsov_searchsemantic_findAgent 调用ov_search工具或用户执行/ov-search搜索结果列表中展示的资源/技能/记忆displayed: truetrace 记录在 openviking-query-runtime.ts 的searchOpenViking流程中ov_archive_searcharchive_grepAgent 调用ov_archive_search工具展示的归档匹配行包含linedisplayed: trueopenviking-archive-tools.ts从源码实现看自动召回的 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.1RecallTraceEntryRecallTraceEntry的完整类型定义在 recall-trace.ts。字段类型说明schemaVersion1.0Trace schema 版本。traceIdstringTrace 唯一 ID通常形如source-timestamp-random。tsnumberUnix timestamp毫秒。sessionIdstring?OpenClaw session ID。sessionKeystring?OpenClaw session key。ovSessionIdstring?映射后的 OpenViking session ID。agentIdstring?实际发送到 OpenViking 的 agent ID。sourceenumauto_recall、memory_recall、ov_search、ov_archive_search。operationTypeenumsemantic_find或archive_grep。resourceTypesarray本次 trace 覆盖的召回类型resource、user、agent。trigger.querystring触发搜索的查询文本受traceRecallQueryMaxChars限制。trigger.derivedKeywordsstring[]?派生关键词归档搜索通常保存原 query。trigger.rawUserTextPreviewstring?原始用户输入预览默认不持久化。trigger.queryTruncatedboolean?query是否因过长被截断。searchesarray本次 trace 中每个逻辑 context type 的搜索明细。selectedarray最终被注入或展示的结果。statsobject候选数、选中数、注入数、估算 token。4.2searches[]字段定义见 recall-trace.ts。字段类型说明resourceTyperesource|user|agent|archive当前子搜索类型。targetUriInputstring?输入或计划中的目标 URI。targetUriResolvedstring?解析后的目标 URI。limitnumber请求 limit。自动召回直接使用recallLimit显式memory_recall可先扩大候选数。scoreThresholdnumber?分数阈值。自动召回由服务端应用显式memory_recall仍可在本地后处理。durationMsnumber子搜索耗时毫秒。totalnumberOpenViking 返回或插件统计的候选总数。resultsarray候选结果摘要最多traceRecallMaxResultsPerSearch条。archiveIdstring?归档搜索指定 archive 时存在。caseInsensitiveboolean?归档 grep 是否大小写不敏感。errorstring?子搜索失败或跳过原因。4.3results[]字段定义见 recall-trace.ts。字段类型说明uristring候选 URI。resourceTypestring?候选类型。归档匹配为archive。categorystring?OpenViking 返回的分类。scorenumber?相似度分数。levelnumber?OpenViking memory 层级插件优先选 leaf memory。abstractPreviewstring?摘要预览。resultTypeenummemory、resource、skill、archive_match。4.4selected[]字段定义见 recall-trace.ts。字段类型说明uristring选中结果 URI。resourceTypestring?选中结果类型。categorystring?分类。scorenumber?分数。linenumber?归档匹配所在行号。abstractPreviewstring?选中结果摘要预览。contentPreviewstring?仅当查询时开启includeContent并成功读取 URI 内容后出现。readErrorstring?开启includeContent但读取内容失败时出现。injectedboolean?是否注入模型上下文。displayedboolean?是否展示给用户或工具调用结果。skippedReasonenum?预留跳过原因score_threshold、dedupe、non_leaf、budget、not_top_k、search_error。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_trace5.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参数类型默认值说明turnlatest|alllatestlatest只返回过滤后最新 1 条all返回最多limit条。traceIdstring无精确查询某条 trace。sessionIdstring当前 session按 OpenClaw session ID 过滤未传时默认当前工具上下文 session。sessionKeystring无按 OpenClaw session key 过滤。ovSessionIdstring当前 session 映射值按 OpenViking session ID 过滤。sourcestring无auto_recall、memory_recall、ov_search、ov_archive_search。resourceTypesstring[] 或逗号分隔 string无按 trace 的resourceTypes过滤允许resource、user、agent。sincenumber无毫秒时间戳下界包含。untilnumber无毫秒时间戳上界包含。includeContentbooleanfalse是否读取 selected URI 的内容预览可能带来额外读请求。limitnumber20最大返回条数仅turn: all时返回多条。当前接口不支持自由文本模糊查询 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: [] } }字段说明content[0].text人类可读摘要由formatRecallTraceText生成见 openviking-recall-trace-runtime.ts展示traceId、query、resourceTypes、stats 及 selected URI 与分数百分比。details.count本次返回条数。details.lookupLayermemory表示来自内存环形缓存persistent表示内存未命中后从 JSONL 文件 fallback 查询。details.warnings读取 JSONL 或 selected 内容失败等 warning。details.entries完整结构化 trace 数组。6. Slash 命令/ov-recall-trace6.1 用途用户可以在 OpenClaw 会话中直接执行/ov-recall-trace查询 trace。命令注册见 openviking-command-definitions.ts。6.2 参数Slash 命令使用--kebab-case参数解析逻辑parseRecallTraceCommandArgs见 openviking-command-definitions.ts参数对应工具参数示例--turnturn--turn all--trace-idtraceId--trace-id ov_search-1780329600000-a1b2c3d4--session-idsessionId--session-id test-session--session-keysessionKey--session-key agent:main:xxx--ov-session-idovSessionId--ov-session-id 8d6e...--sourcesource--source auto_recall--resource-typesresourceTypes--resource-types user,agent--sincesince--since 1780320000000--untiluntil--until 1780406399999--include-contentincludeContent--include-content--limitlimit--limit 206.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 17804063999996.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 参数参数类型默认值说明turnlatest|alllatest是否只返回最新一条。traceIdstring无精确过滤 trace ID。sessionIdstring无OpenClaw session ID。sessionKeystring无OpenClaw session key。ovSessionIdstring无OpenViking session ID。sourcestring无auto_recall、memory_recall、ov_search、ov_archive_search。resourceTypesstring无逗号或换行分隔如user,agent。sincenumber无毫秒时间戳下界。untilnumber无毫秒时间戳上界。includeContentboolean/string配置默认值支持1、true、yes。limitnumber20最大返回条数。请求示例curl http://127.0.0.1:gateway-port/api/openviking/recall-traces?turnallsourceov_searchlimit10curl http://127.0.0.1:gateway-port/api/openviking/recall-traces?turnallresourceTypesuser,agentsince1780320000000until1780406399999返回值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 参数参数类型说明traceIdstring需要查询的 trace ID。Query 参数除traceId外支持与列表接口相同的 query 参数例如includeContenttrue。请求示例curl http://127.0.0.1:gateway-port/api/openviking/recall-traces/ov_search-1780329600000-a1b2c3d4?includeContenttrue返回值{ ok: true, entries: [ { traceId: ov_search-1780329600000-a1b2c3d4, source: ov_search } ], lookupLayer: memory, warnings: [] }8. 查询与存储行为8.1 内存 Ring BufferRecallTraceMemoryStore保存最近 N 条 traceN 由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.jsonlRecallTraceJsonlStore.append见 recall-trace.ts文件名使用 trace 的 UTC 日期jsonlFileNameForTimestamp。默认不会持久化trigger.rawUserTextPreview除非设置traceRecallIncludeRawUserPreview: true见 recall-trace.ts 的entryForPersistence。写入新 trace 时会同步清理超过traceRecallRetentionDays的旧 JSONL 文件pruneExpiredFiles。查询时如果内存命中直接返回内存结果只有内存未命中且存在持久化 store才 fallback 扫描 JSONLqueryWithFallback见 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 解释为什么自动召回没有注入记忆打开 tracetraceRecall: true。复现一轮会话。查询最新自动召回/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. 错误与排障现象可能原因排查/解决查询为空且 warning 包含traceRecall is disabled未配置traceRecall: true显式启用traceRecall重启 Gateway 后复现。配了recallTargetTypes但没有 trace召回范围配置不等于 trace 开关同时设置traceRecall: true。Gateway 路由不可用当前 Gateway 未提供registerRouteadapter使用 Agent 工具ov_recall_trace或 Slash 命令/ov-recall-trace。重启后查不到历史 trace未开启traceRecallPersist或超过traceRecallQueryMaxDays查询窗口开启持久化必要时传since/until或调大traceRecallQueryMaxDays。includeContent后有readErrorselected URI 已不可读、权限不足或 OpenViking read 失败查看warnings与selected[].readError再用ov_read验证 URI。JSONL 查询有 corrupted warning持久化文件存在损坏行插件会跳过损坏行返回有效记录可检查对应YYYY-MM-DD.jsonl。11. 测试覆盖与二次开发注意点相关单元测试集中在tests/ut/recall-trace.test.ts覆盖召回类型归一化、搜索计划、内存 ring buffer、JSONL 持久化、隐私控制如“不持久化原始用户预览”“JSONL 追加失败时内存仍可查询”“先查内存再 fallback 持久化”等场景测试见RecallTraceMemoryStore/RecallTraceJsonlStore/RecallTraceRecorder三个 describe 块。tests/ut/tools.test.tsov_recall_trace工具、Slash 命令、Gateway 路由、includeContent、显式召回 trace、查询不重新触发搜索。建议修改 trace 行为后至少运行npm run typecheck npm test -- tests/ut/recall-trace.test.ts tests/ut/tools.test.ts12. 快速参考开启 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-contentHTTP 查询curl http://127.0.0.1:gateway-port/api/openviking/recall-traces?turnallsourcememory_recalllimit10HTTP 查询单条curl http://127.0.0.1:gateway-port/api/openviking/recall-traces/traceId?includeContenttrue【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考