企业官网建设流程全解析

OpenViking OpenCode 插件安装与配置实战：为 OpenCode 接入统一记忆、资源检索与生命周期记忆管理

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

导读

本文以 OpenViking 仓库中唯一维护的 OpenCode 插件 examples/opencode-plugin 为主线，完整讲解如何在 OpenCode 中安装并配置该插件，使其通过标准 stdio MCP 代理暴露 OpenViking 的记忆（Memory）、资源（Resources）与代码上下文（Code Context）工具，同时借助生命周期钩子实现会话同步、自动捕获、生命周期提交与自动召回。读完本文，你将掌握两种安装方式（发布包与源码安装）、完整配置项语义、环境变量与凭证解析机制、MCP 工具清单，以及常见故障的排查路径。

一、插件定位：一个插件，两层能力

OpenViking 的 OpenCode 插件是一个"统一插件"，它把两类能力合并到了同一个包中：

• OpenViking MCP 工具：用于记忆、资源和代码上下文的检索与写入；
• 生命周期行为：长期记忆、会话同步、生命周期提交与自动召回。

它与仓库中 Claude Code、Codex 记忆插件共享同一个 stdio MCP 代理（servers/mcp-proxy.mjs），模型工具由该代理统一提供。

与部分其他 Agent 插件不同，它不安装skills/openviking/SKILL.md，也不要求 Agent 使用ov命令——工具面完全来自 OpenViking 的 MCP 端点，而不是本地技能文件。这一点从 README.md 的目录结构可以确认：examples/opencode-plugin/下刻意没有skills/目录。

从插件入口 index.mjs 可以看到它挂载的完整生命周期钩子面：

二、前置条件

在安装插件之前，需要准备：

• OpenCode（本地或 TUI 环境）；
• OpenViking HTTP Server；
• Node.js 18+；
• 如果服务器开启了鉴权，还需要一个有效的 OpenViking API key。

首先启动 OpenViking 服务：

openviking-server --config ~/.openviking/ov.conf

然后检查服务是否就绪：

curl http://localhost:1933/health

默认服务端点在http://127.0.0.1:1933（见 lib/config.mjs 中的DEFAULT_CONFIG.endpoint）。另外，该插件依赖 OpenViking 服务器的viking://~home-alias 支持——自动召回通过viking://~/memories与viking://~/skills定位调用方自身的上下文空间。

三、安装方法一：发布包（推荐普通用户）

普通用户建议通过 OpenCode 的包插件机制启用，即把@openviking/opencode-plugin加入 OpenCode 配置：

{ "plugin": ["@openviking/opencode-plugin"] }

对应 package.json 中的包名为@openviking/opencode-plugin（当前仓库版本为0.2.4，main指向index.mjs）。可通过如下命令确认包在 npm 上的可用性：

npm view @openviking/opencode-plugin version

npm 包安装时，OpenCode 通过package.json的main字段直接加载index.mjs，无需额外包装文件。

四、安装方法二：源码安装（开发 / 调试 / PR 测试）

当你需要开发、调试或测试 PR 时，使用源码安装。OpenCode 推荐的插件目录是：

~/.config/opencode/plugins

在仓库根目录执行以下命令：

mkdir -p ~/.config/opencode/plugins/openviking cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/ cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/

安装完成后的目录结构应为：

~/.config/opencode/plugins/ ├── openviking.js └── openviking/ ├── index.mjs ├── package.json ├── lib/ └── servers/

顶层的openviking.js是一个转发包装器，它把 OpenCode 本地插件扫描器能发现的一级.js入口转发到真正的插件目录（源码见 wrappers/openviking.js）：

export { OpenVikingPlugin, default } from "./openviking/index.mjs"

这里有几个要点：

• 包装器仅用于源码安装的上述目录布局；npm 包安装直接通过package.json加载index.mjs；
• 源码安装必须使用.js包装器，因为 OpenCode 的本地插件扫描器发现的是 JavaScript/TypeScript 插件文件；
• 如果你通过 npm 包安装，也可以把examples/opencode-plugin当作一个普通的 OpenCode 插件包使用。

五、配置详解

5.1 配置文件位置

创建用户级配置文件：

~/.config/opencode/openviking-config.json

配置的搜索路径按优先级从高到低依次为（见 lib/config.mjs 的getConfigPaths）：

1. 环境变量OPENVIKING_PLUGIN_CONFIG指向的路径；
2. 当前项目目录下的.opencode/openviking-config.json；
3. ~/.config/opencode/openviking-config.json；
4. 插件根目录下的openviking-config.json。

