企业官网建设流程全解析

为 Claude Code 接入 OpenViking 记忆插件：安装、验证、配置与工作原理全解析

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

本篇技术指南以 OpenViking 官方文档 docs/images/agents/en/claude-code.md 为骨架，结合完整集成指南 docs/en/agent-integrations/02-claude-code.md 与仓库内的插件源码 examples/claude-code-memory-plugin，系统讲解如何在 Claude Code 中安装、验证并调优 OpenViking 记忆插件。读完本文，你将掌握一键/手动两种安装方式、插件健康验证三连命令、完整的环境变量配置体系，以及插件在 Claude Code 生命周期钩子中的底层工作原理。

OpenViking 是一个面向 AI Agent 的"自进化上下文数据库"，统一了 Agent 记忆、知识 RAG 与技能（Skills）。Claude Code 记忆插件（openviking-memory）正是将这套能力接入 Claude Code 的官方途径：安装之后，每次对话前自动召回相关记忆，每次回复后自动捕获新内容，模型无需显式调用任何 MCP 工具，即可获得跨项目、跨会话的长期记忆。

第一步：安装

因为 Claude Code 可能会拦截来源未知的安装脚本，自动安装可能无法顺利完成，官方推荐优先执行下面的手动终端步骤。

一键安装器（推荐）

在终端运行官方安装器，指定 harness 为claude、分发渠道为 TOS 镜像：

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness claude --dist tos

安装器会依次交互询问：

1. 语言：English / 中文；
2. OpenViking 凭据；
3. 是否启用 StatusLine（输入框下方的状态条）。

在 OpenViking 凭据步骤，选择VolcEngine OpenViking Cloud Service [api.vikingdb.cn-beijing.volces.com]，并输入 API KEY：

{{OPENVIKING_API_KEY}}

Claude Code 与 Codex 共用同一个安装器（去掉--harness claude即可交互式选择），它会询问语言、要安装的 harness、下载源以及 OpenViking 凭据；每一步都是幂等的，重复运行完全安全。

在 GitHub 访问困难的区域，可以改用 Volcengine TOS 镜像运行同一安装器（或在下载源提示处选择 "TOS mirror"）：

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)

TOS 渠道对 Claude Code 的注意事项：TOS 渠道注册的是一个本地目录 marketplace，无法自动更新——需要重新运行安装器来升级。（Codex 在 TOS 上安装自 TOS 托管的 git 仓库，可保持远程更新。）

值得强调的是，不再需要 shell 包装脚本：插件自带一个 stdio MCP 代理，运行时直接读取~/.openviking/ovcli.conf（或OPENVIKING_*环境变量），与 hooks 使用同一套配置来源。

安装并实际使用一段时间后，可以开启一个新会话，询问之前提到过的内容——它会记得。

OpenViking StatusLine

StatusLine 是输入框下方的状态条，实时展示记忆插件的运行状态。例如：

OV ✓ │ Fable 5 · ctx 42% │ ↪ 6 mem (0.92) · 50ms │ ✎ 573/20k · 2 arch

你可以根据偏好启用或跳过它。关于状态条各分段的完整语义与个性化配方，见 examples/claude-code-memory-plugin/STATUSLINE.md，后文"StatusLine 状态条"一节也会展开讲解。

手动安装（可选）

如果倾向手动搭建，可参考 02-claude-code.md 文档的 Manual setup 折叠块：

1. 配置连接——写入~/.openviking/ovcli.conf（包含url、api_key，可选account/user），或在安装后运行插件自带的向导node <plugin-dir>/scripts/setup.mjs：

{ "url": "https://your-openviking-server.example.com", "api_key": "<your-api-key>", "account": "my-team", "user": "alice" }

2. 从远程 marketplace 安装插件（无需 clone 仓库）：

claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json claude plugin install openviking-memory@openviking

若为开发目的，可注册本地 checkout：claude plugin marketplace add "<repo>/examples"后安装同一个插件 ID。两种模式注册的 marketplace 都叫openviking，因此插件 ID 始终是openviking-memory@openviking。

