openviking-context-database

OpenViking 上下文数据库 — OpenClaw 插件操作技能

在安装并配置好 @openviking/openclaw-plugin 后使用本技能。它描述的是当前 OpenClaw 插件的实现，而非独立的 OpenViking Python SDK。

适用范围与安全规则

• 该插件仅支持远程。它通过 HTTP 与现有的 OpenViking 服务通信，不会启动或管理 openviking-server。
• 不要臆造 OpenViking REST 端点。请使用下文描述的已注册 OpenClaw 工具和命令。
• Agent 可见的 add_resource 工具默认禁用（enableAddResourceTool=false）。在搜索、检索、URI 读取或搜索结果优化过程中，不要使用 add_resource。在这些流程中请使用 ov_search 和 ov_read。
• 请使用手动 /add-resource，或仅在 add_resource 被显式启用且用户明确要求导入、添加、上传、保存或索引某个资源时，才使用 add_resource。
• 仅在用户明确要求将 Agent Skill 导入、添加、安装或注册到 OpenViking 时，才使用 add_skill。
• 对于本地文件和目录，请将本地路径传给插件工具。插件会通过 /api/v1/resources/temp_upload 上传它们；不要自行将原始本地文件系统路径发送到远程服务。
• 切勿记录或回显 API 密钥。插件会将 API 密钥作为 X-API-Key / setup probe 请求头发送，并在 setup 输出中将其掩码处理。

当前架构

OpenClaw 负责 Agent 执行、提示词和工具调用。OpenViking 负责长期存续的上下文：

层级	当前行为
assemble	从 OpenViking 重建压缩后的会话历史，并将相关召回注入到最新一条用户消息中。
afterTurn	仅将新增的一轮追加到 OpenViking 会话；当 pending_tokens >= tokenBudget * commitTokenThresholdRatio 时，可能触发异步提交。
compact	运行 commit(wait=true)，等待归档/提取完成，并读回最新的归档概览。
工具	记忆召回/存储/遗忘、归档搜索/展开、资源/技能导入/搜索、召回轨迹查询、工具结果列表/搜索/读取。

长期记忆通常在 /compact 时或在达到阈值触发的提交时提取。在新会话中提到的一个事实，在成为长期记忆之前，可能仍作为近期会话上下文存在。

配置快速参考

先读取状态：

openclaw openviking status --json
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine

核心配置位于 plugins.entries.openviking.config 下：

字段	默认值	用途
baseUrl	http://127.0.0.1:1933	OpenViking HTTP 端点。也可以来自 OPENVIKING_BASE_URL / OPENVIKING_URL。
apiKey	空	可选的 API key。也可以来自 OPENVIKING_API_KEY。
peer_role	none	记忆范围：none（共享 viking://user/<user_id>/memories）、assistant（归属于助手的记忆，位于 .../peers/<assistant_id>/memories）或 sender（归属于发送者的记忆，位于 .../peers/<sender_id>/memories）。旧版 person 会被视为 sender。
peer_prefix	空	当 peer_role=assistant 时，用于助手 peer_id / actor peer 值的可选前缀。
accountId / userId	空	用于 root-key 或受信任部署的高级租户身份请求头。
targetUri	viking://~/memories	旧版定向记忆搜索的默认搜索范围。
autoCapture	true	将清理后的对话轮次文本追加到 OpenViking 会话。
captureMode	semantic	semantic 或 keyword；影响服务端提取过滤。
captureMaxLength	24000	每次捕获轮次的最大清理文本长度。
autoRecall	true	在回复前执行召回并注入相关上下文。
recallTargetTypes	user,agent	省略 targetUri 时的默认目标类型。允许值：resource、user、agent。
recallResources	false	兼容性快捷方式，当未设置 recallTargetTypes 时会将 resource 追加到默认召回目标。
recallLimit	6	最多选择的召回条目数。
recallScoreThreshold	0.15	后处理后的最低分数。
recallMaxInjectedChars	4000	注入字符总数上限；放不下的完整记忆会被跳过。
commitTokenThresholdRatio	0.5	异步提交阈值，表示模型上下文窗口的比例（0-1，例如 0.5 = 50%）；0 表示每轮都提交。
commitKeepRecentCount	10	afterTurn 提交后保持活跃的最近消息数。Compact 始终使用 0。
bypassSessionPatterns	空	类似 glob 的会话键，可完全绕过 OpenViking（* 表示单段，** 表示多段）。
emitStandardDiagnostics	false	输出结构化的 openviking: diag {...} 行。
logFindRequests	false	记录 find/session 写入的路由。也可通过 OPENVIKING_LOG_ROUTING=1 或 OPENVIKING_DEBUG=1 启用。
traceRecall	false	在内存中记录召回追踪。
traceRecallPersist	false	将召回追踪持久化为本地 JSONL 文件。
traceRecallDir	~/.openclaw/openviking/recall-traces	启用持久化时的召回追踪目录。