5.2 完整示例配置

{ "enabled": true, "mcp": { "enabled": true }, "timeoutMs": 30000, "repoContext": { "enabled": true, "cacheTtlMs": 60000 }, "autoRecall": { "enabled": true, "limit": 6, "scoreThreshold": 0.35, "maxContentChars": 500, "preferAbstract": true, "tokenBudget": 2000, "minQueryLength": 3 }, "commitTokenThreshold": 20000, "commitKeepRecentCount": 10, "profileTokenBudget": 10000, "resumeContextBudget": 32000 }

5.3 关键配置项语义与默认值

结合 lib/config.mjs 中的DEFAULT_CONFIG与normalizeConfig的取值钳制逻辑，核心配置项如下：

5.4autoRecall.limit的配额语义

需要注意：autoRecall.limit是遗留的配额缩放输入，不是最终结果上限。由于每个编码分类会保留一个检索槽位，显式配置 1～5 时，实际生效的总配额为 6。如果需要对特定分类设置精确上限，应直接使用上下文（Context）的quotas机制。

5.5 凭证解析与身份头

插件不鼓励把 API key 直接写进配置文件，推荐通过环境变量提供：

export OPENVIKING_API_KEY="your-api-key-here"

API key 的解析来源依次是环境变量与~/.openviking/ovcli.conf，解析结果由钩子与 MCP 代理共同以Authorization: Bearer ...头发送。

• account与user是信任模式身份头，分别以X-OpenViking-Account和X-OpenViking-User发送；使用 user/admin API key 时请留空；
• peerId以X-OpenViking-Actor-Peer头随数据面记忆/资源请求发送，捕获的会话消息会将其写入 body 的peer_id字段；
• 自动召回默认走服务端上下文接口（POST /api/v1/search/search，mode="context"），在旧版本部署上回退到已废弃的/api/v1/search/recall（见 README.md）。

环境变量优先级高于配置文件：OPENVIKING_API_KEY、OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_PEER_ID均覆盖openviking-config.json中的同名配置。配置文件中的peerId在共享凭证（ovcli.conf 或环境变量）未携带自己的 peer 时仍然生效，从而保证认证环境持续写入 peer 作用域数据，而不是落入共享用户树。

高级场景可用OPENVIKING_PLUGIN_CONFIG指向另一个配置文件路径。lib/config.mjs中还支持大量OPENVIKING_*环境变量（如OPENVIKING_AUTO_RECALL、OPENVIKING_RECALL_LIMIT、OPENVIKING_SCORE_THRESHOLD、OPENVIKING_RECALL_TOKEN_BUDGET、OPENVIKING_RECALL_PEER_SCOPE、OPENVIKING_COMMIT_TOKEN_THRESHOLD、OPENVIKING_PROFILE_TOKEN_BUDGET、OPENVIKING_RESUME_CONTEXT_BUDGET、OPENVIKING_BYPASS_SESSION_PATTERNS等），可以精细覆盖几乎每一个行为配置。

5.6 Hook-only 模式

如果另一个 MCP server 已经暴露了 OpenViking，可以关闭本插件内置的 MCP 注册，同时保留生命周期钩子：

{ "mcp": { "enabled": false } }

此时仓库上下文、自动召回、消息捕获与生命周期提交仍然启用，但不会添加或覆盖 OpenCode 的mcp.openviking条目。对应的注册逻辑在 lib/mcp-config.mjs 的injectOpenVikingMcpConfig：enabled为false或已存在被禁用的mcp.openviking条目时直接跳过注入。

六、验证安装

修改插件或 OpenViking 配置后，需要重启 OpenCode。

在新 OpenCode 会话中，让 Agent 浏览 OpenViking 记忆或搜索一个已知的已索引资源。插件应暴露 OpenViking MCP server，工具在 OpenCode 中以openviking_前缀命名空间呈现：

• openviking_search、openviking_find
• openviking_read、openviking_list、openviking_tree、openviking_grep、openviking_glob
• openviking_remember、openviking_write、openviking_edit、openviking_add_resource
• openviking_list_watches、openviking_cancel_watch、openviking_forget、openviking_health

如果行为异常，检查运行时文件：

ls ~/.config/opencode/openviking/ tail -n 100 ~/.config/opencode/openviking/openviking-memory.log

对本地服务器，再次确认服务可达：

curl http://localhost:1933/health

七、可用 MCP 工具与使用指引