3. 启动 Claude Code并运行/mcp验证 OpenViking 条目已连接。

相关前提：

• 还没有ovcli.conf？参见 Deployment Guide → CLI。
• 纯本地模式（http://127.0.0.1:1933，无认证）？可跳过第 1 步——插件会自动回退到本地默认配置。
• 运行 Claude Code < 2.0？安装器检测到旧版本后会自动回退为claude mcp add+ hooks 合并的方式，详见插件 README 的 Legacy mode 一节。

Legacy 模式（Claude Code < 2.0）：claude plugin自 Claude Code 2.0+（2025 年 10 月）起可用，旧版本仍可通过claude mcp add与 hooks 系统手工接线，大致流程如下：

PLUGIN_DIR="$(pwd)/examples/claude-code-memory-plugin" # stdio MCP 代理——自行读取 ovcli.conf / OPENVIKING_*，无需手工接 header claude mcp remove openviking -s user 2>/dev/null claude mcp add --scope user openviking -- node "$PLUGIN_DIR/servers/mcp-proxy.mjs" # 将插件 hooks 合并进 ~/.claude/settings.json（带备份） mkdir -p ~/.claude && [ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json cp -p ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%s) sed "s|\${CLAUDE_PLUGIN_ROOT}|$PLUGIN_DIR|g" "$PLUGIN_DIR/hooks/hooks.json" > /tmp/ov-hooks.json jq --slurpfile h /tmp/ov-hooks.json '.hooks = ((.hooks // {}) * $h[0].hooks)' \ ~/.claude/settings.json > /tmp/ov-settings.json jq -e . /tmp/ov-settings.json >/dev/null && mv /tmp/ov-settings.json ~/.claude/settings.json rm -f /tmp/ov-hooks.json

一键安装器检测到 pre-2.0 构建时会自动执行上述操作（它会在~/.openviking/openviking-repo保留一份源码 checkout 以支撑上面的绝对路径）。

第二步：验证

重启 Claude Code，然后依次执行三条命令确认插件与 MCP 均已就绪。

1. 运行/plugins，确认已安装列表中出现openviking-memory，且openvikingMCP 已连接：

User ❯ openviking-memory Plugin · openviking · ✔ enabled └ openviking MCP · ✔ connected

2. 运行/mcp，确认显示如下：

Built-in MCPs (always available) ❯ plugin:openviking-memory:openviking · ✔ connected · 10 tools

3. 运行/openviking-memory:ov，确认服务状态健康：

OpenViking Memory Status ✅ Status: OpenViking server is healthy and running

/openviking-memory:ov命令除了展示服务健康状态，还会展示身份信息、召回/注入统计以及开关状态。如果插件看起来没有激活，设置OPENVIKING_DEBUG=1并查看日志~/.openviking/logs/cc-hooks.log。

插件工作原理：hooks 生命周期

插件通过钩住 Claude Code 的生命周期事件实现"零工具调用"的记忆能力（来源：docs/en/agent-integrations/02-claude-code.md）：

• 每次 prompt 之前——检索 OpenViking 并注入相关记忆；
• 每次回复之后——捕获新的对话轮次；
• 会话启动时——注入你的 profile 与记忆索引；
• 压缩（compact）之前与会话结束时——提交挂起的消息；
• 每个子代理（subagent）——分配独立的隔离记忆会话。

所有写操作均为异步执行，绝不会阻塞你的对话。

工具调用与结果会作为专门的toolpart 被捕获，tool_output原样上报。截断是服务端的职责：超过tool_output_externalization.threshold_chars（默认20000）的输出会被写入会话的 tool-result 存储，part 中仅保留摘要 stub 加tool_output_ref，原始内容仍可通过/api/v1/sessions/{id}/tool-results读取。

Hook 注册与职责

从 examples/claude-code-memory-plugin/hooks/hooks.json 可以看到全部 9 个 hook 的注册与超时配置：

