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 可以看到它挂载的完整生命周期钩子面钩子职责config向 OpenCode 配置注入 OpenViking MCP servermcp.openvikingevent处理会话创建/删除/压缩/空闲等事件触发会话刷新tool.execute.beforevikingUriGuard拦截对viking://URI 的本地文件系统读取experimental.chat.system.transform注入已索引仓库viking://resources/的系统提示词chat.message注入会话上下文与自动召回的隐藏合成上下文experimental.session.compacting会话压缩时提交会话dispose插件卸载时flushAll({ commit: true })兜底提交所有会话二、前置条件在安装插件之前需要准备OpenCode本地或 TUI 环境OpenViking HTTP ServerNode.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.4main指向index.mjs。可通过如下命令确认包在 npm 上的可用性npm view openviking/opencode-plugin versionnpm 包安装时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.jsexport { 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环境变量OPENVIKING_PLUGIN_CONFIG指向的路径当前项目目录下的.opencode/openviking-config.json~/.config/opencode/openviking-config.json插件根目录下的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的取值钳制逻辑核心配置项如下配置项默认值取值范围钳制说明endpointhttp://127.0.0.1:1933—OpenViking HTTP 服务地址尾部多余/会被去除timeoutMs300001000 ~ 300000HTTP 请求超时毫秒enabledtrue—插件总开关置false时插件直接跳过初始化mcp.enabledtrue—是否注册内置 MCP serverruntime.dataDir~/.config/opencode/openviking—运行时文件目录支持~展开repoContext.enabledtrue—是否向系统提示词注入已索引仓库repoContext.cacheTtlMs600001000 ~ 3600000仓库上下文缓存 TTLautoRecall.enabledtrue—自动召回开关autoRecall.limit101 ~ 50召回配额见下方说明autoRecall.scoreThreshold0.350 ~ 1召回相似度阈值autoRecall.maxContentChars500100 ~ 5000单条召回内容最大字符数autoRecall.preferAbstracttrue—优先使用摘要而非全文autoRecall.tokenBudget2000200 ~ 50000召回上下文 token 预算autoRecall.minQueryLength31 ~ 64触发召回的最小查询长度autoCapturetrue—是否自动捕获会话消息captureModesemanticsemantic/keyword捕获内容的分块方式captureMaxLength24000200 ~ 100000单条捕获文本最大长度captureAssistantTurnstrue—是否捕获助手轮次captureToolMaxChars1000000200 ~ 1000000工具调用参数捕获上限commitTokenThreshold20000≥ 1000待提交 token 达到该值触发会话提交commitKeepRecentCount10≥ 0提交时保留的最近消息条数profileTokenBudget10000≥ 500用户画像注入的 token 预算resumeContextBudget32000≥ 1024会话恢复上下文的 token 预算recallPeerScopeallall/actor召回范围模式recallQueryExpansionautoauto/off服务端查询扩展开关扩展会先消耗一次模型调用workspacePeertrue—是否从 git 身份派生 peernoAutoInjectfalse—关闭会话上下文自动注入bypassSession/bypassSessionPatternsfalse/[]—按会话或模式跳过捕获5.4autoRecall.limit的配额语义需要注意autoRecall.limit是遗留的配额缩放输入不是最终结果上限。由于每个编码分类会保留一个检索槽位显式配置 15 时实际生效的总配额为 6。如果需要对特定分类设置精确上限应直接使用上下文Context的quotas机制。5.5 凭证解析与身份头插件不鼓励把 API key 直接写进配置文件推荐通过环境变量提供export OPENVIKING_API_KEYyour-api-key-hereAPI 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/searchmodecontext在旧版本部署上回退到已废弃的/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 的injectOpenVikingMcpConfigenabled为false或已存在被禁用的mcp.openviking条目时直接跳过注入。六、验证安装修改插件或 OpenViking 配置后需要重启 OpenCode。在新 OpenCode 会话中让 Agent 浏览 OpenViking 记忆或搜索一个已知的已索引资源。插件应暴露 OpenViking MCP server工具在 OpenCode 中以openviking_前缀命名空间呈现openviking_search、openviking_findopenviking_read、openviking_list、openviking_tree、openviking_grep、openviking_globopenviking_remember、openviking_write、openviking_edit、openviking_add_resourceopenviking_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跨记忆、资源、技能的深度语义检索使用modecontext获得均衡、可直接注入的上下文openviking_find快速语义检索openviking_remember存储重要事实或决策供记忆抽取使用openviking_read读取一个或多个viking://文件openviking_list列出viking://目录openviking_tree展示viking://目录树openviking_grep精确文本或正则搜索openviking_globglob 文件匹配openviking_write创建、覆盖或追加写入viking://文件openviking_edit对viking://文件做精确字符串替换openviking_add_resource添加 URL、本地文件、sitemap 或 feedopenviking_forget在用户明确确认后删除viking://URIopenviking_list_watches/openviking_cancel_watch查看或取消资源 watchopenviking_health检查 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.mjsFILESYSTEM_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.mjsOpenCode 将其作为本地 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(pathhttps://example.com/spec.md, toviking://resources/spec) openviking_add_resource(path./docs/notes.md, toviking://resources/notes.md) openviking_add_resource(pathfile:///home/alice/project/notes.md, descriptionproject notes)注意本地目录的自动 zip 上传暂不支持传入目录会返回明确错误。九、运行时文件插件默认将运行时文件写入~/.config/opencode/openviking/可能出现的文件包括openviking-memory.log插件运行日志openviking-session-state.json会话映射与待发送消息的状态持久化v2 格式防抖 300ms 写入写盘采用临时文件 rename 的原子方式并通过 promise 链串行化保存见 lib/memory-session.mjs。可通过配置中的runtime.dataDir修改此目录。这些是本地运行时文件不应提交到代码仓库。十、常见问题排查问题排查方向插件未加载包安装确认~/.config/opencode/opencode.json包含openviking/opencode-plugin源码安装确认~/.config/opencode/plugins/openviking.js存在MCP 工具连到了错误的服务器检查~/.openviking/ovcli.conf或设置OPENVIKING_*环境变量 /OPENVIKING_PLUGIN_CONFIG指向目标配置路径收到 OpenViking 的 401 / 403核对OPENVIKING_API_KEY信任模式部署还需核对OPENVIKING_ACCOUNT与OPENVIKING_USER召回为空确认 OpenViking 已索引记忆/资源且autoRecall.enabled为true本地openviking_add_resource失败传入文件路径而非目录本地目录暂不支持自动上传十一、从源码看插件运行时行为为了让文章不流于照配置这里补充几个从源码可以确认的运行时细节会话映射与提交每个 OpenCode 会话都会映射为一个 OpenViking 会话lib/memory-session.mjs 中的deriveHarnessSessionId(oc-, ...)子代理会话以subagent-id派生。会话提交调用POST /api/v1/sessions/id/commit携带keep_recent_count对应commitKeepRecentCount当服务不可达或提交失败可重试时消息与提交会进入 pending 队列待init或session.created时健康检查通过后重放。自动召回流程lib/memory-recall.mjs在chat.message钩子中提取当前用户文本短于minQueryLength直接跳过先做一次/health检查再构建召回块最后以synthetic: true的文本 part前置到输出消息使模型看到隐藏的 OpenViking 上下文。服务端会基于映射的 OV 会话开启查询扩展与跨轮次去重账本。会话上下文注入lib/session-inject.mjs每个会话首次消息前注入openviking-context sourcesession-start块包含用户画像profileTokenBudget预算与历史会话归档概览resumeContextBudget预算来自/api/v1/sessions/id/context。noAutoInject可关闭injectedSessions集合保证每个会话只注入一次。仓库上下文注入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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking OpenCode 插件安装与配置实战：为 OpenCode 接入统一记忆、资源检索与生命周期记忆管理
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 可以看到它挂载的完整生命周期钩子面钩子职责config向 OpenCode 配置注入 OpenViking MCP servermcp.openvikingevent处理会话创建/删除/压缩/空闲等事件触发会话刷新tool.execute.beforevikingUriGuard拦截对viking://URI 的本地文件系统读取experimental.chat.system.transform注入已索引仓库viking://resources/的系统提示词chat.message注入会话上下文与自动召回的隐藏合成上下文experimental.session.compacting会话压缩时提交会话dispose插件卸载时flushAll({ commit: true })兜底提交所有会话二、前置条件在安装插件之前需要准备OpenCode本地或 TUI 环境OpenViking HTTP ServerNode.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.4main指向index.mjs。可通过如下命令确认包在 npm 上的可用性npm view openviking/opencode-plugin versionnpm 包安装时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.jsexport { 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环境变量OPENVIKING_PLUGIN_CONFIG指向的路径当前项目目录下的.opencode/openviking-config.json~/.config/opencode/openviking-config.json插件根目录下的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的取值钳制逻辑核心配置项如下配置项默认值取值范围钳制说明endpointhttp://127.0.0.1:1933—OpenViking HTTP 服务地址尾部多余/会被去除timeoutMs300001000 ~ 300000HTTP 请求超时毫秒enabledtrue—插件总开关置false时插件直接跳过初始化mcp.enabledtrue—是否注册内置 MCP serverruntime.dataDir~/.config/opencode/openviking—运行时文件目录支持~展开repoContext.enabledtrue—是否向系统提示词注入已索引仓库repoContext.cacheTtlMs600001000 ~ 3600000仓库上下文缓存 TTLautoRecall.enabledtrue—自动召回开关autoRecall.limit101 ~ 50召回配额见下方说明autoRecall.scoreThreshold0.350 ~ 1召回相似度阈值autoRecall.maxContentChars500100 ~ 5000单条召回内容最大字符数autoRecall.preferAbstracttrue—优先使用摘要而非全文autoRecall.tokenBudget2000200 ~ 50000召回上下文 token 预算autoRecall.minQueryLength31 ~ 64触发召回的最小查询长度autoCapturetrue—是否自动捕获会话消息captureModesemanticsemantic/keyword捕获内容的分块方式captureMaxLength24000200 ~ 100000单条捕获文本最大长度captureAssistantTurnstrue—是否捕获助手轮次captureToolMaxChars1000000200 ~ 1000000工具调用参数捕获上限commitTokenThreshold20000≥ 1000待提交 token 达到该值触发会话提交commitKeepRecentCount10≥ 0提交时保留的最近消息条数profileTokenBudget10000≥ 500用户画像注入的 token 预算resumeContextBudget32000≥ 1024会话恢复上下文的 token 预算recallPeerScopeallall/actor召回范围模式recallQueryExpansionautoauto/off服务端查询扩展开关扩展会先消耗一次模型调用workspacePeertrue—是否从 git 身份派生 peernoAutoInjectfalse—关闭会话上下文自动注入bypassSession/bypassSessionPatternsfalse/[]—按会话或模式跳过捕获5.4autoRecall.limit的配额语义需要注意autoRecall.limit是遗留的配额缩放输入不是最终结果上限。由于每个编码分类会保留一个检索槽位显式配置 15 时实际生效的总配额为 6。如果需要对特定分类设置精确上限应直接使用上下文Context的quotas机制。5.5 凭证解析与身份头插件不鼓励把 API key 直接写进配置文件推荐通过环境变量提供export OPENVIKING_API_KEYyour-api-key-hereAPI 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/searchmodecontext在旧版本部署上回退到已废弃的/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 的injectOpenVikingMcpConfigenabled为false或已存在被禁用的mcp.openviking条目时直接跳过注入。六、验证安装修改插件或 OpenViking 配置后需要重启 OpenCode。在新 OpenCode 会话中让 Agent 浏览 OpenViking 记忆或搜索一个已知的已索引资源。插件应暴露 OpenViking MCP server工具在 OpenCode 中以openviking_前缀命名空间呈现openviking_search、openviking_findopenviking_read、openviking_list、openviking_tree、openviking_grep、openviking_globopenviking_remember、openviking_write、openviking_edit、openviking_add_resourceopenviking_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跨记忆、资源、技能的深度语义检索使用modecontext获得均衡、可直接注入的上下文openviking_find快速语义检索openviking_remember存储重要事实或决策供记忆抽取使用openviking_read读取一个或多个viking://文件openviking_list列出viking://目录openviking_tree展示viking://目录树openviking_grep精确文本或正则搜索openviking_globglob 文件匹配openviking_write创建、覆盖或追加写入viking://文件openviking_edit对viking://文件做精确字符串替换openviking_add_resource添加 URL、本地文件、sitemap 或 feedopenviking_forget在用户明确确认后删除viking://URIopenviking_list_watches/openviking_cancel_watch查看或取消资源 watchopenviking_health检查 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.mjsFILESYSTEM_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.mjsOpenCode 将其作为本地 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(pathhttps://example.com/spec.md, toviking://resources/spec) openviking_add_resource(path./docs/notes.md, toviking://resources/notes.md) openviking_add_resource(pathfile:///home/alice/project/notes.md, descriptionproject notes)注意本地目录的自动 zip 上传暂不支持传入目录会返回明确错误。九、运行时文件插件默认将运行时文件写入~/.config/opencode/openviking/可能出现的文件包括openviking-memory.log插件运行日志openviking-session-state.json会话映射与待发送消息的状态持久化v2 格式防抖 300ms 写入写盘采用临时文件 rename 的原子方式并通过 promise 链串行化保存见 lib/memory-session.mjs。可通过配置中的runtime.dataDir修改此目录。这些是本地运行时文件不应提交到代码仓库。十、常见问题排查问题排查方向插件未加载包安装确认~/.config/opencode/opencode.json包含openviking/opencode-plugin源码安装确认~/.config/opencode/plugins/openviking.js存在MCP 工具连到了错误的服务器检查~/.openviking/ovcli.conf或设置OPENVIKING_*环境变量 /OPENVIKING_PLUGIN_CONFIG指向目标配置路径收到 OpenViking 的 401 / 403核对OPENVIKING_API_KEY信任模式部署还需核对OPENVIKING_ACCOUNT与OPENVIKING_USER召回为空确认 OpenViking 已索引记忆/资源且autoRecall.enabled为true本地openviking_add_resource失败传入文件路径而非目录本地目录暂不支持自动上传十一、从源码看插件运行时行为为了让文章不流于照配置这里补充几个从源码可以确认的运行时细节会话映射与提交每个 OpenCode 会话都会映射为一个 OpenViking 会话lib/memory-session.mjs 中的deriveHarnessSessionId(oc-, ...)子代理会话以subagent-id派生。会话提交调用POST /api/v1/sessions/id/commit携带keep_recent_count对应commitKeepRecentCount当服务不可达或提交失败可重试时消息与提交会进入 pending 队列待init或session.created时健康检查通过后重放。自动召回流程lib/memory-recall.mjs在chat.message钩子中提取当前用户文本短于minQueryLength直接跳过先做一次/health检查再构建召回块最后以synthetic: true的文本 part前置到输出消息使模型看到隐藏的 OpenViking 上下文。服务端会基于映射的 OV 会话开启查询扩展与跨轮次去重账本。会话上下文注入lib/session-inject.mjs每个会话首次消息前注入openviking-context sourcesession-start块包含用户画像profileTokenBudget预算与历史会话归档概览resumeContextBudget预算来自/api/v1/sessions/id/context。noAutoInject可关闭injectedSessions集合保证每个会话只注入一次。仓库上下文注入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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考