企业官网建设流程全解析

DeerFlow 接入 OpenViking：通过 MCP Server 打通 Agent 记忆与知识检索

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

OpenViking 为 AI Agent 提供统一的长效记忆与知识库能力，而 DeerFlow 这类深度智能体框架则需要在任务执行过程中随时检索和读取这些记忆。本文以 docs/images/agents/zh/deerflow-mcp.md 为主线，完整讲解如何在 DeerFlow 中通过 MCP（Model Context Protocol）接入 OpenViking：从.env鉴权配置、extensions_config.json的 MCP Server 声明，到重启验证与故障排查，并结合仓库源码说明/mcp端点背后提供的工具能力与鉴权机制。读完本文，你将掌握一条零插件、纯标准协议的 DeerFlow ↔ OpenViking 接入路径，并理解 MCP 工具与 MemoryManager 自动召回两种接入方式的本质区别。

DeerFlow 为什么需要 MCP 接入 OpenViking

DeerFlow 是一个由多智能体组成的深度推理框架，任务执行过程中需要的事实往往散落在长期记忆与已入库的知识资源中。OpenViking 的核心价值正是打通这一层知识检索能力：把 Agent 的记忆（会话、消息）和知识（资源、文档）统一管理起来，并通过检索接口按需取用。

在 DeerFlow 中接入 OpenViking 有两条主线路径：

• MCP Server 接入（本文主题）：DeerFlow 通过标准 MCP 协议把 OpenViking 的工具加载为自身可调用的工具集，Agent 在推理时按需调用find、search、read、remember等工具主动搜索、读取和使用 OpenViking 中的记忆与知识；
• MemoryManager 接入（见 deerflow-memory-manager.md）：把 OpenViking 配置为 DeerFlow 的长期记忆后端（manager_class: openviking），实现写入与模型调用前的自动记忆召回。

两者定位不同：MCP 工具由模型按需调用，是"主动搜索"；MemoryManager 是"自动召回"，会在每次模型调用前自动注入记忆。本文聚焦前者。

步骤 1：配置 OpenViking 鉴权信息

在 DeerFlow 项目根目录下编辑.env文件，把 API Key 填进去：

OPENVIKING_API_KEY=<your-openviking-api-key>

如果 OpenViking 服务不在默认地址，还需要一并配置 Base URL（下文 MCP 配置中的{{OPENVIKING_BASE_URL}}即对应此变量）：

OPENVIKING_BASE_URL=http://localhost:1933

鉴权前提：OpenViking 的 MCP 端点与 REST API 复用同一套 API-Key 认证系统（详见 MCP 集成指南）。服务端在ov.conf中配置了root_api_key时，客户端必须携带有效 Key 才能访问；本地开发模式（未配置root_api_key）下无需认证。鉴权模式是自动检测的：配置了root_api_key则进入api_key模式，否则进入dev模式，见 config.py 的get_effective_auth_mode实现。

步骤 2：创建 MCP 配置文件

DeerFlow 通过项目根目录下的extensions_config.json声明可加载的 MCP Server。复制示例文件：

cp extensions_config.example.json extensions_config.json

这一步只是为了得到一个可编辑的起点；实际生效的是extensions_config.json中的mcpServers段。

步骤 3：配置 OpenViking MCP Server

打开项目根目录下的extensions_config.json，在mcpServers中添加 OpenViking 配置：

{ "mcpServers": { "openviking": { "enabled": true, "type": "http", "url": "{{OPENVIKING_BASE_URL}}/mcp", "headers": { "X-API-Key": "$OPENVIKING_API_KEY" } } } }

各字段说明：

X-API-Key头部是 OpenViking 服务端官方支持的两种鉴权 Header 之一，由服务端在请求上下文中显式解析，见 auth/init.py 中x_api_key_ctx = Header(None, alias="X-API-Key")的声明；另一种是标准的Authorization: Bearer。二者与 REST API 完全一致，详见 MCP 集成指南 的鉴权章节。

步骤 4：重启 DeerFlow

保存.env和extensions_config.json后，重新启动 DeerFlow：

make dev

MCP 配置只在 DeerFlow Gateway 启动时加载，因此任何配置变更都必须重启才生效。若不方便重启，可尝试调用 DeerFlow 的/api/mcp/cache/reset接口刷新 MCP 配置缓存（见下方故障排查表）。

OpenViking MCP 端点为 DeerFlow 提供哪些工具

接入后，DeerFlow Agent 获得的并非空壳连接，而是 OpenViking 服务端通过 mcp_endpoint.py 中@mcp.tool()注册的完整工具集（该文件顶部注释明确指出这些注册就是权威工具清单）。从源码结构看，至少包括以下几类：

• 检索类：find与search，支持query、target_uri、limit等参数，并可选择读取命中内容（read_content），是 DeerFlow 打通知识检索的核心入口；
• 文件系统类：read、ls、tree、grep、glob，用于浏览和读取 OpenViking 资源库中的文档内容；
• 记忆类：remember、write、edit，支持把消息写入记忆与编辑既有内容；
• 资源管理类：add_resource用于把新资源摄入 OpenViking；list_watches、cancel_watch管理 watch 订阅；forget删除资源；
• 健康检查：health，可用于验证 DeerFlow ↔ OpenViking 连通性。

这意味着 DeerFlow Agent 在任务中既能"搜"（find/search），也能"读"（read/ls/tree），还能"写"（remember/write），从而把 OpenViking 作为任务执行期的实时知识后端。

故障排查

其中最后一条最容易误解：MCP 工具是"按需调用"的，模型不主动用就不会触发检索。如果目标是"每次对话前自动注入记忆"，应当选择 MemoryManager 接入方案（memory.manager_class: openviking、mode: middleware），它会通过injection_enabled在模型调用前自动执行记忆召回并注入上下文。

从 MCP 到自动召回：两条接入路径如何选

一句话总结两种方式的适用场景：

• 需要 Agent 主动探索知识库（如查询资源、读取文档、按需写记忆）→ 用本文的 MCP Server 接入，配合提示词引导模型调用工具；
• 需要无感、自动的长期记忆（对话自动落库、模型调用前自动注入召回结果）→ 用 MemoryManager 接入，将manager_class切换为openviking。

两者可以理解为互补关系：MCP 解决"会搜"，MemoryManager 解决"记得住、用得上"。DeerFlow 项目中甚至可以两者并用——以 MemoryManager 保证记忆的自动写入与召回，以 MCP 工具补足任务执行中对具体文档的深度检索。更多 Agent 运行时接入方式可参考 Agent 集成概览 与 MCP 客户端。

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