异步写路径

Stop、SessionEnd、SubagentStop使用"分离工作进程"模式：父 hook 读完 stdin 后立即输出{decision:"approve"}解除 Claude Code 阻塞，再派生一个分离的克隆进程去执行 HTTP 写操作——用户永远不会等待 OV。PreCompact保持同步，因为 Claude Code 紧接着就会改写 transcript。调试期如需确定性顺序，可通过claude_code.writePathAsync: false关闭该机制。

记忆污染防护

auto-capture在推送每一轮之前会剥离<openviking-context>、<system-reminder>、<relevant-memories>与[Subagent Context]块。若不做这一步，插件本轮注入的召回上下文会在下一轮被当作"用户消息"的一部分重新捕获，形成自引用的污染循环。

召回实现的源码级细节

以 examples/claude-code-memory-plugin/scripts/auto-recall.mjs 为例，可以看清召回的真实数据流：

• 多源检索：同时检索viking://~/memories（记忆）与viking://~/skills（技能）两个源，viking://~是 home 别名，由服务端展开为调用者自己的用户空间，无需客户端改写；
• 服务端优先：优先走服务端上下文组装接口（可带 OV session ID，解锁服务端的查询扩展与跨轮去重账本）；无结果时才回退到本地searchAllSources+ 排序；
• 客户端排序：在基础分数上叠加叶节点 boost（level === 2或.md结尾 +0.12）、事件/偏好意图 boost、词法重叠 boost，并对 events/cases 类记忆按 URI 去重；
• token 预算注入：预算内的高分项携带完整内容，超出预算的项降级为"URI + 分数"提示行，首项即使超预算也强制包含——保证注入块格式如<openviking-context>…</openviking-context>始终可控。

配置体系

解析优先级

每个插件字段按以下链路解析（高 → 低）：

1. 环境变量（OPENVIKING_*，见下方表格）；
2. Workspace registry——本机针对当前仓库的条目~/.openviking/workspaces/<slot>.json；
3. <repo-root>/.openviking/config.local.json——私有、gitignore 的工作区设置；
4. <repo-root>/.openviking/config.json——团队提交的工作区设置；
5. ovcli.conf——CLI 客户端配置（~/.openviking/ovcli.conf或OPENVIKING_CLI_CONFIG_FILE）；连接字段（url、api_key、account、user）加plugin段，plugin.claude_code优先于共享的plugin；
6. ov.conf——服务端配置（~/.openviking/ov.conf或OPENVIKING_CONFIG_FILE）；插件读取server.url、server.root_api_key及遗留的claude_code块；
7. 内置默认值（http://127.0.0.1:1933，无认证）。

三个 workspace 层只承载 Workspace configuration files 中列出的设置；连接与凭据绝不会从它们中读取。同一套连接与身份字段也同时被 stdio MCP 代理使用。

环境变量速查表

所有插件行为都可通过环境变量设置；连接/身份变量同时影响 hooks 与 MCP 代理，调优变量只影响 hooks。

连接 / 身份

召回调优

捕获调优

生命周期 / 行为 / 杂项

纯环境变量示例（无需任何配置文件）：

OPENVIKING_MEMORY_ENABLED=1 \ OPENVIKING_URL=https://openviking.example.com \ OPENVIKING_API_KEY=sk-xxx \ OPENVIKING_ACCOUNT=my-team \ OPENVIKING_USER=alice \ OPENVIKING_RECALL_LIMIT=8 \ claude

启用 / 关闭

三种控制手段（插件 README 的 Enable / disable 一节）：

1. OPENVIKING_MEMORY_ENABLED环境变量——0/false/no强制关闭；1/true/yes强制开启（强制开启且无配置文件时，连接信息必须来自环境变量）；
2. ov.conf中的claude_code.enabled——设为false关闭；
3. 配置文件存在性——存在ov.conf或ovcli.conf即启用；否则静默关闭（不报错，hooks 直接透传）。

跳过某个会话

