OpenViking 插件查询参数运行期动态配置完全指南RuntimeQueryConfigStore、CLI 与 Gateway API 实战【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本指南以 examples/openclaw-plugin/docs/openviking-dynamic-query-config-test-report.md 为主体结合 OpenViking 仓库中 OpenClaw 插件源码与测试用例撰写。核心场景是在 OpenClaw及 ArkClaw 等兼容宿主中接入 OpenViking 作为上下文数据库时无需重启宿主进程即可在运行期调整自动召回与memory_recall/ov_search工具的召回数量、候选数量、阈值、资源范围和排序权重并支持 claw 与 session 两级粒度。读者读完后将掌握动态查询配置的优先级模型、持久化与热加载机制、/ov-query-config命令用法以及两个新增 Gateway 只读 API 的请求/响应契约。一、为什么需要运行期动态配置OpenViking 插件在默认形态下查询行为完全由plugins.entries.openviking.config中的静态配置决定例如recallLimit、recallScoreThreshold、recallTargetTypes等。这带来三个痛点调整召回策略必须重启 OpenClaw在多租户或长期运行的 Gateway 场景下代价高昂粒度只有全局一档无法针对某个 clawagent或某个 session 做差异化召回排序权重无法运行期调整用户想临时提高偏好类记忆或某个资源类型的权重只能改代码或改静态配置。本次变更的核心目标正是不重启即可调参并形成如下能力矩阵能力说明关键实现位置运行期动态配置新增RuntimeQueryConfigStore负责参数归一化、分层合并、持久化、热加载、异常容错query-config.tsRuntimeQueryConfigStore类定义于 L173分层优先级合并顺序为 request session claw static config default并输出字段来源sourcesquery-config.tsgetEffectiveclaw / session 粒度claw 以agentIdpeerId为 keysession 优先ovSessionId其次sessionId再次sessionKeyquery-config.tsresolveSessionQueryConfigKey自动召回接入assemble 阶段获取有效查询配置传入自动召回链路auto-recall.tsparams.queryConfig参与scoreThreshold/recallLimit/maxInjectedChars/resourceTypes决策显式工具接入memory_recall、ov_search使用运行期有效配置作为默认值请求参数仍可覆盖plugin/openviking-memory-recall-tools.ts排序权重参数化rankingWeights、categoryWeights、resourceTypeWeights参与客户端侧排序memory-ranking.tsCLI 管理入口新增/ov-query-configget/set/unset/resetplugin/openviking-query-config-command.tsGateway URI 详情新增只读详情接口不重新触发搜索plugin/recall-trace-routes.ts路由/api/openviking/uri-detailGateway 最近 ov_search 清单从 recall trace 中扁平化最近一次ov_search结果plugin/openviking-recall-trace-runtime.ts生成detailUrl见 L390二、核心机制RuntimeQueryConfigStoreRuntimeQueryConfigStorequery-config.ts是整套动态配置能力的中枢职责可以概括为四句话归一化入参、按优先级分层合并、内存热更新 文件持久化、异常容错不阻断查询链路。从源码结构看它内部维护三样关键状态data: RuntimeFile内存中的运行期配置快照结构为{ schemaVersion, updatedAt, claws, sessions }loadPromise初始load()的 in-flight 引用写操作set/unset/reset会先await this.waitForInitialLoad()避免插件注册后首次写入被旧文件覆盖的竞态writeQueue: Promisevoid串行化持久化写入的队列任何一次写失败都不会让后续写入永久失效。2.1 字段级生效优先级每次自动召回、memory_recall、ov_search执行前都会通过getEffective()生成一次有效配置。字段级优先级如下request 覆盖参数 session 运行期配置 claw 运行期配置 plugins.entries.openviking.config 静态配置 代码默认值在源码中这一顺序体现在 getEffective 的合并流程先以静态配置与代码默认值初始化effective然后依次applyLayerclaw 层、session 层、request 层每一层只覆盖该层实际显式声明的字段。需要特别说明的边界行为request 级参数只影响当前调用不会写入运行期配置文件session 级配置只影响当前会话匹配顺序为ovSessionId→sessionId→sessionKey见findSessionRecordquery-config.tsclaw 级配置以当前agentId/peerId为作用域影响该 claw 下后续所有 sessionsources会为每个字段标记来源request/session/claw/static/default用于排查为什么当前召回数量/阈值/权重是这个值。2.2 字段合并规则类型规则标量字段高优先级覆盖低优先级如recallLimit、scoreThreshold数组字段整体覆盖不拼接如resourceTypes对象字段浅合并{ ...effective, ...params }如rankingWeights、categoryWeights、resourceTypeWeightscandidateLimit显式设置优先于recallLimit * candidateMultiplier派生值且最终保证candidateLimit recallLimit非法数值归一化时 clamp 到允许范围非法targetUri会报错持久化文件损坏保留 last known-good 内存配置不阻断查询链路candidateLimit的显式跟踪是本轮修复的重点之一。源码中applyLayer()维护一个candidateLimitExplicit布尔值query-config.ts当低优先级层显式设置了candidateLimit时该标记被置为true此后高优先级层如果只设置了recallLimit或candidateMultiplier不会再去覆盖这个显式候选数从而避免session 只设recallLimit却把 claw 显式candidateLimit冲掉的问题对应回归测试 tests/ut/query-config.test.ts。2.3 支持字段与取值范围字段语义范围/约束默认来源recallLimit最终注入或展示结果数1-50静态recallLimitcandidateLimit每个 target URI 的候选检索数1-200派生值candidateMultiplier候选数倍数候选数 recallLimit * candidateMultiplier1-204源码常量DEFAULT_CANDIDATE_MULTIPLIERquery-config.tsscoreThreshold客户端后处理分数阈值0-1静态recallScoreThresholdmaxInjectedChars自动召回注入字符预算100-50000静态recallMaxInjectedCharsrecallPreferAbstract是否优先使用 abstract 注入boolean静态recallPreferAbstractresourceTypes默认搜索范围resource/user/agent静态recallTargetTypestargetUri强制搜索单一 URI必须以viking://开头无ovSearchLimitov_search默认返回数1-10010源码常量DEFAULT_OV_SEARCH_LIMITquery-config.tsrankingWeights.baseScore语义分权重0-21rankingWeights.leaf叶子节点加权0-20.12rankingWeights.event事件类加权0-20.1rankingWeights.preference偏好类加权0-20.08rankingWeights.lexicalOverlapMax词面重叠最大加权0-20.2resourceTypeWeights按资源类型加权-1 到 2空对象categoryWeights按 category 加权-1 到 2空对象以上默认权重在 query-config.ts 的DEFAULT_RANKING_WEIGHTS常量中定义。归一化逻辑集中在normalizeRuntimeQueryParamsquery-config.ts整数字段用clampInteger取整后 clamp浮点字段用clampNumber权重 map 用shallowNumberRecord逐值 clamptargetUri不以viking://开头会直接抛错当candidateLimit recallLimit时自动抬升并写入 warningcandidateLimit was raised to recallLimit。静态配置侧的同名字段recallLimit、recallScoreThreshold、recallMaxInjectedChars、recallPreferAbstract、recallTargetTypes等在 config.ts 的MemoryOpenVikingConfig类型中定义动态配置正是在这些默认值之上叠加运行期覆盖。三、持久化与热加载3.1 配置持久化路径在 OpenClaw 插件配置中声明runtimeQueryConfigPath即可启用持久化不声明则退化为纯内存模式load()/persist()直接跳过{ plugins: { entries: { openviking: { config: { runtimeQueryConfigPath: /path/to/runtime-query-config.json } } } } }3.2 持久化文件结构{ schemaVersion: 1.0, updatedAt: 1780520000000, claws: { main: { params: { recallLimit: 8, candidateLimit: 80 }, updatedAt: 1780520000000, updatedBy: command, agentId: main } }, sessions: { session:oc-session-123: { params: { scoreThreshold: 0.08 }, updatedAt: 1780520000000, updatedBy: command, agentId: main } } }源码层面值得注意的工程细节session key 前缀区分来源ovSessionId前缀为ov:sessionId前缀为session:sessionKey前缀为key:query-config.ts写入是临时文件 renamepersist()先写${path}.${pid}.${ts}.tmp成功后rename原子替换query-config.ts避免半截文件被热加载读到热加载基于 mtimereloadIfChanged()在每次getEffective()前被调用只有当文件 mtime 变化或force: true才重新读取解析解析失败或 schemaVersion 不匹配时静默保留 last known-good 内存配置查询链路不受影响写队列自恢复writeQueue捕获前序失败catch(() undefined)再串联下一次写因此一次磁盘/权限错误不会让后续写入永久失败但失败的那次写入仍会向调用方抛出对应测试 tests/ut/query-config.test.ts。四、使用方式/ov-query-config 命令命令处理器位于 plugin/openviking-query-config-command.ts支持get/set/unset/reset四个动作--scope可选claw或session缺省按session处理见 L196。命令定义注册在 plugin/openviking-command-definitions.ts。4.1 查看当前有效配置/ov-query-config get --scope session返回内容包含scope当前查看的作用域effective合并后的最终配置effective.sources字段来源如session/claw/static/defaulteffective.warnings归一化或降级警告。4.2 设置 claw 级默认召回策略/ov-query-config set --scope claw \ --recallLimit 4 \ --candidateLimit 40 \ --scoreThreshold 0.2 \ --resourceTypes user,agent效果当前 claw以agentId为作用域下所有 session 默认继承该配置session 级配置仍可覆盖。4.3 设置 session 级临时策略/ov-query-config set --scope session \ --recallLimit 10 \ --candidateLimit 80 \ --scoreThreshold 0.08 \ --resourceTypes resource,user效果仅当前 session 生效不影响同 claw 下其他 session。4.4 调整排序权重/ov-query-config set --scope claw \ --weight baseScore0.8,leaf0.2,preference0.18,event0.04,lexicalOverlapMax0.25 \ --categoryWeight preferences0.3,events-0.1 \ --resourceTypeWeight user0.2,resource0.1说明--weight对应rankingWeights--categoryWeight对应categoryWeights--resourceTypeWeight对应resourceTypeWeights命令解析在parseQueryConfigPatchopenviking-query-config-command.ts中实现数值型 flag 校验必须为有限数值权重类 flag 以keyvalue逗号分隔形式解析为数值 map并支持--rankingWeights/--categoryWeights/--resourceTypeWeights作为等价别名权重只影响插件客户端侧排序不改变 OpenViking 服务端搜索算法。客户端排序逻辑位于 memory-ranking.tsmemory_recall链路在 openviking-memory-recall-tools.ts 将三者传入排序函数。4.5 清理字段覆盖/ov-query-config unset recallLimit scoreThreshold rankingWeights --scope session效果删除当前 session 的指定字段覆盖unset接收位置参数作为字段列表下一次查询回退到 claw 或静态配置。4.6 重置作用域配置/ov-query-config reset --scope session /ov-query-config reset --scope claw效果删除该作用域整条运行期配置。命令行安全边界set在归一化后字段为空即传入了未知参数、空 patch时直接抛错拒绝落库不会把已有 scope 配置清空见 openviking-query-config-command.ts对应测试 tests/ut/tools.test.ts。五、Gateway 只读 API两个 API 由 plugin/recall-trace-routes.ts 注册L42-L43它们都不会重新触发搜索方便前端/Gateway 侧展示与深链。5.1GET /api/openviking/uri-detail用途按完整viking://URI 查询详情和正文片段只调用读取能力不重新发起搜索。请求示例curl --get http://127.0.0.1:gateway-port/api/openviking/uri-detail \ --data-urlencode uriviking://resources/project/spec.md \ --data includeContenttrue \ --data contentLimit12000 \ --data offset0Query 参数参数类型必填默认值说明uristring是无完整viking://URI必须 URL encodeincludeContentboolean否true是否读取正文offsetnumber否0内容分页起始偏移contentLimitnumber否20000返回正文最大字符数范围 1-100000agentIdstring否当前上下文 agent读取时的 agent 路由sessionIdstring否当前上下文 sessiontrace / session 上下文关联sessionKeystring否当前上下文 sessionKeytrace / session 上下文关联ovSessionIdstring否当前上下文 ovSessionIdtrace / session 上下文关联traceIdstring否无用于从指定 trace 补充摘要、分数、category 等元信息preferTracePreviewboolean否true是否优先复用 trace 预览信息响应字段字段说明ok是否成功uri请求的完整 URIuriTypeURI 类型如resource/session/user_memory/agent_memory/skill/archive/unknownabstractPreviewtrace 或读取结果摘要预览metadatacategory、score、level、resultType、sourceTraceId、source 等展示元信息content.text正文片段content.offset本次分页起始偏移content.limit本次分页限制content.returnedChars本次返回字符数content.totalChars正文总字符数content.hasMore是否还有后续内容readStatusnot_requested/ok/read_failedwarnings非致命警告error错误码和错误消息状态码状态码场景200URI 合法且读取成功或includeContentfalse只返回元信息400URI 缺失、非viking://、URI 被展示截断、分页参数非法502OpenViking read 调用失败5.2GET /api/openviking/recall-traces/latest-ov-search-list用途获取当前会话最近一次ov_searchtrace 的扁平化 URI 清单方便前端展示上次搜索到了哪些资源。该接口不会重新发起ov_search。请求示例curl --get http://127.0.0.1:gateway-port/api/openviking/recall-traces/latest-ov-search-list \ --data-urlencode sessionIdoc-session-123 \ --data limit20 \ --data includeSelectedtrue \ --data dedupetrueQuery 参数参数类型必填默认值说明sessionIdstring否当前上下文 sessionOpenClaw sessionIdsessionKeystring否当前上下文 sessionKeyOpenClaw sessionKeyovSessionIdstring否当前上下文 ovSessionIdOpenViking storage session idagentIdstring否当前上下文 agent过滤同 session 下不同 agent 的 tracelimitnumber否20返回条数范围 1-100lookupstring否auto当前响应会回显trace 查询走内存/持久化 fallbackincludeSelectedboolean否true是否合并 selected/displayed 结果dedupeboolean否true是否按 URI 去重selected 优先includeSkillsboolean否true是否包含 skill 结果strictboolean否false未找到 trace 时是否返回 404响应字段字段说明ok是否成功非 strict 且无 trace 时仍为 truelookupLayer查询来源memory/persistent/nonefallbackUsed是否使用持久化 fallbackquery回显查询条件trace.traceId命中的 trace IDtrace.ts/trace.isoTimetrace 时间trace.triggerQuery触发 ov_search 的 queryitems[]扁平化条目items[].uri完整 URIitems[].abstractPreview摘要预览items[].resourceType资源类型items[].resultTypememory/resource/skill/archive_matchitems[].category记忆或资源 categoryitems[].score相关性分数items[].sourcesearch_result/selecteditems[].targetUri来源搜索 target URIitems[].detailUrl可直接打开 URI 详情的 Gateway URL格式为/api/openviking/uri-detail?uri...traceId...见 openviking-recall-trace-runtime.tstotalItems返回条目数warnings非致命警告状态码状态码场景200查询成功默认未找到 trace 也返回空列表加 warning400limit等参数非法404stricttrue且未找到最近ov_searchtrace六、本次变更的重点修复问题影响修复说明测试覆盖session 只设置recallLimit时错误覆盖 claw 显式candidateLimit低优先级显式候选数被高优先级派生值覆盖applyLayer()增加candidateLimitExplicit跟踪tests/ut/query-config.test.ts/ov-query-config不能设置权重参数用户无法运行期调整排序权重增加--weight、--categoryWeight、--resourceTypeWeight、--recallPreferAbstract解析tests/ut/tools.test.ts空 patch 覆盖已有配置用户传未知参数会把已有 scope 配置清空空归一化结果直接报错不落库tests/ut/tools.test.tsinstall.sh JSON 转义错误openclaw config set收到非法 JSON 字符串改为传入[resource]的实际 JSON 文本tests/ut/package-install-contract.test.ts初始 load 与 set 并发竞态插件注册后首次写入可能被旧文件覆盖写操作等待 in-flight initial loadtests/ut/query-config.test.ts持久化队列失败后不可恢复一次磁盘/权限错误会让后续写入永久失败rejected queue 自动恢复当前失败仍向调用方抛出tests/ut/query-config.test.tsenv 文件单引号转义错误包含单引号的 API key / URL 可能生成不可 source 的 env 文件使用 shell 单引号规范转义\等价片段实际输出为\tests/ut/package-install-contract.test.ts其中 install.sh 相关修复位于 scripts/install.shJSON 传参修复约在 L242env 单引号转义修复约在 L404。七、测试保障体系7.1 覆盖范围范围覆盖内容单元测试参数归一化、clamp、分层合并、字段来源、持久化、热加载、unset/reset、session alias 匹配命令测试/ov-query-configset/get/unset/reset、权重参数、空 patch 拒绝工具链路测试session 配置影响后续memory_recall、ov_search默认 limit/targetUri自动召回场景测试context engine assemble 阶段使用 session 有效配置排序测试rankingWeights、categoryWeights、resourceTypeWeights 对入选排序生效Gateway API 测试URI detail route、latest ov_search list route、skill 过滤、detailUrl 生成见 tests/ut/tools.test.ts安装脚本契约测试standalone package contract、resource-only recall 配置、JSON 传参、env 单引号转义类型检查tsc -p tsconfig.json生产构建tsc -p tsconfig.build.json稳定性模拟in-flight load serialization、100 session 并发写入、配置文件损坏恢复、写队列失败恢复7.2 聚焦回归测试命令结果npm test -- tests/ut/query-config.test.ts通过9 tests passednpm test -- tests/ut/tools.test.ts -t ov-query-config通过4 tests passednpm test -- tests/ut/package-install-contract.test.ts通过6 tests passedbash -n scripts/install.sh通过无语法错误7.3 全量测试 / 类型 / 构建命令结果npm test通过29 test files passed562 tests passednpm run typecheck通过npm run build通过7.4 生产风格稳定性模拟验证命令覆盖以下行为load()与set()并发时写操作等待初始加载不会被旧文件覆盖100 个 session 并发写入后session 与 claw 配置仍按优先级正确合并配置文件被破坏为非法 JSON 后reloadIfChanged({ force: true })保留 last known-good 内存配置持久化路径临时不可写导致一次写入失败后修复路径后下一次写入可以恢复install.sh dry-run 对包含单引号的 URL/API key 不崩溃resource-only recall 配置输出正确。执行结果production-style runtime config stability check passed: in-flight load serialization 100 concurrent session writes corrupt-file recovery write-queue recovery7.5 未执行范围说明仓库中的 Python e2e 脚本依赖真实 OpenClaw Gateway、OpenViking 服务、LLM 后端和有效 token。当前本地验收环境未提供这些外部运行前提因此未执行会访问真实外部服务的 Python e2e。对应风险已通过全量 Vitest、真实 server 单测、生产风格稳定性模拟和 install dry-run 覆盖本次变更相关链路。八、质量结论与后续演进方向8.1 已关闭风险动态配置优先级已通过单测与场景测试验证candidateLimit显式配置优先级已修复并回归权重参数 CLI 设置已补齐空 patch 不再覆盖已有配置持久化写入采用临时文件 rename写队列失败后可恢复配置文件损坏时保留 last known-good不影响查询链路install.sh 的 JSON 参数与 env 单引号转义均已覆盖。8.2 后续建议建议优先级说明增加 Gateway query-config 写接口P2当前已实现 CLI 与内部 store如前端需要可继续补齐GET/PUT/DELETE /api/openviking/query-config支持 TTL/过期清理P2设计文档预留expiresAt源码RuntimeRecord类型中也已声明该可选字段见 query-config.ts当前主要覆盖 set/unset/reset不做自动 TTL 管理增加真实环境 e2e 流水线P2需要 OpenClaw Gateway、OpenViking、LLM、token 的稳定测试环境多实例集中配置P3当前为单进程/本地文件模型多 gateway 实例可后续接远程配置服务九、总结本次变更已完成OpenViking 查询参数动态配置主链路支持 claw/session 两级粒度、运行期即时生效、配置持久化与热加载、召回数量/候选数量/阈值/资源类型/排序权重全量可调并新增 URI 详情与最近 ov_search 简化清单两个只读 Gateway API。核心实现在 query-config.ts 的RuntimeQueryConfigStore命令入口在 plugin/openviking-query-config-command.ts召回与排序接入分别在 plugin/openviking-memory-recall-tools.ts 与 memory-ranking.ts。经过二次验收和追加复审后发现的问题均已修复当前自动化验证全部通过可以进入提测/评审阶段。对于希望深入源码或复跑验证的读者可重点阅读上述实现文件与 tests/ut/query-config.test.ts、tests/ut/tools.test.ts 两组测试。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考