OpenClaw 接入 OpenViking为 Agent 网关配置长效记忆与上下文引擎插件【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenClaw 是一个 Agent 网关/运行时OpenViking 是一个面向 AI Agent 的自进化上下文数据库统一 Agent 记忆、知识 RAG 与 Skills。通过openviking/openclaw-plugin插件可以把 OpenClaw 变成 OpenViking 的远程上下文引擎客户端安装并配置后OpenClaw 会自动记忆对话中的重要信息并在每次回复前召回相关上下文。本文基于 docs/images/agents/zh/openclaw.md 与 docs/zh/agent-integrations/03-openclaw.md 的完整步骤结合 examples/openclaw-plugin 的源码与配置讲解从安装、记忆归属peer_role设计、验证到故障排查的全过程读完即可在本地或火山引擎托管的 OpenViking 服务上完成接入并开始对话。前置条件在开始安装前先确认运行环境满足插件的最低版本要求组件版本要求Node.js 22OpenClaw 2026.5.27快速检查node -v openclaw --version插件以仅远程模式运行它是已有 OpenViking 服务的 HTTP 客户端不会启动本地 OpenViking server 进程见 examples/openclaw-plugin/README_CN.md。因此需要先有一个正在运行的 OpenViking 服务参考 部署指南。若 OpenViking 与 OpenClaw 在同一台机器上最短启动流程是pip install openviking --upgrade --force-reinstall openviking-server init openviking-server doctor openviking-serveropenviking-server init生成服务端配置openviking-server doctor检查本地模型和 provider 鉴权是否可用openviking-server真正启动 HTTP API 的命令插件使用期间需要一直运行。后台启动可写日志到固定路径mkdir -p ~/.openviking/data/log nohup openviking-server ~/.openviking/data/log/openviking.log 21 OpenViking 跑在其他机器上时需要监听可访问的地址和端口openviking-server --host 0.0.0.0 --port 1933并把插件的baseUrl指向对应地址。安装或重启插件前先确认服务可访问curl http://127.0.0.1:1933/health不要把插件和 Skill 装混openviking/openclaw-plugin是 OpenClaw插件context-engine 插件。不要使用下面的命令安装它clawhub install openviking这条命令安装的是名为openviking的 AgentSkill不是 OpenClaw 插件。安装插件应使用见 INSTALL-ZH.mdopenclaw plugins install clawhub:openviking/openclaw-plugin另外从2026.5.3开始 OpenClaw 会校验 TypeScript 插件入口是否带有编译后的 JavaScript 产物推荐的 ClawHub 安装路径会直接安装已发布且包含dist/*.js的插件包普通用户不需要本地编译。步骤1安装整个接入过程一共四步安装插件 → 配置服务地址与 Key → 重启 Gateway → 验证。1.1 安装 OpenViking 插件openclaw plugins install clawhub:openviking/openclaw-plugin如果你的环境需要显式 registry 前缀命令不变clawhub:前缀即为显式指定。1.2 连接至火山引擎托管的 OpenViking 服务如果你的 OpenViking 由火山引擎控制台托管无需自建openviking-server直接把控制台提供的 server url 和 API Key 注入 setup 向导openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key $OPENVIKING_API_KEY自建服务的通用写法openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --jsonsetup向导会完成三件事把配置写入plugins.entries.openviking.config、激活plugins.slots.contextEngineopenviking槽位、并验证与服务端的连接。追加--json可以获得机器可读的输出方便自动化 Agent 判断下一步。常用 setup 变体# 可选 agent 命名空间前缀 openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --peer-prefix openclaw-prod --json # root/trusted key 部署需要显式租户身份 header openclaw openviking setup --base-url http://my-server:1933 --api-key root-xxx --account-id acc_123 --user-id user_456 --json # 默认只召回 account 级共享知识资源 openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --recall-target-types resource --json如果服务暂时不可达但仍希望先保存配置可加--allow-offlineopenclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --allow-offline --json如果已有其他 context engine 占用槽位setup 默认不会替换确认要替换时使用--force-slotopenclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --force-slot --json1.3 配置 peer_role记忆归属peer_role用于标识对话参与者的类型并非权限角色。其中assistant表示不同的 Agent、工具或模型person旧别名等价于sender表示不同的人类参与者。完成配置后peer_role默认为none。peer_role决定长期记忆是在 OpenViking user 层共享还是归属到具体 peer值记忆路径适用场景none默认共享记忆位于viking://user/user_id/memories/...不使用具体 peer 的记忆子树通用场景该 OpenViking 用户下的所有对话共享 user-level 记忆assistantassistant 归因的 peer 记忆位于viking://user/user_id/peers/assistant_id/memories/...人是 OpenViking user让main、research等不同助手的 peer 记忆分开sendersender 归因的 peer 记忆位于viking://user/user_id/peers/sender_id/memories/...Agent 是 OpenViking user让customer-42、customer-99等不同发送者的 peer 记忆分开例如# Alice 是 OpenViking user按 OpenClaw 助手分开 peer 记忆。 openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role assistant --json # support-agent 是 OpenViking user按给它发消息的人分开 peer 记忆。 openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json新配置请使用sender已有的peer_roleperson配置仍兼容并按sender处理。OpenViking 会为每个用户初始化受管的peers/容器因此none的含义是不使用具体的peers/peer_id/memories子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆切换 scope不会搬迁已有记忆。从源码看config.ts 中的resolvePeerRole()会把person规范化为sender非法值直接抛错保证运行时只出现none | assistant | sender三种合法值。如需调整已保存的peer_role执行openclaw openviking setup --reconfigure1.4 重启 Gatewayopenclaw gateway restart如果你的 OpenClaw 版本使用不同的重启命令请使用对应的 gateway 重启方式。配置修改包括直接改openclaw.json后都需要重启 Gateway、容器或 Pod 才能生效。备用路径ov-install当 ClawHub 或 OpenClaw 插件管理器不可用、被限流或明确需要测试 Git ref 时可以使用备用安装器npm install -g openclaw-openviking-setup-helper ov-install --base-url http://your-server:1933常用参数参数含义--workdir PATHOpenClaw 数据目录默认~/.openclaw--plugin-versionVER插件版本npm 版本、dist-tag 或 Git ref--base-url URLOpenViking 服务地址--api-key KEYOpenViking API Key--peer-role ROLE记忆归属none、assistant或senderperson是旧别名--peer-prefix PREFIXassistantpeer_id/ actor peer 值的前缀--uninstall卸载插件面向用户的安装仍应优先使用openclaw plugins install clawhub:openviking/openclaw-plugin。步骤2验证2.1 一键状态检查在终端执行openclaw openviking status返回如下结果即表示接入成功 OpenViking Plugin Status Status: Configured mode: remote baseUrl: https://api.vikingdb.cn-beijing.volces.com/openviking apiKey: set peer_role: none accountId: not set userId: not set slot: active ✓ Server reachable (version: v0.x.xx.x)追加--json可获取机器可读结果关键字段期望值JSON 字段期望值configuredtrueslotActivetruehealth.ok服务可达时为true2.2 手动验证槽位与配置确认插件占用了contextEngine槽位openclaw config get plugins.slots.contextEngine # 期望输出openviking查看插件配置openclaw config get plugins.entries.openviking.config全链路健康检查在仓库 checkout 中运行会注入一次真实对话并验证会话捕获、提交、归档和记忆提取python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py详细说明见 HEALTHCHECK-ZH.md。插件配置详解插件配置位于plugins.entries.openviking.config通常 setup 已经写好。核心字段参数默认值含义moderemote兼容旧配置的字段当前只支持 remotebaseUrlhttp://127.0.0.1:1933OpenViking 服务端点也支持${OPENVIKING_BASE_URL}插值apiKey空OpenViking API Key服务端未开启认证时可留空peer_rolenone记忆归属none、assistant或sender旧值person作为sender的别名兼容peer_prefix空peer_roleassistant时 assistant peer 身份的可选前缀accountId/userId空使用 root API key 时的租户上下文高级选项autoRecallTimeoutMs5000源码默认15000整个 auto-recall 流程的外层超时毫秒本地嵌入硬件较慢时可调大取值范围 1000–300000普通修改优先使用 setupopenclaw openviking setup --reconfigure也可以直接用config set修改单个字段openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933 openclaw config set plugins.entries.openviking.config.apiKey your-api-key openclaw config set plugins.entries.openviking.config.peer_role assistant openclaw config set plugins.entries.openviking.config.peer_prefix your-prefix无法执行 CLI 时直接配置文件容器内无法执行openclawCLI 时可以把以下字段合并到 OpenClaw 实际读取的配置文件设置了OPENCLAW_CONFIG_PATH时使用该路径否则通常是$OPENCLAW_STATE_DIR/openclaw.json默认~/.openclaw/openclaw.json{ plugins: { entries: { openviking: { enabled: true, config: { mode: remote, baseUrl: http://openviking:1933, apiKey: API_KEY, peer_role: assistant } } }, slots: { contextEngine: openviking } } }注意事项编辑前请备份配置contextEngine是独占 slot只有确认替换后再修改容器连接其他服务时baseUrl应使用容器内可访问的服务地址而不是127.0.0.1推荐使用SecretRef对象作为apiKey而非明文字符串避免密钥直接落盘。支持的形式与 OpenClaw 核心标准一致类型示例说明env{ source: env, id: OPENVIKING_API_KEY }启动时读取同名环境变量file{ source: file, id: /etc/secrets/openviking.key }以 UTF-8 读取并去除首尾空白适配 KubernetessecretKeyRef卷挂载、0600 权限文件exec打包版插件不支持改用命令包一层环境变量OPENVIKING_API_KEY$(op read op://vault/openviking/credential)然后配env从源码看config.ts 的resolveSecret()实现了env/file解析exec会直接抛 not supported 错误——因为应用市场安装扫描会拦截可 spawn 子进程的插件。其他高级配置参数源码确认config.ts 中memoryOpenVikingConfigSchema.parse()还解析并校验了大量高级参数例如autoCapture默认true、captureModesemantic/keyword默认semantic、captureMaxLength默认 24000autoRecall默认true、recallTargetTypes默认[user,agent]可选resource、recallLimit默认 6、recallScoreThreshold默认 0.15、recallMaxInjectedChars默认 4000commitTokenThresholdRatio默认 0.5afterTurn后当待提交 token 达到「模型上下文窗口 × 该比例」时触发异步 commit设为0则每轮都提交commitKeepRecentCount默认 10traceRecall/traceRecallPersist/traceRecallDir默认~/.openclaw/openviking/recall-traces召回链路追踪enableAddResourceTool默认falseAgent 可见的add_resource导入工具默认禁用手动/add-resource始终可用enabledTools/disabledTools工具白名单/黑名单支持精确工具名或分组default、all、memory、resource_query、import、recall_trace、archive、tool_resultbypassSessionPatterns对匹配的 session key 完全绕过 OpenViking不捕获、不召回、不提交压缩回退到 OpenClaw 原生 compactor。例如禁用记忆并只保留资源查询工具{ autoCapture: false, autoRecall: false, enabledTools: [resource_query] }工作原理插件在 OpenClaw 生命周期中的角色从源码结构看examples/openclaw-plugin 下的openviking-context-engine-registration.ts、openviking-lifecycle-hooks.ts、openviking-services.ts等插件同时扮演四个角色context-engine实现assemble/afterTurn/compact、Hook 层接管session_start、session_end、before_reset、Tool 提供者注册 memory/archive 与资源导入工具、运行时管理器连接并监控远程 OpenViking 服务。所有 HTTP 调用统一走OpenVikingClientclient.ts由 client 层补充X-OpenViking-*头并记录路由日志。上图对应的整体边界是OpenClaw 在左侧仍是主运行时负责 agent runtime、prompt 编排与工具执行插件中间层把 Hook、Context Engine、Tools、Runtime Manager 合并在一个注册单元里OpenViking 服务端承接 session、memory、archive 与抽取底层存储落在viking://user/*、viking://session/*和viking://resources/*。这套拆分让 OpenClaw 继续专注推理与编排让 OpenViking 成为长期上下文的事实源。Session 生命周期assemble / afterTurn / compactSession 是这套设计的主轴覆盖历史组装、增量写入、异步提交、阻塞压缩回读四个动作阶段行为每轮对话后afterTurn新消息追加到 OpenViking sessioncommit/抽取由阈值触发明确要求记住memory_store重要长期事实可立即写入并提交/compact时compact待提交 session 消息被 commit 并抽取为长期记忆回复前assemble自动检索相关记忆并注入上下文assemble()OpenClaw 会调用两次。preflight 形态带prompt插件从 OpenViking 回读 archive/session context 并重建历史——latest_archive_overview被改写成[Session History Summary]pre_archive_abstracts被改写成[Archive Index]当前活跃消息按 message block 回放并做toolCall/toolResult配对修复transformContext 形态不带prompt只做长期记忆召回把relevant-memories块 prepend 到当前 user message 开头。afterTurn()只切出本轮新增消息user/assistant文本、格式化后的toolCall/toolResult先剥掉注入过的relevant-memories和元数据噪音再追加到 OpenViking session随后读取pending_tokens达到tokenBudget × commitTokenThresholdRatio时触发commit(waitfalse)当前 turn 不被阻塞。compact()走严格同步边界调用commit(waittrue)阻塞等待归档完成后回读latest_archive_overview返回新的 token 估算与 archive 摘要如果摘要不够细模型可再调用ov_archive_expand读取原始消息。自动召回链路召回阶段的核心流程从最后一条 user message 提取查询文本 → 基于sessionId/sessionKey解析本轮 agent 路由 → 快速可用性检查OpenViking 不可用时跳过不拖慢模型请求→ 按recallTargetTypes发起带 session 上下文的 context search默认user,agent可选resource→ 由服务端结合 session 历史扩展查询、完成过滤排序与预算内组装 → 以relevant-memories形式注入不追加独立 synthetic user message。插件默认提供的工具安装后插件默认为 Agent 提供 14 个工具见 config.ts 的OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES工具用途memory_recall在user、agent、resource目标中显式语义召回memory_store立即持久化明确的长期事实触发阻塞 commit/抽取memory_forget按精确 URI 删除记忆或搜索并删除唯一高置信匹配ov_archive_search对当前 session 已归档的原始对话消息做关键词 grepov_archive_expand按 archive ID 展开原始消息ov_recall_trace查看 auto-recall 和显式 recall/search 记录的召回链路add_skill将SKILL.md、skill 目录、原始 skill 内容或 MCP tool dict 导入viking://user/uid/skills/...ov_search检索已导入的 resources 和 skillsov_read读取ov_search/ trace 返回的viking://...OpenViking 虚拟 URI 完整内容ov_multi_read一次读取多个精确viking://...URI适合同时读取 overview 和同级切片ov_list在检索后列出 OpenViking 目录补查同级切片和.overview.md文件openviking_tool_result_list列出当前 session 中被外置的大工具输出openviking_tool_result_search在外置工具输出中按关键词搜索openviking_tool_result_read通过viking://session/.../tool-results/...ref 分页读取外置工具输出插件还提供手动 slash command/add-resource、/add-skill、/ov-search、/ov-recall-trace。Agent 可见的add_resource工具默认禁用enableAddResourceToolfalse避免搜索/检索阶段误触发资源导入确需允许时显式设置enableAddResourceTooltrue。数据流与隐私发送内容每轮 user/assistant 消息文本已剥离注入的记忆块和元数据噪音发送去向仅发往你配置的 OpenViking 服务baseUrl插件本身只与该服务通信服务端对 embedding、VLM 等模型的调用取决于服务端配置存储位置所有数据存储在你的 OpenViking 服务上命名空间包括viking://user/*、viking://session/*、viking://resources/*等API Key通过X-API-Keyheader 发送不会被日志记录或转发多租户隔离支持accountId、userId可选的peer_role/peer_prefix控制是否把 OpenClaw 说话人写入 OpenVikingpeer_id并在数据面使用X-OpenViking-Actor-Peersession message 仍用 bodypeer_id做消息归因。升级、卸载与迁移升级openclaw plugins update openviking openclaw gateway restart openclaw openviking status --json确认configured和slotActive都是true。卸载openclaw plugins uninstall openviking openclaw config set plugins.slots.contextEngine legacy openclaw gateway restart当前 OpenClaw 原生卸载不一定会把plugins.slots.contextEngine恢复为legacy显式执行config set可避免 slot 继续指向已卸载插件。从旧版 memory-openviking 迁移旧插件插件 IDmemory-openviking版本 0.3.x与新插件不兼容请先清理openclaw plugins uninstall memory-openviking 2/dev/null || true openclaw config set plugins.slots.memory none或直接使用仓库自带的清理脚本bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh之后再安装新插件、重新配置并重启。从ov-install安装的旧 context-engine 部署文件位于~/.openclaw/extensions/openviking/切换到openclaw plugins install前需要清理该目录已有配置字段baseUrl、apiKey、peer_role、peer_prefix等会保留。故障排查问题处理插件未生效重跑安装再执行openclaw gateway restart401 / 403检查鉴权凭据plugins.slots.contextEngine不是openviking插件槽位未设置或被其他插件覆盖检查openclaw config get plugins.slots.contextEngine无法连接 OpenViking 服务baseUrl配置错误或服务未启动手动测试curl http://baseUrl/healthrecall 在不同 session 间不稳定路由身份和预期不一致打开logFindRequests再看openclaw logs --follow长对话后没有持续抽取记忆pending_tokens未过阈值或服务端抽取失败检查插件配置和~/.openviking/data/log/openviking.logsummary 太粗不够回答细节问题用[Archive Index]里的 ID 调用ov_archive_expand读取 archive 级原文日志与运维入口OpenClaw 插件侧日志openclaw logs --followOpenViking 服务侧日志cat ~/.openviking/data/log/openviking.log查看当前配置openclaw openviking status --json openclaw plugins list openclaw config get plugins.entries.openviking.config openclaw config get plugins.slots.contextEngine继续深入完整安装、升级、卸载指南INSTALL-ZH.md插件设计说明架构、身份与路由、hook 生命周期README_CN.md插件配置源码全部参数与默认值config.ts集成能力参考16-capability-reference.md健康检查工具ov-healthcheck.py【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考