在/tmpPoC 目录中使用 Claude Code 且不想污染长期记忆：

# 持久生效：任何 session_id 或 cwd 匹配模式的会话 export OPENVIKING_BYPASS_SESSION_PATTERNS='/tmp/**,**/scratch/**,/Users/me/Dev/throwaway/*' # 或一次性： OPENVIKING_BYPASS_SESSION=1 claude

bypass 生效时，每个 hook 都会立即 approve，不联系 OpenViking。

ovcli.conf中的插件设置

客户端侧的调优属于~/.openviking/ovcli.conf的plugin段。共享键对所有 harness 生效；per-harness 对象覆盖它们：

{ "url": "http://127.0.0.1:1933", "plugin": { "recallCompress": "auto" } }

解析顺序：环境变量 → workspace 层 →plugin.claude_code→plugin→ov.conf中遗留的claude_code块 → 内置默认值。除非显式覆盖，插件会省略服务端自有的 Context 默认值（如limit=10、max_tokens=1600、query_expansion="auto"）。显式的遗留recallLimit会转换为按类别拆分的编码配额（1~5 之间取值会产生总计 6 的有效配额，即每个编码域一个检索槽），而非强制性的最终结果上限；新的直接 API 集成应改用quotas配置。

摘要压缩（Digest compression）

recallCompress决定摘要由谁生成，默认auto：

• client——总是通过claude -p本地压缩（默认 Sonnet + 低 effort；Haiku 忽略 effort 旋钮，其延迟不可控），token 成本留在你自己的订阅上；
• server——由 OpenViking 生成摘要；
• auto——本地优先，找不到健康的宿主 CLI 时回退到服务端。

压缩执行或输出校验失败时，回退到未压缩的上下文块；任一压缩器返回精确的NO_RELEVANT_MEMORY都视为成功的空结果，不注入任何内容。压缩子进程运行时会禁用所有 OpenViking hooks，避免递归。旧的环境变量OPENVIKING_RECALL_REWRITE与配置键recallRewrite仍作为低优先级兼容别名受支持。

ov.conf中的遗留claude_code块

早期版本在~/.openviking/ov.conf的claude_code块下配置调优字段，目前仍为向后兼容而支持——每个环境变量都有对应的 camelCase 形式（OPENVIKING_RECALL_LIMIT→claude_code.recallLimit、OPENVIKING_BYPASS_SESSION_PATTERNS→claude_code.bypassSessionPatterns为 JSON 数组等）。环境变量优先。新部署应优先使用环境变量与 shell rc——服务端配置文件不应携带逐开发者机器的调优。

Workspace 配置文件

仓库可以携带自己的插件设置：<repo-root>/.openviking/config.json（团队提交）与<repo-root>/.openviking/config.local.json（私有、gitignored）。第三层——本机在~/.openviking/workspaces/下的条目——优先于两者。

{ "version": 1, "peer": { "source": "git" }, "recall": { "peer_scope": "actor" }, "bypass": { "session_patterns": ["**/fixtures/**"] } }

version: 1是必需的；声明其他版本的文件会被跳过并告警。Schema v1 支持peer.source、peer.id、recall.enabled、recall.peer_scope、recall.dedup_turns、recall.max_items、recall.score_threshold、capture.enabled、capture.commit_token_threshold、bypass.session_patterns与labels。列表跨层取并集，前导"!reset"丢弃继承值；未知键保留并忽略。由于 hook 是非交互式的（逐 workspace 的审批门会导致每个命令都要确认），这些文件被直接信任；被拒绝的是结构性问题：连接与凭据键（url、api_key、account、user、extra_headers等）会被剥离并告警，且其中的${VAR}永不展开。完整 schema 见 Client Configuration → Workspace Configuration。

注意.gitignore不要整体忽略.openviking/（否则config.json永远无法提交），应把规则收窄到.openviking/media/与.openviking/downloads/。

Workspace Peer：一个项目一份记忆