常规设置命令：

openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json

常用变体：

openclaw openviking setup --base-url <URL> --api-key <KEY> --peer-role assistant --peer-prefix openclaw-prod --json
openclaw openviking setup --base-url <URL> --api-key <ROOT_KEY> --account-id <ACCOUNT_ID> --user-id <USER_ID> --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --recall-target-types resource --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --allow-offline --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --force-slot --json

工具选择指南

用户意图	使用
“我之前说过什么？”，偏好、决定、已知事实	memory_recall
“现在记住这个”	memory_store
“忘记 X”	memory_forget
摘要缺少旧聊天中的确切命令/路径/片段	ov_archive_search，如需要再用 ov_archive_expand
导入文档、PDF、本地目录、URL、Git 仓库、媒体附件	手动 /add-resource；仅当 enableAddResourceTool=true 时使用 add_resource
导入/注册 Agent Skill	add_skill
搜索已导入的资源或技能	ov_search
读取来自 ov_search 或召回追踪的确切 viking://... 命中项	ov_read
解释召回/搜索为什么返回了某些内容	ov_recall_trace
之前的工具结果只显示预览/引用	openviking_tool_result_list、openviking_tool_result_search、openviking_tool_result_read

工具接口参考

memory_recall

对记忆/资源进行语义搜索。会话历史请使用归档工具。

参数	必填	描述
query	是	搜索查询。
limit	否	最多选取的结果数。默认为 recallLimit。
scoreThreshold	否	分数阈值 0..1。默认为 recallScoreThreshold。
targetUri	否	精确搜索 URI。若设置，则仅搜索此 URI。
resourceTypes	否	resource、user、agent 的数组；仅在省略 targetUri 时使用。

说明：省略 targetUri 时，插件会根据 resourceTypes 或已配置的 recallTargetTypes 确定搜索计划，获取多于请求数量的候选项，去重、筛除叶子记忆、重新排序，并遵守 recallMaxInjectedChars 的限制。

memory_store

立即持久化文本：写入会话并以 wait=true 提交。

参数	必填	描述
text	是	信息来源文本。
role	否	会话角色，默认为 user。
sessionId	否	现有的 OpenViking/OpenClaw 会话引用。若省略，则会创建临时的 memory-store-* 会话。

memory_forget

删除记忆。

参数	必填	描述
uri	否	精确的 viking://user/.../memories/... 记忆 URI。非记忆 URI 会被拒绝。
query	否	URI 未知时使用的搜索查询。
targetUri	否	搜索范围 URI，默认为 targetUri。
limit	否	搜索数量上限，默认为 5。
scoreThreshold	否	搜索阈值，默认为 recallScoreThreshold。

如果查询模式找到多个候选项，请报告候选项并让用户选择精确 URI；不要删除有歧义的记忆。

ov_archive_search

在当前会话归档的原始对话消息中进行关键词搜索。

参数	必填	描述
query	是	单个关键词或简短短语；优先使用名称、日期、文件路径、命令或具有辨识度的名词。
archiveId	否	限定在单个归档中搜索，例如 archive_002。

在确定归档细节不可用之前，至少尝试两个具体的关键词变体。

ov_archive_expand

参数	必填	描述
archiveId	是	来自 [Archive Index] 的归档 ID，例如 archive_002。

在归档搜索后使用，或者当 [Archive Index] 已指出可能包含精确细节的归档时使用。

add_resource

将资源导入 viking://resources/...。

此 Agent 工具默认禁用。导入资源时优先使用手动 /add-resource。如果 enableAddResourceTool=true 启用了该工具，仅在明确要求导入/索引时使用，不要将其用于搜索/检索优化。

参数	必填	描述
source	是	本地路径、OpenClaw 媒体附件路径、目录路径、公共 URL 或 Git URL。
to	否	精确的目标 URI，例如 viking://resources/project-docs。与 parent 互斥。
parent	否	viking://resources 下的父级 URI。与 to 互斥。
reason	否	导入原因/备注。
instruction	否	用于语义提取的处理指令。
wait	否	等待处理完成。

当前 OpenClaw 工具会公开上述参数。底层客户端还支持面向服务端的资源选项，例如 strict、ignore_dirs、include、exclude 和 preserve_structure，供命令/内部路径使用；除非已注册的 schema 公开这些选项，否则不要将它们传给工具。

add_skill

将 Agent 技能导入 viking://~/skills/...。

