2026/9/11 2:05:07
FEATURED · 精选文章 
为 OpenClaw 安装 OpenViking 插件长期记忆、知识库检索与 RAG 上下文完整接入指南【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本篇指南面向 OpenClaw 用户与自动化 Agent系统讲解如何通过openviking/openclaw-plugin插件为 OpenClaw 接入 OpenViking获得长期记忆、知识库检索、语义搜索与 RAG 上下文能力。读完本文你将掌握从环境检查、OpenViking Server 启动、插件安装配置、Gateway 重启验证到升级卸载、端到端健康检查与备用安装路径迁移的完整实战流程并能看懂配置文件中每个核心参数的含义。插件与 Skill 的区别先避免一个常见坑openviking/openclaw-plugin是 OpenClaw 插件plugin不是 AgentSkill。两者安装方式完全不同错误命令clawhub install openviking—— 这条命令安装的是名为openviking的 AgentSkill不是OpenClaw 插件正确命令openclaw plugins install clawhub:openviking/openclaw-plugin从仓库中的 openclaw.plugin.json 可以看到该插件的kind为context-engine插件 ID 为openviking并声明了add_resource、ov_search、memory_recall、memory_store、ov_archive_search等一系列工具契约同时内置了install-openviking-memory、openviking-context-database、ov-experience-memory三个 skill。前置要求与版本边界组件要求Node.js 22OpenClaw 2026.5.27插件以远程模式连接到已有的 OpenViking 服务它不会帮你启动 OpenViking server。需要先启动 OpenViking 并保持服务运行再把插件的baseUrl指向这个 HTTP 服务默认本地地址为http://127.0.0.1:1933。仓库中 package.json 的engines.openclaw字段同样声明了2026.5.27与文档要求一致。该版本下限包含 2026 年 7 月 2 日 OpenClaw 安全公告批次的修复包括 GHSA-8wg3-5mcm-fjq8 与 GHSA-83w9-h5wv-j9xm。此外需要注意几个版本行为边界从2026.5.3开始OpenClaw 在安装包时会校验 TypeScript 插件入口是否包含编译后的 JavaScript 产物从2026.5.4开始已安装/全局插件若缺少编译后的 JavaScript运行时不再回退加载.ts源码插件可能被跳过推荐的openclaw plugins install clawhub:openviking/openclaw-plugin安装的是已发布且包含dist/*.js的插件包普通用户不需要本地编译ov-install是备用/源码安装路径仅在 ClawHub 或插件管理器不可用、被限流或需要测试源码 ref 时使用。安装前先做快速检查node -v openclaw --version场景一火山 OpenViking Service 一键接入如果你使用的是火山控制台创建的 OpenViking Service 库则无需启动本地openviking-server。从控制台复制 OpenViking Service 的 server url 与 API Key并按需配置 peer 标识即可OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYyour-openviking-service-api-key \ bash scripts/install.sh --json这条命令会依次完成默认从 TOSlatest安装 OpenViking 插件写入$OPENCLAW_STATE_DIR/openviking.env默认~/.openclaw/openviking.env权限为0600调用openclaw openviking setup --base-url ... --api-key ...写入插件配置重启openclaw gateway执行openclaw openviking status --json与openclaw config get plugins.slots.contextEngine做验证。如果需要把 OpenClaw assistant 说话人写成独立的peer_id并让数据面 recall/search 使用对应 actor peer 视图可额外传入OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYyour-openviking-service-api-key \ OPENVIKING_PEER_ROLEassistant \ OPENVIKING_PEER_PREFIXopenclaw-prod \ bash scripts/install.sh --json如果使用 root key 或可信服务身份需要补充租户信息OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYroot-key \ OPENVIKING_ACCOUNT_IDaccount-id \ OPENVIKING_USER_IDuser-id \ bash scripts/install.sh --json离线下载包安装先本地执行sh build.sh构建出output/openviking.tgzsh build.sh OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYyour-openviking-service-api-key \ OPENVIKING_PEER_ROLEassistant \ OPENVIKING_PEER_PREFIXopenclaw-prod \ bash output/install.sh --source tarball --tarball output/openviking.tgz --json底层实现可参考 scripts/install.sh脚本会通过jq将plugins.entries.openviking.enabled置为true把openviking追加进plugins.allow并在当前没有其他 context engine 占用 slot 时写入plugins.slots.contextEngine openviking若已有其他 context engine脚本会保留原值并提示手动切换避免误覆盖。接入后在火山 OpenViking Service 控制台检查发送一轮 OpenClaw 对话后Session下出现原始会话触发/compact或等待 commit 后User/memories出现长期记忆若配置了peer_roleassistant数据面 recall/search 会携带对应的X-OpenViking-Actor-Peersession message 仍用 bodypeer_id做消息归因通过手动/add-resource导入文档、URL 或目录后Resources下出现对应知识并可做目录递归检索。Agent 可见的add_resource工具默认禁用只有显式设置enableAddResourceTooltrue后才暴露。场景二启动本地 OpenViking Server如果 OpenViking 与 OpenClaw 在同一台机器上最短流程是pip install openviking --upgrade --force-reinstall openviking-server init openviking-server doctor openviking-server三个命令各司其职openviking-server init生成服务端配置openviking-server doctor检查本地模型和 provider 鉴权是否可用openviking-server真正启动 HTTP API。OpenClaw 使用插件期间这个服务进程需要一直运行。后台启动方式mkdir -p ~/.openviking/data/log nohup openviking-server ~/.openviking/data/log/openviking.log 21 如果 OpenViking 跑在另一台机器上需要监听可访问的地址和端口openviking-server --host 0.0.0.0 --port 1933然后把 OpenClaw 插件的baseUrl配置成对应地址例如http://your-server:1933。安装或重启插件前先确认服务可访问curl http://127.0.0.1:1933/health推荐安装方式普通用户 / 正式环境 / Agent 自动安装1. 安装插件openclaw plugins install clawhub:openviking/openclaw-plugin如果你的 OpenClaw 环境需要显式 registry 前缀同样使用带clawhub:前缀的完整形式openclaw plugins install clawhub:openviking/openclaw-plugin2. 配置插件用户交互式配置openclaw openviking setupAgent 非交互配置openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --json示例openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --jsonsetup会写入plugins.entries.openviking.config并激活plugins.slots.contextEngineopenviking。如果 OpenViking 服务暂时不可达但仍希望先保存配置openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --allow-offline --json如果使用 root API key可能还需要租户上下文openclaw openviking setup \ --base-url OPENVIKING_URL \ --api-key ROOT_API_KEY \ --account-id ACCOUNT_ID \ --user-id USER_ID \ --json如果已有其他 context engine 占用 slotsetup 默认不会替换。确认要替换时再使用openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --force-slot --json选择--peer-role记忆归属的三种模式根据 OpenViking user 代表谁来选择值存储示例适用场景none默认viking://user/alice/memories/...该 OpenViking 用户下的所有对话共享 user-level 记忆不使用具体 peer 的记忆子树。assistantviking://user/alice/peers/main/memories/...OpenViking user 代表人并希望把 assistant 归因的 peer 记忆按不同 OpenClaw 助手分开。senderviking://user/support-agent/peers/customer-42/memories/...OpenViking user 代表 agent并希望把 sender 归因的 peer 记忆按不同发送者分开。person仍作为sender的旧配置别名被兼容新配置请使用sender。例如让每个助手使用独立的 peer 记忆并可选给 assistant id 加前缀openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --peer-role assistant --peer-prefix PREFIX --json如果 OpenViking user 是 agent按给它发消息的 sender 分开 peer 记忆openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --peer-role sender --jsonOpenViking 会为每个用户初始化受管的peers/容器。none表示插件不创建、也不路由到具体的peers/peer_id/memories子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆切换配置不会搬迁已有记忆。从 openclaw.plugin.json 的configSchema可以看到peer_role的合法取值为none、assistant、sender与person默认值为none。无法执行 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 } } }注意以下约束插件必须已经安装编辑前请备份配置并把以上字段合并到现有plugins配置如果配置中已有plugins.allow把openviking追加进去如果没有不要仅为本插件新建 allowlistcontextEngine是独占 slot若已有其他 context engine只有确认替换后再修改该字段。使用 root API key 时还需在config中设置accountId和userId容器连接其他服务时baseUrl应使用容器内可访问的服务地址而不是127.0.0.1推荐使用SecretRef对象作为apiKey而不是明文字符串避免密钥直接落盘写入openclaw.json。支持的形式与 OpenClaw 核心中 LLM/TTS/MCP 等 provider 配置使用的标准SecretRef一致类型示例说明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。仍可使用纯字符串形式含${ENV_VAR}插值作为向后兼容路径此时请限制文件权限或通过受控 Secret 卷提供并在修改后重启 Gateway、容器或 Pod。3. 重启 OpenClaw Gatewayopenclaw gateway restart如果你的 OpenClaw 版本使用不同的重启命令请使用对应的 gateway 重启方式。4. 验证openclaw openviking status --json期望结果JSON 字段期望值configuredtrueslotActivetruehealth.ok服务可达时应为true也可以直接查看 OpenClaw 配置openclaw config get plugins.entries.openviking.config openclaw config get plugins.slots.contextEngineplugins.slots.contextEngine应输出openviking。Agent 自动化的判断规则Agent 应优先使用--json输出并根据以下字段判断下一步动作结果含义建议动作success: true配置已保存setup 完成重启 gateway然后执行 statussuccess: false,action: slot_blocked配置可能已保存但其他插件占用contextEngine询问用户后再用--force-slotsuccess: false,action: error校验失败展示error不要宣称安装成功health.ok: false服务不可达检查 URL/服务状态只有用户接受时才用--allow-offlinekeyProbe.keyType: root_keyroot key 需要租户上下文追加--account-id和--user-id这套设计让自动化流程可以像状态机一样稳定推进配置成功 → 重启 → 验证slot 被占 → 询问用户 → 强制替换校验失败 → 如实报告服务不可达 → 检查网络 → 必要时离线保存。配置说明与核心参数插件配置位于plugins.entries.openviking.config核心字段字段默认值说明moderemote兼容旧配置的字段。当前只支持 remote。baseUrlhttp://127.0.0.1:1933OpenViking HTTP 地址apiKey空OpenViking API keypeer_rolenone记忆归属none共享viking://user/user_id/memories、assistant.../peers/assistant_id/memories或sender.../peers/sender_id/memories。旧值person作为sender的别名兼容。Session message 使用 bodypeer_id数据面 recall/search 使用X-OpenViking-Actor-Peer。peer_prefix空peer_roleassistant时 assistantpeer_id/ actor peer 值的可选前缀。accountId空使用 root API key 时需要userId空使用 root API key 时需要普通修改优先使用 setup 的重新配置模式openclaw openviking setup --reconfigure查看当前配置openclaw config get plugins.entries.openviking.config从 openclaw.plugin.json 的configSchema与uiHints还可以看到更丰富的可选高级参数例如autoCapture/autoRecall是否自动捕获会话记忆、是否自动注入相关记忆recallTargetTypes召回目标类型user、agent、resource默认user,agentrecallLimit默认 6、recallScoreThreshold默认 0.15、recallMaxInjectedChars默认 4000控制召回数量、分数门槛与注入字符上限commitTokenThresholdRatio默认 0.5待处理 token 达到模型上下文窗口该比例时触发自动 commitenableAddResourceTool默认false是否向 Agent 暴露add_resource工具bypassSessionPatterns对匹配的 session key 完全绕过 OpenViking不做 capture、recall、commitcompaction 回退到 OpenClaw 原生 compactor。这些参数都可以用openclaw 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升级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 继续指向已卸载的插件。可选链路健康检查验证 Gateway 到 OpenViking 的完整链路如果status已通过还想验证 Gateway 到 OpenViking 的完整链路可以在仓库 checkout 中运行python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py该脚本只依赖 Python 标准库地址和 token 会从openclaw.json自动读取。它会注入一次真实对话并在 OpenViking 侧验证会话捕获、提交、归档和记忆提取。详细原理与参数说明见 health_check_tools/HEALTHCHECK-ZH.md。从健康检查文档可知其核心工作流分五个阶段通过 Gateway/v1/responses注入带唯一 probe 标记的真实对话 → 扫描 OpenViking sessions 验证捕获 → 触发 commit 并轮询归档与记忆抽取 → 分别做同 session 追问与新 session 召回验证 → 清理本次产生的 synthetic session 与 memory。需要注意的是Phase 1 依赖 Gateway 的/v1/responses接口该接口默认关闭需要在openclaw.json中启用{ gateway: { http: { endpoints: { chatCompletions: { enabled: true }, responses: { enabled: true } } } } }启用后重启 Gateway。若未启用Phase 1 会以 HTTP 404 失败。Phase 3 等待异步 commit 完成默认最多 300 秒属于正常现象——commit 涉及 LLM 调用来做归档和记忆抽取。备用路径ov-installov-install是备用路径不是主安装方式。仅当openclaw plugins install clawhub:openviking/openclaw-plugin无法访问 ClawHub、被限流或者你明确需要从 Git 分支/源码 ref 安装测试时使用。先尝试 OpenClaw 插件管理器。如果该路径不可用再执行npm install -g openclaw-openviking-setup-helper ov-install常用备用/源码参数参数含义--workdir PATH指定 OpenClaw state 目录--plugin-versionREF指定插件版本npm 版本、npm dist-tag 或 Git ref--current-version查看 helper 记录的当前版本--base-url URLOpenViking 服务器地址启用非交互模式--api-key KEYOpenViking API key--peer-role ROLE记忆归属none、assistant或sender旧值person作为sender的别名兼容--peer-prefix PREFIXassistantpeer_id/ actor peer 值的前缀--update更新 helper 管理的安装面向用户的安装请优先使用openclaw plugins install clawhub:openviking/openclaw-plugin只有作为备用路径时才选择ov-install。从 ov-install 迁移到 openclaw plugin install如果之前通过ov-install安装了 OpenViking切换到推荐的openclaw plugins install安装方式前需要清理。同一插件 IDopenviking版本 0.3.xov-install 的 context-engine 部署会将文件写入~/.openclaw/extensions/openviking/。通过 npm 安装后OpenClaw 可能仍从旧目录加载。清理步骤# 删除 ov-install 部署的文件 rm -rf ~/.openclaw/extensions/openviking/ # 通过 OpenClaw 插件管理器安装 openclaw plugins install clawhub:openviking/openclaw-plugin # 重新配置openclaw.json 中的已有配置会保留 openclaw openviking setup --reconfigure openclaw gateway restart openclaw openviking status --json已有的配置字段baseUrl、apiKey、peer_role、peer_prefix等会保留。旧插件 IDmemory-openviking版本 0.3.x旧版 memory 插件使用了不同的插件 ID 和 slot# 卸载旧插件 openclaw plugins uninstall memory-openviking 2/dev/null || true # 清理旧 slot 和文件 openclaw config set plugins.slots.memory none rm -rf ~/.openclaw/extensions/memory-openviking/ # 安装新插件 openclaw plugins install clawhub:openviking/openclaw-plugin openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --json openclaw gateway restart openclaw openviking status --json或直接使用仓库提供的清理脚本bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh小结整个接入流程可以概括为一条主线先确保 OpenViking 服务可达再用插件管理器安装openviking/openclaw-plugin通过setup写入配置并激活contextEngineslot重启 Gateway最后用status --json验证。核心决策点有三个一是选对安装路径推荐openclaw plugins installov-install仅作备用二是选对记忆归属peer_role的none/assistant/sender决定记忆落在viking://URI 的哪棵子树三是密钥安全优先SecretRef的env/file形态避免明文落盘。文中所有命令与配置均以当前仓库 INSTALL-ZH.md 及 openclaw.plugin.json、scripts/install.sh、health_check_tools/HEALTHCHECK-ZH.md 为准可放心作为操作手册使用。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
为 OpenClaw 安装 OpenViking 插件：长期记忆、知识库检索与 RAG 上下文完整接入指南
为 OpenClaw 安装 OpenViking 插件长期记忆、知识库检索与 RAG 上下文完整接入指南【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本篇指南面向 OpenClaw 用户与自动化 Agent系统讲解如何通过openviking/openclaw-plugin插件为 OpenClaw 接入 OpenViking获得长期记忆、知识库检索、语义搜索与 RAG 上下文能力。读完本文你将掌握从环境检查、OpenViking Server 启动、插件安装配置、Gateway 重启验证到升级卸载、端到端健康检查与备用安装路径迁移的完整实战流程并能看懂配置文件中每个核心参数的含义。插件与 Skill 的区别先避免一个常见坑openviking/openclaw-plugin是 OpenClaw 插件plugin不是 AgentSkill。两者安装方式完全不同错误命令clawhub install openviking—— 这条命令安装的是名为openviking的 AgentSkill不是OpenClaw 插件正确命令openclaw plugins install clawhub:openviking/openclaw-plugin从仓库中的 openclaw.plugin.json 可以看到该插件的kind为context-engine插件 ID 为openviking并声明了add_resource、ov_search、memory_recall、memory_store、ov_archive_search等一系列工具契约同时内置了install-openviking-memory、openviking-context-database、ov-experience-memory三个 skill。前置要求与版本边界组件要求Node.js 22OpenClaw 2026.5.27插件以远程模式连接到已有的 OpenViking 服务它不会帮你启动 OpenViking server。需要先启动 OpenViking 并保持服务运行再把插件的baseUrl指向这个 HTTP 服务默认本地地址为http://127.0.0.1:1933。仓库中 package.json 的engines.openclaw字段同样声明了2026.5.27与文档要求一致。该版本下限包含 2026 年 7 月 2 日 OpenClaw 安全公告批次的修复包括 GHSA-8wg3-5mcm-fjq8 与 GHSA-83w9-h5wv-j9xm。此外需要注意几个版本行为边界从2026.5.3开始OpenClaw 在安装包时会校验 TypeScript 插件入口是否包含编译后的 JavaScript 产物从2026.5.4开始已安装/全局插件若缺少编译后的 JavaScript运行时不再回退加载.ts源码插件可能被跳过推荐的openclaw plugins install clawhub:openviking/openclaw-plugin安装的是已发布且包含dist/*.js的插件包普通用户不需要本地编译ov-install是备用/源码安装路径仅在 ClawHub 或插件管理器不可用、被限流或需要测试源码 ref 时使用。安装前先做快速检查node -v openclaw --version场景一火山 OpenViking Service 一键接入如果你使用的是火山控制台创建的 OpenViking Service 库则无需启动本地openviking-server。从控制台复制 OpenViking Service 的 server url 与 API Key并按需配置 peer 标识即可OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYyour-openviking-service-api-key \ bash scripts/install.sh --json这条命令会依次完成默认从 TOSlatest安装 OpenViking 插件写入$OPENCLAW_STATE_DIR/openviking.env默认~/.openclaw/openviking.env权限为0600调用openclaw openviking setup --base-url ... --api-key ...写入插件配置重启openclaw gateway执行openclaw openviking status --json与openclaw config get plugins.slots.contextEngine做验证。如果需要把 OpenClaw assistant 说话人写成独立的peer_id并让数据面 recall/search 使用对应 actor peer 视图可额外传入OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYyour-openviking-service-api-key \ OPENVIKING_PEER_ROLEassistant \ OPENVIKING_PEER_PREFIXopenclaw-prod \ bash scripts/install.sh --json如果使用 root key 或可信服务身份需要补充租户信息OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYroot-key \ OPENVIKING_ACCOUNT_IDaccount-id \ OPENVIKING_USER_IDuser-id \ bash scripts/install.sh --json离线下载包安装先本地执行sh build.sh构建出output/openviking.tgzsh build.sh OPENVIKING_BASE_URLhttps://api.vikingdb.cn-beijing.volces.com/openviking \ OPENVIKING_API_KEYyour-openviking-service-api-key \ OPENVIKING_PEER_ROLEassistant \ OPENVIKING_PEER_PREFIXopenclaw-prod \ bash output/install.sh --source tarball --tarball output/openviking.tgz --json底层实现可参考 scripts/install.sh脚本会通过jq将plugins.entries.openviking.enabled置为true把openviking追加进plugins.allow并在当前没有其他 context engine 占用 slot 时写入plugins.slots.contextEngine openviking若已有其他 context engine脚本会保留原值并提示手动切换避免误覆盖。接入后在火山 OpenViking Service 控制台检查发送一轮 OpenClaw 对话后Session下出现原始会话触发/compact或等待 commit 后User/memories出现长期记忆若配置了peer_roleassistant数据面 recall/search 会携带对应的X-OpenViking-Actor-Peersession message 仍用 bodypeer_id做消息归因通过手动/add-resource导入文档、URL 或目录后Resources下出现对应知识并可做目录递归检索。Agent 可见的add_resource工具默认禁用只有显式设置enableAddResourceTooltrue后才暴露。场景二启动本地 OpenViking Server如果 OpenViking 与 OpenClaw 在同一台机器上最短流程是pip install openviking --upgrade --force-reinstall openviking-server init openviking-server doctor openviking-server三个命令各司其职openviking-server init生成服务端配置openviking-server doctor检查本地模型和 provider 鉴权是否可用openviking-server真正启动 HTTP API。OpenClaw 使用插件期间这个服务进程需要一直运行。后台启动方式mkdir -p ~/.openviking/data/log nohup openviking-server ~/.openviking/data/log/openviking.log 21 如果 OpenViking 跑在另一台机器上需要监听可访问的地址和端口openviking-server --host 0.0.0.0 --port 1933然后把 OpenClaw 插件的baseUrl配置成对应地址例如http://your-server:1933。安装或重启插件前先确认服务可访问curl http://127.0.0.1:1933/health推荐安装方式普通用户 / 正式环境 / Agent 自动安装1. 安装插件openclaw plugins install clawhub:openviking/openclaw-plugin如果你的 OpenClaw 环境需要显式 registry 前缀同样使用带clawhub:前缀的完整形式openclaw plugins install clawhub:openviking/openclaw-plugin2. 配置插件用户交互式配置openclaw openviking setupAgent 非交互配置openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --json示例openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --jsonsetup会写入plugins.entries.openviking.config并激活plugins.slots.contextEngineopenviking。如果 OpenViking 服务暂时不可达但仍希望先保存配置openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --allow-offline --json如果使用 root API key可能还需要租户上下文openclaw openviking setup \ --base-url OPENVIKING_URL \ --api-key ROOT_API_KEY \ --account-id ACCOUNT_ID \ --user-id USER_ID \ --json如果已有其他 context engine 占用 slotsetup 默认不会替换。确认要替换时再使用openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --force-slot --json选择--peer-role记忆归属的三种模式根据 OpenViking user 代表谁来选择值存储示例适用场景none默认viking://user/alice/memories/...该 OpenViking 用户下的所有对话共享 user-level 记忆不使用具体 peer 的记忆子树。assistantviking://user/alice/peers/main/memories/...OpenViking user 代表人并希望把 assistant 归因的 peer 记忆按不同 OpenClaw 助手分开。senderviking://user/support-agent/peers/customer-42/memories/...OpenViking user 代表 agent并希望把 sender 归因的 peer 记忆按不同发送者分开。person仍作为sender的旧配置别名被兼容新配置请使用sender。例如让每个助手使用独立的 peer 记忆并可选给 assistant id 加前缀openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --peer-role assistant --peer-prefix PREFIX --json如果 OpenViking user 是 agent按给它发消息的 sender 分开 peer 记忆openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --peer-role sender --jsonOpenViking 会为每个用户初始化受管的peers/容器。none表示插件不创建、也不路由到具体的peers/peer_id/memories子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆切换配置不会搬迁已有记忆。从 openclaw.plugin.json 的configSchema可以看到peer_role的合法取值为none、assistant、sender与person默认值为none。无法执行 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 } } }注意以下约束插件必须已经安装编辑前请备份配置并把以上字段合并到现有plugins配置如果配置中已有plugins.allow把openviking追加进去如果没有不要仅为本插件新建 allowlistcontextEngine是独占 slot若已有其他 context engine只有确认替换后再修改该字段。使用 root API key 时还需在config中设置accountId和userId容器连接其他服务时baseUrl应使用容器内可访问的服务地址而不是127.0.0.1推荐使用SecretRef对象作为apiKey而不是明文字符串避免密钥直接落盘写入openclaw.json。支持的形式与 OpenClaw 核心中 LLM/TTS/MCP 等 provider 配置使用的标准SecretRef一致类型示例说明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。仍可使用纯字符串形式含${ENV_VAR}插值作为向后兼容路径此时请限制文件权限或通过受控 Secret 卷提供并在修改后重启 Gateway、容器或 Pod。3. 重启 OpenClaw Gatewayopenclaw gateway restart如果你的 OpenClaw 版本使用不同的重启命令请使用对应的 gateway 重启方式。4. 验证openclaw openviking status --json期望结果JSON 字段期望值configuredtrueslotActivetruehealth.ok服务可达时应为true也可以直接查看 OpenClaw 配置openclaw config get plugins.entries.openviking.config openclaw config get plugins.slots.contextEngineplugins.slots.contextEngine应输出openviking。Agent 自动化的判断规则Agent 应优先使用--json输出并根据以下字段判断下一步动作结果含义建议动作success: true配置已保存setup 完成重启 gateway然后执行 statussuccess: false,action: slot_blocked配置可能已保存但其他插件占用contextEngine询问用户后再用--force-slotsuccess: false,action: error校验失败展示error不要宣称安装成功health.ok: false服务不可达检查 URL/服务状态只有用户接受时才用--allow-offlinekeyProbe.keyType: root_keyroot key 需要租户上下文追加--account-id和--user-id这套设计让自动化流程可以像状态机一样稳定推进配置成功 → 重启 → 验证slot 被占 → 询问用户 → 强制替换校验失败 → 如实报告服务不可达 → 检查网络 → 必要时离线保存。配置说明与核心参数插件配置位于plugins.entries.openviking.config核心字段字段默认值说明moderemote兼容旧配置的字段。当前只支持 remote。baseUrlhttp://127.0.0.1:1933OpenViking HTTP 地址apiKey空OpenViking API keypeer_rolenone记忆归属none共享viking://user/user_id/memories、assistant.../peers/assistant_id/memories或sender.../peers/sender_id/memories。旧值person作为sender的别名兼容。Session message 使用 bodypeer_id数据面 recall/search 使用X-OpenViking-Actor-Peer。peer_prefix空peer_roleassistant时 assistantpeer_id/ actor peer 值的可选前缀。accountId空使用 root API key 时需要userId空使用 root API key 时需要普通修改优先使用 setup 的重新配置模式openclaw openviking setup --reconfigure查看当前配置openclaw config get plugins.entries.openviking.config从 openclaw.plugin.json 的configSchema与uiHints还可以看到更丰富的可选高级参数例如autoCapture/autoRecall是否自动捕获会话记忆、是否自动注入相关记忆recallTargetTypes召回目标类型user、agent、resource默认user,agentrecallLimit默认 6、recallScoreThreshold默认 0.15、recallMaxInjectedChars默认 4000控制召回数量、分数门槛与注入字符上限commitTokenThresholdRatio默认 0.5待处理 token 达到模型上下文窗口该比例时触发自动 commitenableAddResourceTool默认false是否向 Agent 暴露add_resource工具bypassSessionPatterns对匹配的 session key 完全绕过 OpenViking不做 capture、recall、commitcompaction 回退到 OpenClaw 原生 compactor。这些参数都可以用openclaw 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升级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 继续指向已卸载的插件。可选链路健康检查验证 Gateway 到 OpenViking 的完整链路如果status已通过还想验证 Gateway 到 OpenViking 的完整链路可以在仓库 checkout 中运行python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py该脚本只依赖 Python 标准库地址和 token 会从openclaw.json自动读取。它会注入一次真实对话并在 OpenViking 侧验证会话捕获、提交、归档和记忆提取。详细原理与参数说明见 health_check_tools/HEALTHCHECK-ZH.md。从健康检查文档可知其核心工作流分五个阶段通过 Gateway/v1/responses注入带唯一 probe 标记的真实对话 → 扫描 OpenViking sessions 验证捕获 → 触发 commit 并轮询归档与记忆抽取 → 分别做同 session 追问与新 session 召回验证 → 清理本次产生的 synthetic session 与 memory。需要注意的是Phase 1 依赖 Gateway 的/v1/responses接口该接口默认关闭需要在openclaw.json中启用{ gateway: { http: { endpoints: { chatCompletions: { enabled: true }, responses: { enabled: true } } } } }启用后重启 Gateway。若未启用Phase 1 会以 HTTP 404 失败。Phase 3 等待异步 commit 完成默认最多 300 秒属于正常现象——commit 涉及 LLM 调用来做归档和记忆抽取。备用路径ov-installov-install是备用路径不是主安装方式。仅当openclaw plugins install clawhub:openviking/openclaw-plugin无法访问 ClawHub、被限流或者你明确需要从 Git 分支/源码 ref 安装测试时使用。先尝试 OpenClaw 插件管理器。如果该路径不可用再执行npm install -g openclaw-openviking-setup-helper ov-install常用备用/源码参数参数含义--workdir PATH指定 OpenClaw state 目录--plugin-versionREF指定插件版本npm 版本、npm dist-tag 或 Git ref--current-version查看 helper 记录的当前版本--base-url URLOpenViking 服务器地址启用非交互模式--api-key KEYOpenViking API key--peer-role ROLE记忆归属none、assistant或sender旧值person作为sender的别名兼容--peer-prefix PREFIXassistantpeer_id/ actor peer 值的前缀--update更新 helper 管理的安装面向用户的安装请优先使用openclaw plugins install clawhub:openviking/openclaw-plugin只有作为备用路径时才选择ov-install。从 ov-install 迁移到 openclaw plugin install如果之前通过ov-install安装了 OpenViking切换到推荐的openclaw plugins install安装方式前需要清理。同一插件 IDopenviking版本 0.3.xov-install 的 context-engine 部署会将文件写入~/.openclaw/extensions/openviking/。通过 npm 安装后OpenClaw 可能仍从旧目录加载。清理步骤# 删除 ov-install 部署的文件 rm -rf ~/.openclaw/extensions/openviking/ # 通过 OpenClaw 插件管理器安装 openclaw plugins install clawhub:openviking/openclaw-plugin # 重新配置openclaw.json 中的已有配置会保留 openclaw openviking setup --reconfigure openclaw gateway restart openclaw openviking status --json已有的配置字段baseUrl、apiKey、peer_role、peer_prefix等会保留。旧插件 IDmemory-openviking版本 0.3.x旧版 memory 插件使用了不同的插件 ID 和 slot# 卸载旧插件 openclaw plugins uninstall memory-openviking 2/dev/null || true # 清理旧 slot 和文件 openclaw config set plugins.slots.memory none rm -rf ~/.openclaw/extensions/memory-openviking/ # 安装新插件 openclaw plugins install clawhub:openviking/openclaw-plugin openclaw openviking setup --base-url OPENVIKING_URL --api-key API_KEY --json openclaw gateway restart openclaw openviking status --json或直接使用仓库提供的清理脚本bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh小结整个接入流程可以概括为一条主线先确保 OpenViking 服务可达再用插件管理器安装openviking/openclaw-plugin通过setup写入配置并激活contextEngineslot重启 Gateway最后用status --json验证。核心决策点有三个一是选对安装路径推荐openclaw plugins installov-install仅作备用二是选对记忆归属peer_role的none/assistant/sender决定记忆落在viking://URI 的哪棵子树三是密钥安全优先SecretRef的env/file形态避免明文落盘。文中所有命令与配置均以当前仓库 INSTALL-ZH.md 及 openclaw.plugin.json、scripts/install.sh、health_check_tools/HEALTHCHECK-ZH.md 为准可放心作为操作手册使用。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
