OpenViking OV Lite 安装指南：为 OpenClaw 部署轻量级会话同步与召回 Skill

OpenViking OV Lite 安装指南为 OpenClaw 部署轻量级会话同步与召回 Skill【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读本文档面向希望在 OpenClaw 中使用 OpenViking 长期记忆能力、但又不希望安装完整contextEngine插件、不占用插件槽位的用户。通过ov_dream这个轻量 Skill你可以把 OpenClaw 的聊天会话以明文 API 密钥直连的方式同步到 OpenViking Serverless并随时通过ov recall query语义检索历史记忆。读完本文你将掌握 OV Lite 的完整安装、校验、认证配置、手动/定时同步、召回以及底层实现原理。OV Lite 是什么不占插件槽位的轻量同步方案OpenViking 为 OpenClaw 提供的标准集成方式是openviking/openclaw-plugin注册为context-engine槽位它会接管assemble、afterTurn、compact等生命周期并自动注入记忆具体可参见 openclaw-plugin 的 README。而本文介绍的OV Lite走的是另一条更轻的路线它通过ov_dreamSkill 直接调用一个纯 Python CLIdream.py将 OpenClaw 聊天会话同步到 OpenViking Serverless。整个方案不安装 contextEngine 插件、不消耗插件槽位适合以下场景只想做手动同步 按需召回不希望插件自动改写每轮对话上下文插件槽位已被其他 context-engine 占用想以最低侵入方式接入 OpenViking希望将同步行为交给 Agent 显式触发ov dream/ov recall ...保持对数据流的完全掌控。从 SKILL.md 的定位说明看OV Lite 第一版是manual-only纯手动它不做记忆自动注入也不替代 context-engine 插件磁盘级同步面向最近录制的聊天记录并不是对当前正在运行的会话的精确检测器。前置条件在运行任何同步或召回命令之前需要准备好以下环境值变量用途OPENVIKING_API_KEYOpenViking Serverless 的 API Key用于 Bearer 认证安全约定不要在日志、shell 历史片段或回复内容中打印 API Key。参考 OV_LITE_INSTALL.md 中的要求该约定在后续.env文件权限chmod 600与源码的认证实现中都有对应体现。安装或更新 OV Lite Skill安装时需显式指定 OpenViking 源码来源。指南合并到main分支后可直接使用main如果正在测试未合并的改动则把SOURCE_BASE替换为其他可信的原始源地址SOURCE_BASEhttps://raw.githubusercontent.com/volcengine/OpenViking/main mkdir -p ~/.openclaw/skills/ov_dream/scripts curl -fsSL $SOURCE_BASE/examples/skills/ov_dream/SKILL.md \ -o ~/.openclaw/skills/ov_dream/SKILL.md curl -fsSL $SOURCE_BASE/examples/skills/ov_dream/scripts/dream.py \ -o ~/.openclaw/skills/ov_dream/scripts/dream.py touch ~/.openclaw/skills/ov_dream/__init__.py touch ~/.openclaw/skills/ov_dream/scripts/__init__.py如果任何一次下载失败请停止操作并核实SOURCE_BASE是否正确。该命令实际拉取的两个文件在当前仓库中的对应路径为 SKILL.md 和 scripts/dream.py你也可以直接从本地仓库复制这两个文件到~/.openclaw/skills/ov_dream/下效果相同。校验下载文件下载完成后通过一组特征字符串校验dream.py是否为预期的 OV Lite 版本grep -q SERVERLESS_BASE_URL ~/.openclaw/skills/ov_dream/scripts/dream.py grep -q OPENVIKING_AUTH_MODE ~/.openclaw/skills/ov_dream/scripts/dream.py grep -q viking://user/default ~/.openclaw/skills/ov_dream/scripts/dream.py grep -q is_chat_session_key ~/.openclaw/skills/ov_dream/scripts/dream.py grep -q raw jsonl fallback can accidentally sync cron/subagent transcripts ~/.openclaw/skills/ov_dream/scripts/dream.py grep -q client.add_session_message(session.session_id ~/.openclaw/skills/ov_dream/scripts/dream.py任何一个检查失败说明下载到的dream.py不是预期的 OV Lite 版本可能是被篡改、来源错误或版本不匹配。这些特征在 dream.py 中均有对应定义例如第 20 行的SERVERLESS_BASE_URL常量、第 178 行的is_chat_session_key()函数以及第 340 行的client.add_session_message(...)调用。配置 Serverless 认证创建~/.openclaw/ov_dream.env环境文件若文件已存在则保留真实的OPENVIKING_API_KEY值只补充缺失的非敏感默认项cat ~/.openclaw/ov_dream.env EOF OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking OPENVIKING_API_KEYreplace with OpenViking serverless API key OPENVIKING_AUTH_MODEserverless EOF chmod 600 ~/.openclaw/ov_dream.env三个变量各司其职OPENVIKING_BASE_URLServerless 网关地址即源码中的SERVERLESS_BASE_URL常量dream.pyOPENVIKING_API_KEY用于 Bearer 认证的密钥OPENVIKING_AUTH_MODE显式指定serverless。若不设置_resolve_auth_mode()会按auto模式推断当base_url包含api.vikingdb或以/openviking结尾时自动切换为serverless否则回落到local默认本地地址为http://127.0.0.1:1933。chmod 600确保只有当前用户可读写该文件配合不打印 API Key的约定共同保护密钥安全。验证同步与召回在 skill 目录下加载环境变量并执行同步、召回验证cd ~/.openclaw/skills/ov_dream set -a . ~/.openclaw/ov_dream.env set a python3 scripts/dream.py dream python3 scripts/dream.py recall 最近我在聊什么dream子命令读取 OpenClaw 的sessions.json将符合条件的聊天会话同步到 OpenViking并对有新消息的会话执行 commitrecall query子命令在默认用户根 URIviking://user/default下执行语义检索默认返回前 5 条记忆。定时同步让记忆自动沉淀同步是幂等增量的非常适合定时执行。添加或更新一个每 5 分钟运行一次的 OpenClaw cronjob。如果ov-dream-sync已存在请更新或替换它而不是创建重复任务openclaw cron add ov-dream-sync \ --schedule */5 * * * * \ --command cd ~/.openclaw/skills/ov_dream set -a . ~/.openclaw/ov_dream.env set a python3 scripts/dream.py dream得益于源码中的逐会话独立同步游标机制状态持久化在~/.openclaw/memory/ov_dream_sync.json由 load_sync_state 与 save_sync_state 管理每次定时同步只会上传各会话新增的消息依据last_synced_timestamp增量过滤见 sync_session不会重复上传历史数据。按需召回命令当用户发出ov recall query指令时从 skill 目录执行cd ~/.openclaw/skills/ov_dream set -a . ~/.openclaw/ov_dream.env set a python3 scripts/dream.py recall query按 SKILL.md 的路由规则ov recall ...是硬路由命令Agent 不得用普通推理作答、不得总结召回会做什么、不得询问是否执行而应立即执行本地召回命令并把命中的记忆行返回给用户若无命中则返回No memories found.。查询为空时向用户询问而不是自行猜测。CLI 还支持更多参数见 _build_parserpython3 scripts/dream.py recall query --limit 10 python3 scripts/dream.py dream --base-url http://127.0.0.1:1933 python3 scripts/dream.py dream --auth-mode local --api-key sk-xxx可用参数包括--base-url、--api-key、--auth-modeauto/local/serverless、--openclaw-root默认~/.openclaw、--state-root默认~/.openclaw/memory以及 recall 的--limit默认 5。行为细节与实现原理会话数据来源只信任索引不回溯原始 jsonlOV Lite 从~/.openclaw/agents/main/sessions/sessions.json读取会话元数据见 get_active_sessions。源码中有一句关键注释raw jsonl fallback can accidentally sync cron/subagent transcripts原始 jsonl 回退可能误同步 cron/subagent 记录这正是校验指纹中那句 grep 的出处——它明确说明OV Lite 不会回退到扫描最新原始 jsonl 文件只以 OpenClaw 的会话索引为唯一数据源避免把后台任务记录误当聊天内容上传。非聊天会话过滤规则is_chat_session_key 通过黑名单前缀过滤非聊天会话只要 session key 包含以下任一片段即被排除:cron:定时任务:heartbeat心跳:subagent:子代理:acp:ACP 工具:hook:钩子事件同时保留agent:main:main、:direct:、:channel:、:group:、:room:等聊天形态的会话键。测试 test_dream_cli.py 中的test_is_chat_session_key_filters_non_chat_openclaw_sessions与test_get_active_sessions_does_not_fallback_to_raw_jsonl精确验证了这套过滤行为。会话 ID 复用与 Serverless 消息格式OV Lite 在写入 OpenViking Serverless 时复用 OpenClaw 的session_id保证同一会话在两端 ID 一致。Serverless 模式下的差异体现在 add_session_message 与 commit_session消息体使用parts数组格式{role: role, parts: [{type: text, text: content}]}区别于 local 模式的content字符串commit 请求携带{telemetry: false}且不带?waittrue后缀。认证与目标 URI 解析Serverless 模式下客户端使用Authorization: Bearer api_key头不再发送X-OpenViking-Account/X-OpenViking-User/X-API-Key见 _headers。召回默认目标 URI 为viking://user/default在 local 模式下_resolve_target_uri 会把该根 URI 展开为viking://user/user取自OPENVIKING_USER环境变量并兼容历史写法viking://user/memories与viking://~/memories均指向viking://user/user/memories/。相关测试包括test_recall_default_target_uri_is_user_root与test_recall_expands_default_user_root_to_explicit_user_space。召回 API 调用链recall 向POST /api/v1/search/find发送{query, limit, target_uri}返回结果按memories列表读取_print_recall_results 以uri|score|summary的格式逐行打印命中记忆无命中时输出No memories found.。测试与验证依据仓库为该 Skill 提供了完整的 CLI 单元测试 tests/test_dream_cli.py覆盖了本文涉及的关键行为可直接作为实现依据test_normalize_raw_ov_recall_phraseov recall 小明的信息被规范化为[recall, 小明的信息]test_serverless_headers_use_bearer_authServerless 模式使用 Bearer 认证且不包含X-API-Key/X-OpenViking-User头test_serverless_sync_reuses_source_session_id_and_uses_parts_payload复用源 session_id 并发送parts格式消息体test_sync_active_session_syncs_chat_sessions_with_independent_cursors多个聊天会话各自维护独立同步游标cron 会话不参与同步。与 contextEngine 插件的取舍维度OV Liteov_dream SkillcontextEngine 插件安装方式下载 SKILL.md dream.py 到~/.openclaw/skills/openclaw plugins install clawhub:openviking/openclaw-plugin插件槽位不占用注册为contextEngine槽位触发方式显式ov dream/ov recall ...或 cron 定时afterTurn/compact等生命周期自动触发记忆注入不自动注入 promptassemble阶段自动检索注入认证模式Serverless Bearer / 本地双模式通过openviking setup配置从源码定位看OV Lite 是手动同步 按需召回的轻量通道而插件是全生命周期自动记忆的重型集成。两者目标不同可按需选择甚至并存——OV Lite 不占用插件槽位意味着即使插件槽位已被占用它依然可以作为旁路同步/检索通道使用。注意事项小结安装时SOURCE_BASE必须指向可信来源任何下载失败都立即停止排查下载后务必执行 6 条 grep 指纹校验防止拿到非预期版本ov_dream.env权限保持600API Key 严禁出现在日志、历史记录与回复中磁盘级同步基于sessions.json索引反映的是最近录制的聊天记录不是当前正在运行会话的精确状态同步状态含每个会话的last_synced_timestamp持久化在~/.openclaw/memory/ov_dream_sync.json重复执行 dream 不会产生重复数据涉及版本与配置项均以当前仓库中 OV_LITE_INSTALL.md、SKILL.md 与 dream.py 的实际内容为准。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考