参数	必填	描述
source	否	本地 SKILL.md 路径或技能目录。必须且只能提供 source 或 data 其中一项。
data	否	原始 SKILL.md 内容或 MCP 工具字典。必须且只能提供 source 或 data 其中一项。
wait	否	等待处理完成。

Agent 技能最佳实践：技能应包含精确的 frontmatter（name、以触发条件为导向的 description、有用的 tags）、明确的范围边界、必要时明确说明“何时不应使用”，并提供带有具体参数的可执行步骤。不要在技能内容中包含机密信息。

ov_search

参数	必填	描述
query	是	搜索查询。
uri	否	搜索 URI。默认为资源和 Agent 技能。
limit	否	每个范围的最大结果数，默认为 10。

导入资源/技能后使用，或在用户要求搜索由 OpenViking 管理的知识时使用。

重要：ov_search 会返回 OpenViking 虚拟 URI，例如 viking://resources/project-docs/api.md#chunk-3。这些不是本地文件路径。不要使用文件系统读取工具读取它们；需要完整内容时，请使用确切的 URI 调用 ov_read。

ov_read

通过 /api/v1/content/read 读取一个确切 OpenViking 虚拟 URI 的完整内容。

参数	必填	描述
uri	是	ov_search 或召回跟踪结果返回的确切 viking://... URI。不接受 openviking://... 别名和本地文件路径。

ov_recall_trace

参数	必填	描述
turn	否	latest 或 all，默认为 latest。
traceId	否	确切的跟踪 ID。
sessionId / sessionKey / ovSessionId	否	按 OpenClaw/OpenViking 会话筛选。
source	否	auto_recall、memory_recall、ov_search 或 ov_archive_search。
resourceTypes	否	包含 resource、user、agent 的数组/字符串。
since / until	否	以毫秒为单位的 Unix 时间戳范围。
includeContent	否	按需读取选定/显示的 URI 内容预览。
limit	否	返回的最大跟踪记录数，默认为 20。

只有在 traceRecall=true 时才会生成跟踪记录；持久化查询需要 traceRecallPersist=true 且跟踪文件可访问。

外置工具结果工具

当预览中包含 viking://user/{user_id}/sessions/<session_id>/tool-results/<tool_result_id> 时使用。

工具	参数
openviking_tool_result_list	tool_name?、limit?（默认为 50）
openviking_tool_result_search	tool_output_ref、query、limit?（默认为 20）、context_chars?（默认为 300）
openviking_tool_result_read	tool_output_ref、offset?（默认为 0）、limit?（默认为 20000，服务器路径接受 -1，表示读取所有剩余内容）

插件拒绝读取/搜索来自其他会话的工具结果引用。

斜杠命令

/add-resource ./README.md --to viking://resources/openviking-readme --wait
/add-skill ./skills/install-openviking-memory --wait
/ov-search "OpenViking install" --uri viking://resources/openviking-readme --limit=5
/ov-recall-trace --turn latest --source auto_recall --include-content

命令解析器支持带引号的参数和标志。仅适用于资源的标志不允许用于技能导入。

故障排查

症状	可能原因	首先采取的操作
configured=false	设置未能持久化配置	重新运行 openclaw openviking setup ... --json；根据 JSON error 分支处理。
slotActive=false	另一个上下文引擎占用了槽位，或网关状态已过期	检查 plugins.slots.contextEngine；仅在用户确认后使用 --force-slot。
health.ok=false	服务不可达，或 baseUrl / 密钥错误	检查 baseUrl、网络、/health 和认证。
新事实后没有长期记忆	/compact 或提交/抽取尚未运行，或服务端抽取失败	对于明确的记住/保存/存储意图，使用 memory_store；否则运行 /compact 或等待阈值提交，然后检查 OpenViking 服务日志。
召回遗漏共享文档	未启用 resource 目标	使用带 resourceTypes:["resource"] 的 memory_recall，或配置 recallTargetTypes: ["resource"]。
摘要缺少精确细节	归档摘要过于粗粒度	使用带具体关键词的 ov_archive_search，然后使用 ov_archive_expand。
大型工具输出预览不充分	工具结果已被外部化	使用带 ref 的 openviking_tool_result_search/read。
需要解释召回行为	追踪已禁用，或该轮次没有追踪	启用 traceRecall；可选启用 traceRecallPersist；查询 ov_recall_trace。

本仓库中的参考文档

• README.md / README_CN.md：功能概览与快速开始。
• INSTALL.md / INSTALL-ZH.md：安装、升级、卸载，以及 JSON 设置处理。
• INSTALL-AGENT.md：面向 Agent 的安装工作流。
• docs/openviking-openclaw-plugin-guide.md：全面的中文操作者/开发者指南。