记忆归档在由当前仓库推导出的 peer 之下，因此一个项目在克隆、worktree、子目录之间共享同一份记忆。默认peer.source: "git"使用仓库归一化后的originURL——例如origin git@github.com:volcengine/OpenViking.git对应的 peer 是github.com-volcengine-openviking——回退到仓库根路径；仓库之外则不发送 peer，此时的记忆进入用户级空间viking://user/<you>/memories。fork 有自己的origin，因此保持独立 peer。

可通过OPENVIKING_PEER_SOURCE、ovcli.conf中的plugin.peerSource、或 workspace 的.openviking/config.json中的peer.source修改：

模板变量为{git_remote}、{git_root}、{cwd}、{dir}（详见 memory-plugin-shared 的 Workspace Peers）。推导是纯文件系统操作、不派生git子进程，因此在git不在 PATH 或拒绝 dubious ownership 仓库时依然成立。想给非仓库目录独立的 peer，在该目录创建.openviking/config.json：{"version": 1, "peer": {"id": "my-project"}}。

从旧路径推导 peer 升级无需任何操作：旧 ID 下写入的记忆仍可被召回（默认peer_scope: "all"时服务端的跨 peer 清扫已覆盖；actor作用域下插件会单独询问旧 peer）。OPENVIKING_PEER_SOURCE=cwd可彻底恢复旧 ID。

StatusLine 状态条

插件在 Claude Code 输入框下方渲染一行 OpenViking 状态指示，让你一眼看到连接健康度、召回数、捕获进度与会话状态。完整分段术语表与个性化配方见 examples/claude-code-memory-plugin/STATUSLINE.md。

各分段的常见形态（来自插件 README 与 STATUSLINE.md）：

OV ✓ │ Fable 5 · ctx 42% │ ↩ 6 mem · 50ms 6 条记忆已注入；模型 + 上下文用量 OV ⚠ slow probe 超过 1s 预算（服务端可能滞后） OV ✗ offline 服务端不可达 OV ⚡ bypass │ Fable 5 · ctx 42% 命中 OPENVIKING_BYPASS_SESSION* OV ✓ │ ✎ 573/20k · 2 arch 挂起捕获，本会话已产生两个归档 OV ✓ │ 🔗 resumed │ +3 today 会话已补水；今天已提交 3 个归档

要点：

• ctx百分比复刻 Claude Code 原生上下文指示（自定义 statusLine 会替换原生指示），沿用原生颜色阈值：<70%暗色、70–89%黄色、≥90%红色；可用OPENVIKING_STATUSLINE_CTX=off隐藏；
• 数据流：auto-recall.mjs/auto-capture.mjs/session-start.mjs每轮把小型快照写入~/.openviking/state/{last-recall,last-capture,last-session-event,daily-stats}.json；scripts/statusline.mjs读取这些快照外加 5 秒共享缓存的GET /health；网络调用有硬性的 1s 超时，缓存跨 CC 会话共享以防惊群；
• 整行硬性上限 100 个可见字符，超出尾部截断为…；
• 停用/自定义：OPENVIKING_STATUSLINE=off静默（保留注册）；NO_COLOR=1（或非 TTY）自动去除 ANSI 颜色；彻底移除用jq 'del(.statusLine)' ~/.claude/settings.json；已有自定义 statusline 时安装器会提示替换/跳过/手工合成。

调试与排障

调试日志

在ov.conf设置claude_code.debug: true或设置OPENVIKING_DEBUG=1，hook 日志写入~/.openviking/logs/cc-hooks.log。

• auto-recall默认记录关键阶段加一份紧凑的ranking_summary；
• 仅在排查逐候选打分时开启claude_code.logRankingDetails: true（输出冗长）；
• 深度诊断建议对样例输入运行独立脚本scripts/debug-recall.mjs与scripts/debug-capture.mjs，而不是长期开启 hook 日志。

自带 Doctor