插件通过 OpenCode 配置注册 OpenViking 的 stdio MCP 代理，真正的工具清单以服务端tools/list响应为准——插件不维护独立的原生工具列表（见 README.md）。当前 OpenViking 服务器暴露的工具包括：

使用建议：

• 概念性问题用openviking_search；
• 精确符号、函数名、类名或错误字符串用openviking_grep；
• 枚举文件用openviking_glob；
• 读取内容用openviking_read；
• 探索目录结构用openviking_list；
• 删除任何内容前先取得用户明确确认，再调用openviking_forget。

viking:// URI 保护：如果 Agent 试图用 OpenCode 本地的read、glob、grep工具去读viking://URI，插件会拦截该调用并引导其使用 MCP 工具。实现位于 lib/viking-uri-guard.mjs：FILESYSTEM_TOOL_HINTS将read映射到openviking_read、glob映射到openviking_glob、grep映射到openviking_search，并在拦截时抛出带示例的引导错误。MCP server 在 OpenCode 中显示名为openviking（见 lib/mcp-config.mjs 的OPENCODE_MCP_NAME），注册命令为node servers/mcp-proxy.mjs，类型为本地 stdio。

MCP 代理的实现原理：mcp-proxy.mjs是一个stdio → streamable-HTTP代理（servers/mcp-proxy.mjs），OpenCode 将其作为本地 MCP server 启动；代理复用与生命周期钩子相同的 OpenViking 凭证源，将 JSON-RPC 请求转发到服务器的/mcp端点，同时保持 stdout 协议纯净。

八、用openviking_add_resource添加本地文件

openviking_add_resource支持三种输入类型：

• 远程http(s)URL：直接调用/api/v1/resources；
• 本地文件路径：先调用/api/v1/resources/temp_upload获取temp_file_id，再凭它添加资源；
• file://URL：按本地文件处理。

相对路径会基于当前 OpenCode 项目目录解析。示例：

openviking_add_resource(path="https://example.com/spec.md", to="viking://resources/spec") openviking_add_resource(path="./docs/notes.md", to="viking://resources/notes.md") openviking_add_resource(path="file:///home/alice/project/notes.md", description="project notes")

注意：本地目录的自动 zip 上传暂不支持，传入目录会返回明确错误。

九、运行时文件

插件默认将运行时文件写入：

~/.config/opencode/openviking/

可能出现的文件包括：

• openviking-memory.log：插件运行日志；
• openviking-session-state.json：会话映射与待发送消息的状态持久化（v2 格式，防抖 300ms 写入，写盘采用临时文件 + rename 的原子方式，并通过 promise 链串行化保存，见 lib/memory-session.mjs）。

可通过配置中的runtime.dataDir修改此目录。这些是本地运行时文件，不应提交到代码仓库。

十、常见问题排查

十一、从源码看插件运行时行为

为了让文章不流于"照配置"，这里补充几个从源码可以确认的运行时细节：

1. 会话映射与提交：每个 OpenCode 会话都会映射为一个 OpenViking 会话（lib/memory-session.mjs 中的deriveHarnessSessionId("oc-", ...)），子代理会话以subagent-<id>派生。会话提交调用POST /api/v1/sessions/<id>/commit，携带keep_recent_count（对应commitKeepRecentCount）；当服务不可达或提交失败可重试时，消息与提交会进入 pending 队列，待init或session.created时健康检查通过后重放。

2. 自动召回流程（lib/memory-recall.mjs）：在chat.message钩子中提取当前用户文本，短于minQueryLength直接跳过；先做一次/health检查，再构建召回块，最后以synthetic: true的文本 part前置到输出消息，使模型看到隐藏的 OpenViking 上下文。服务端会基于映射的 OV 会话开启查询扩展与跨轮次去重账本。

3. 会话上下文注入（lib/session-inject.mjs）：每个会话首次消息前注入<openviking-context source="session-start">块，包含用户画像（profileTokenBudget预算）与历史会话归档概览（resumeContextBudget预算，来自/api/v1/sessions/<id>/context）。noAutoInject可关闭；injectedSessions集合保证每个会话只注入一次。

4. 仓库上下文注入：experimental.chat.system.transform钩子将已索引的viking://resources/仓库系统提示词推入系统消息；session.created与插件初始化时都会refreshRepos({ force: true })刷新仓库列表（index.mjs）。

这些实现细节均可在 examples/opencode-plugin 目录下找到对应源码与 tests 测试（如config.test.mjs、memory-recall.test.mjs、memory-session.test.mjs、viking-uri-guard.test.mjs），便于进一步深入阅读与二次开发。

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