先运行插件自带的诊断脚本ov-memory-doctor，它会检查安装（marketplace、启用状态、hooks、MCP 接线）、解析后的配置（哪个文件胜出、API key 掩码显示）、连接（可达性、认证、/mcp）以及最近的 hook 活动，并为每个发现打印修复建议：

node "$(jq -r '.plugins["openviking-memory@openviking"][0].installPath' ~/.claude/plugins/installed_plugins.json)/scripts/ov-memory-doctor.mjs"

也可以直接让 Claude 检查插件：ov-memory-doctorskill 会运行同一脚本并解读报告。

常见问题速查

综合关联文档与集成指南的排障表：

与 Claude Code 内置记忆的对比

Claude Code 自带MEMORY.md文件系统。本插件与其是互补关系：

架构总览

┌────────────────────────────────────────────────────────────┐ │ Claude Code │ │ │ │ SessionStart UserPromptSubmit Stop PreCompact │ │ SessionEnd SubagentStart SubagentStop │ └────┬───────────────┬───────────────┬───────────┬───────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ │ hook scripts (.mjs) │ │ │ ┌──────────────┐ │ │ read transcript + │───┼───────────┼────►│ │ │ │ call OV HTTP API │ │ │ │ OpenViking │ │ └───────────────────────┘ │ │ │ Server │ │ │ │ │ (Python) │ │ ┌────────────▼───────────▼───►│ │ │ │ MCP tools (stdio proxy → /mcp) │ │ │ find/search/recall/remember/… │ │ └─────────────────►│ │ │ OV session └─────────────────────────────► │ context inject └──────────────┘

关键架构事实（插件 README 的 Architecture 一节）：

• 无 TypeScript 构建步骤、无运行时 npm 引导。hooks 是纯.mjs文件，通过 HTTP 与 OpenViking 通信；MCP 使用servers/mcp-proxy.mjs作为零依赖 stdio 桥接到服务端原生/mcp端点；
• 持久 OV 会话：首次联系时创建并复用整个 Claude Code 会话；OV 会话 ID 为cc-<cc_session_id>（CC session_id 原样、不做哈希），因此 resume / compact / 多 hook 事件都指向同一会话；
• 客户端触发归档 + 记忆提取：Stophook 在服务端上报的挂起 token 越过commitTokenThreshold（默认 20000）时提交，PreCompact/SessionEnd/SubagentStop无条件提交。

插件目录结构（examples/claude-code-memory-plugin）：

claude-code-memory-plugin/ ├── hooks/hooks.json # 9 个 hook 注册 ├── commands/ov.md # /ov 状态命令 ├── skills/ # openviking-memory / ov-experience-memory / ov-memory-doctor ├── servers/mcp-proxy.mjs # stdio -> OpenViking /mcp 桥 ├── scripts/ │ ├── config.mjs # 共享配置加载器（env > ovcli.conf > ov.conf） │ ├── auto-recall.mjs # UserPromptSubmit │ ├── auto-capture.mjs # Stop │ ├── session-start.mjs / session-end.mjs │ ├── pre-compact.mjs │ ├── subagent-start.mjs / subagent-stop.mjs │ ├── debug-recall.mjs / debug-capture.mjs # 独立诊断 │ ├── ov-status.mjs / ov-memory-doctor.mjs │ └── lib/ # ov-session.mjs / async-writer.mjs 等 ├── .mcp.json # MCP 服务配置（本地 stdio 代理） └── package.json # 仅 type:module 标记，无运行时依赖

MCP 侧可用的工具来自服务端原生/mcp端点（检索、记忆、资源、watch、文件系统、代码导航等），规范工具清单与参数见 MCP 集成指南 与 Capability Reference。

继续阅读

• Claude Code Memory Plugin 集成文档——完整的环境变量表、hook 细节与架构图
• 插件 README——配置优先级、Legacy 模式、排障细节
• StatusLine 指南——分段术语表与个性化配方
• Agent 集成总览——低延迟召回等进阶主题
• Client Configuration——workspace 配置文件完整 schema
• MCP Clients——MCP 工具参数与其他客户端

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking