Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: refine DeerFlow agent integration guide (#3968)

ManAsWind2e9b6610abcf
diff --git a/docs/en/agent-integrations/05-hermes.md b/docs/en/agent-integrations/05-hermes.md
index 65d967b81..3f696f934 100644
--- a/docs/en/agent-integrations/05-hermes.md
+++ b/docs/en/agent-integrations/05-hermes.md
@@ -35,7 +35,7 @@ Configuration is saved to Hermes's `config.yaml` and `.env` files.
hermes memory status
```
-Once configured, Hermes automatically uses OpenViking for long-term memory — `viking_remember`, `viking_recall`, and other memory tools become available to the agent.
+Once configured, Hermes uses the OpenViking memory provider to inject context, prefetch relevant memories, and sync and extract memories after sessions. Available tools include `viking_search`, `viking_read`, `viking_browse`, `viking_remember`, `viking_forget`, and `viking_add_resource`.
## See also
diff --git a/docs/images/agents/en/deerflow-mcp.md b/docs/images/agents/en/deerflow-mcp.md
index 722425736..f51436c43 100644
--- a/docs/images/agents/en/deerflow-mcp.md
+++ b/docs/images/agents/en/deerflow-mcp.md
@@ -2,72 +2,54 @@ DeerFlow can connect to OpenViking through an MCP Server. MCP integration lets D
## Step 1: Configure OpenViking credentials
-Set the OpenViking MCP endpoint and API key in the environment that starts DeerFlow:
+Edit the `.env` file in the DeerFlow project root and add the OpenViking USER API Key:
```bash
-export OPENVIKING_MCP_URL="https://api.vikingdb.cn-beijing.volces.com/openviking/mcp"
-export OPENVIKING_API_KEY="[TODO]your-api-key"
+OPENVIKING_API_KEY=[TODO]your-api-key
```
-If DeerFlow uses a `.env` file, add the same variables there and confirm that the startup command loads it.
-
## Step 2: Create an MCP configuration file
-Create an MCP configuration file in the DeerFlow project, for example `mcp.json`:
+Copy `extensions_config.example.json` to `extensions_config.json` in the project root. DeerFlow uses this file to load MCP Servers:
+
+```bash
+cp extensions_config.example.json extensions_config.json
+```
+
+## Step 3: Configure the OpenViking MCP Server
+
+Open `extensions_config.json` in the project root and add OpenViking under `mcpServers`:
```json
{
"mcpServers": {
"openviking": {
- "url": "${OPENVIKING_MCP_URL}",
+ "enabled": true,
+ "type": "http",
+ "url": "[TODO]openviking-base-url/mcp",
"headers": {
- "Authorization": "Bearer ${OPENVIKING_API_KEY}"
+ "X-API-Key": "$OPENVIKING_API_KEY"
}
}
}
}
```
-If DeerFlow already has a standard MCP config path, merge this server into the existing file.
-
-## Step 3: Configure the OpenViking MCP Server
-
-Enable this MCP Server in the DeerFlow agent or tool configuration, and keep the server name aligned with `openviking` in the MCP config file.
-
-Allow DeerFlow to use OpenViking search, read, browse, and health-check tools to cover common memory retrieval and knowledge lookup scenarios.
-
## Step 4: Restart DeerFlow
-Save the MCP configuration and restart DeerFlow:
+Save `.env` and `extensions_config.json`, then restart DeerFlow:
```bash
-pnpm dev
-```
-
-After restart, check the logs and confirm that the `openviking` MCP Server is loaded and its tools are available.
-
-## Step 5: Verify MCP tools
-
-Ask DeerFlow to check the OpenViking service status:
-
-```text
-Use the OpenViking MCP tools to check whether the current service is available.
+make dev
```
-You can also ask DeerFlow to search for an existing memory or resource:
-
-```text
-Search OpenViking for memories related to the current project.
-```
-
-If the agent can call OpenViking MCP tools and return results, MCP integration is working.
-
## Troubleshooting
-| Symptom | Fix |
-|---------|-----|
-| MCP Server is not loaded | Check whether DeerFlow reads the MCP config path and whether the server name is configured consistently |
-| Connection fails or times out | Confirm the runtime can access `api.vikingdb.cn-beijing.volces.com`; configure proxy or network allowlists if needed |
-| OpenViking returns 401 / 403 | Verify `OPENVIKING_API_KEY` and make sure the request header is `Authorization: Bearer <API Key>` |
-| Agent does not call tools | Explicitly allow OpenViking MCP tool usage in the DeerFlow system prompt or tool policy |
-| Search results are empty | Confirm OpenViking already has related memories or knowledge resources, and try broader search keywords |
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| DeerFlow does not load the OpenViking MCP Server after startup | `extensions_config.json` is missing, malformed, or `enabled` is not set to `true` | Check `mcpServers.openviking` and make sure the JSON format is valid |
+| OpenViking MCP tools do not appear in the Agent tool list | The MCP configuration did not take effect, or the service was not restarted | Save the configuration and restart DeerFlow, or refresh the MCP configuration cache |
+| Calling OpenViking MCP tools fails with 401 or 403 | API Key is missing, incorrect, or unauthorized | Check whether `OPENVIKING_API_KEY` is correctly set in `.env` and confirm the header uses `X-API-Key` |
+| MCP Server connection fails | The `url` is incorrect, or DeerFlow Gateway cannot access the OpenViking MCP Server | Check the OpenViking MCP Server address, network connectivity, and Docker network configuration |
+| Old credentials are still used after modifying `.env` | Environment variables were not reloaded, or the MCP configuration cache was not refreshed | Restart DeerFlow, or call `/api/mcp/cache/reset` to refresh the cache |
+| Agent does not actively call OpenViking tools | MCP tools are invoked by the model on demand and are not an automatic memory backend | Explicitly ask the Agent to use OpenViking tools in the prompt, or use MemoryManager integration for automatic recall |
diff --git a/docs/images/agents/en/deerflow-memory-manager.md b/docs/images/agents/en/deerflow-memory-manager.md
index 021756c60..63baddc6d 100644
--- a/docs/images/agents/en/deerflow-memory-manager.md
+++ b/docs/images/agents/en/deerflow-memory-manager.md
@@ -2,78 +2,89 @@ DeerFlow can use OpenViking as a long-term memory backend through MemoryManager.
## Step 1: Configure OpenViking credentials
-Set the OpenViking base URL and API key in the environment that starts DeerFlow:
+Edit the `.env` file in the DeerFlow project root and add the OpenViking USER API Key:
```bash
-export OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking"
-export OPENVIKING_API_KEY="[TODO]your-api-key"
+OPENVIKING_API_KEY=[TODO]your-api-key
```
-If you use `.env` or a deployment platform to manage environment variables, add the same variables there and make sure the DeerFlow process can read them at startup.
-
## Step 2: Update DeerFlow memory configuration
-Enable MemoryManager in the DeerFlow configuration and point the provider to OpenViking:
+Open `config.yaml` in the project root, find the `memory:` section, and replace the default DeerMem configuration with OpenViking:
```yaml
memory:
enabled: true
- provider: openviking
- openviking:
- base_url: ${OPENVIKING_BASE_URL}
- api_key: ${OPENVIKING_API_KEY}
- auto_write: true
- auto_recall: true
- inject_recalled_memory: true
+ injection_enabled: true
+ shutdown_flush_timeout_seconds: 30
+ manager_class: openviking
+ mode: middleware
+ backend_config:
+ base_url: [TODO]openviking-base-url
+ owner_user_id: default
+ api_key_env: OPENVIKING_API_KEY
+ startup_policy: fail_fast
+ failure_policy:
+ read: fail_open
+ write: log_and_drop
+ retrieval:
+ top_k: 8
+ score_threshold: 0.25
+ max_injection_chars: 12000
+ content_mode: overview
+ injection_query: >-
+ user profile preferences important entities events ongoing goals
+ constraints and prior decisions
```
-Enable write, recall, and injection together so DeerFlow can persist long-term memory during conversations and reuse relevant memories in later tasks.
-
## Step 3: Restart DeerFlow
-Save the configuration and restart DeerFlow:
+Save `.env` and `config.yaml`, then restart DeerFlow:
```bash
-pnpm dev
+make dev
```
-If DeerFlow is deployed through Docker, a process manager, or a cloud service, use the corresponding restart flow and verify that the new environment variables are available at runtime.
-
-## Step 4: Verify OpenViking connectivity
+## Step 4: Verify OpenViking integration
-After startup, check the DeerFlow logs and confirm that MemoryManager initializes successfully without OpenViking authentication or network errors.
-
-You can also check OpenViking connectivity directly:
+Check the Gateway logs from the project root:
```bash
-curl -H "Authorization: Bearer ${OPENVIKING_API_KEY}" \
- "${OPENVIKING_BASE_URL}/health"
+grep -i "memory manager resolved\|openviking\|deermem" logs/gateway.log
```
-A service status response means OpenViking is reachable.
+Successful log examples:
+
+```text
+Memory manager resolved: OpenVikingMemoryManager (manager_class='openviking')
+HTTP Request: GET [TODO]openviking-base-url/health "HTTP/1.1 200 OK"
+```
## Step 5: Verify memory write and recall
-Start a DeerFlow conversation with a stable fact, for example:
+Use the following logs to confirm that write and recall are working:
-```text
-Remember that my DeerFlow test project uses OpenViking as the long-term memory backend.
+```bash
+grep -Ei "messages/batch|commit|search/find|has_memory" logs/gateway.log | tail -100
```
-Then start a new conversation and ask:
+Successful log examples:
```text
-What does my DeerFlow test project use as the long-term memory backend?
+/messages/batch "HTTP/1.1 200 OK"
+/commit "HTTP/1.1 200 OK"
+/search/find "HTTP/1.1 200 OK"
+has_memory=True
```
-If DeerFlow answers OpenViking, memory write, recall, and context injection are working.
-
## Troubleshooting
-| Symptom | Fix |
-|---------|-----|
-| MemoryManager fails to initialize | Check `memory.enabled`, `provider`, and whether DeerFlow is loading the expected configuration file |
-| OpenViking returns 401 / 403 | Verify `OPENVIKING_API_KEY`, confirm it has not expired, and make sure requests use the `Bearer` prefix |
-| Memories are not written | Confirm `auto_write` is enabled and check DeerFlow logs for write failures |
-| Memories are not recalled | Confirm `auto_recall` and `inject_recalled_memory` are enabled and OpenViking already has related memories |
-| Works locally but not after deployment | Check whether `OPENVIKING_BASE_URL` and `OPENVIKING_API_KEY` are injected into the deployed runtime |
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| DeerFlow fails to start and reports an OpenViking configuration error | The OpenViking section in `config.yaml` is incomplete or malformed | Check that `manager_class: openviking` is configured and verify fields such as `base_url` and `api_key_env` |
+| DeerFlow is not connected to OpenViking | `memory.manager_class` was not changed to `openviking`, or the service was not restarted after the config change | Save the configuration, restart DeerFlow, and confirm that `OpenVikingMemoryManager` appears in the logs |
+| Remote authentication fails with 401 or 403 | The OpenViking API Key is missing, incorrect, or unauthorized | Check whether `OPENVIKING_API_KEY` is correctly set in `.env` |
+| Retrieval fails but DeerFlow still replies | The current configuration uses `read: fail_open`, which is expected behavior | If OpenViking retrieval fails, memory will not be injected, but the main Agent response will continue |
+| A response is generated but memory write fails | The current configuration uses `write: log_and_drop`, so write failures are recorded in logs | Check and fix OpenViking service, network, and authentication settings. New messages can continue to be written after recovery |
+| Messages have been written, but memories are not visible immediately | OpenViking summarization and memory extraction are asynchronous | Wait for background tasks to finish, then check again |
+| Memory operations are still pending during service shutdown | The system waits up to `shutdown_flush_timeout_seconds` for them to finish | If the wait times out, or OpenViking is unavailable during shutdown, some writes may not complete. Increase the timeout if needed and check OpenViking network/service availability during shutdown |
diff --git a/docs/images/agents/en/hermes.md b/docs/images/agents/en/hermes.md
index 0d78d7ed4..9cc5c17bc 100644
--- a/docs/images/agents/en/hermes.md
+++ b/docs/images/agents/en/hermes.md
@@ -25,7 +25,7 @@ The configuration is saved to Hermes `config.yaml` and `.env` files.
hermes memory status
```
-After configuration, Hermes automatically uses OpenViking as long-term memory. Memory tools such as `viking_remember` and `viking_recall` are available immediately.
+After configuration, Hermes uses the OpenViking memory provider to inject context, prefetch relevant memories, and sync and extract memories after sessions. Available tools include `viking_search`, `viking_read`, `viking_browse`, `viking_remember`, `viking_forget`, and `viking_add_resource`.
## Reference docs
diff --git a/docs/images/agents/en/index.json b/docs/images/agents/en/index.json
index 4ab8c8ff9..7404d4732 100644
--- a/docs/images/agents/en/index.json
+++ b/docs/images/agents/en/index.json
@@ -100,7 +100,7 @@
"id": "deerflow",
"name": "DeerFlow",
"tags": ["MemoryManager", "MCP"],
- "logo": "https://raw.githubusercontent.com/bytedance/deer-flow/main/frontend/public/images/deer.svg",
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/deer.png",
"summary": "DeerFlow can connect through MemoryManager and MCP to automatically write, recall, inject, and manage memory. Enable both methods for the full memory experience.",
"detailPath": "https://docs.openviking.net/agents/en/deerflow-memory-manager.md",
"tabs": [
diff --git a/docs/images/agents/zh/deerflow-mcp.md b/docs/images/agents/zh/deerflow-mcp.md
index 5364429cc..34f8ee93a 100644
--- a/docs/images/agents/zh/deerflow-mcp.md
+++ b/docs/images/agents/zh/deerflow-mcp.md
@@ -2,72 +2,54 @@ DeerFlow 支持通过 MCP Server 接入 OpenViking。MCP 接入的核心价值
## 步骤 1:配置 OpenViking 鉴权信息
-在启动 DeerFlow 的环境中配置 OpenViking MCP 服务地址和 API Key:
+在 DeerFlow 项目根目录下编辑 `.env` 文件,添加 OpenViking USER API Key:
```bash
-export OPENVIKING_MCP_URL="https://api.vikingdb.cn-beijing.volces.com/openviking/mcp"
-export OPENVIKING_API_KEY="[TODO]your-api-key"
+OPENVIKING_API_KEY=[TODO]your-api-key
```
-如果 DeerFlow 使用 `.env` 文件,请写入同名变量,并确认启动命令会加载该文件。
-
## 步骤 2:创建 MCP 配置文件
-在 DeerFlow 项目中创建 MCP 配置文件,例如 `mcp.json`:
+复制 `extensions_config.example.json` 到项目根目录下的 `extensions_config.json`,用于配置 DeerFlow 可加载的 MCP Server:
+
+```bash
+cp extensions_config.example.json extensions_config.json
+```
+
+## 步骤 3:配置 OpenViking MCP Server
+
+打开项目根目录下的 `extensions_config.json`,在 `mcpServers` 中添加 OpenViking 配置:
```json
{
"mcpServers": {
"openviking": {
- "url": "${OPENVIKING_MCP_URL}",
+ "enabled": true,
+ "type": "http",
+ "url": "[TODO]openviking-base-url/mcp",
"headers": {
- "Authorization": "Bearer ${OPENVIKING_API_KEY}"
+ "X-API-Key": "$OPENVIKING_API_KEY"
}
}
}
}
```
-如果 DeerFlow 的 MCP 配置文件路径已有约定,请将以上配置合并到现有文件中。
-
-## 步骤 3:配置 OpenViking MCP Server
-
-在 DeerFlow 的 Agent 或工具配置中启用该 MCP Server,并确保 server 名称与 MCP 配置文件中的 `openviking` 保持一致。
-
-建议允许 DeerFlow 使用 OpenViking 的搜索、读取、目录浏览和健康检查工具,以覆盖常见的记忆检索与知识读取场景。
-
## 步骤 4:重启 DeerFlow
-保存 MCP 配置后重启 DeerFlow:
+保存 `.env` 和 `extensions_config.json` 后,重新启动 DeerFlow:
```bash
-pnpm dev
-```
-
-重启后检查日志,确认 `openviking` MCP Server 已成功加载,且工具列表可以正常获取。
-
-## 步骤 5:验证 MCP 工具是否可用
-
-在 DeerFlow 中发起任务,让 Agent 主动检查 OpenViking 连接状态:
-
-```text
-请使用 OpenViking MCP 工具检查当前服务是否可用。
+make dev
```
-也可以让 DeerFlow 搜索一条已存在的记忆或资源:
-
-```text
-请从 OpenViking 中搜索和当前项目相关的记忆。
-```
-
-如果 Agent 能够调用 OpenViking MCP 工具并返回结果,说明 MCP 接入成功。
-
## 故障排查
-| 现象 | 处理方式 |
-|------|----------|
-| MCP Server 未加载 | 检查 MCP 配置文件路径是否被 DeerFlow 读取,server 名称是否配置一致 |
-| 连接失败或超时 | 确认网络可访问 `api.vikingdb.cn-beijing.volces.com`,必要时配置代理或网络白名单 |
-| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY` 是否正确、是否过期,以及请求头是否为 `Authorization: Bearer <API Key>` |
-| Agent 不主动调用工具 | 在 DeerFlow 的系统提示词或工具策略中明确允许使用 OpenViking MCP 工具 |
-| 搜索结果为空 | 确认 OpenViking 中已有相关记忆或知识资源,并尝试放宽搜索关键词 |
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| DeerFlow 启动后未加载 OpenViking MCP Server | `extensions_config.json` 未配置、配置格式错误,或 `enabled` 未设置为 `true` | 检查 `mcpServers.openviking` 配置,并确认 JSON 格式正确 |
+| OpenViking MCP 工具未出现在 Agent 可用工具中 | MCP 配置未生效,或服务未重启 | 保存配置后重启 DeerFlow,或刷新 MCP 配置缓存 |
+| 调用 OpenViking MCP 工具失败,返回 401 或 403 | API Key 缺失、错误或无权限 | 检查 `.env` 中的 `OPENVIKING_API_KEY` 是否正确,并确认 Header 使用 `X-API-Key` |
+| MCP Server 连接失败 | `url` 配置错误,或 DeerFlow Gateway 无法访问 OpenViking MCP Server | 检查 OpenViking MCP Server 地址、网络连通性和 Docker 网络配置 |
+| 修改 `.env` 后仍然使用旧鉴权信息 | 环境变量未重新加载,或 MCP 配置缓存未刷新 | 重启 DeerFlow,或调用 `/api/mcp/cache/reset` 刷新缓存 |
+| Agent 没有主动调用 OpenViking 工具 | MCP 工具由模型按需调用,不是自动记忆后端 | 在提示词中明确要求使用 OpenViking 工具,或改用 MemoryManager 接入实现自动召回 |
diff --git a/docs/images/agents/zh/deerflow-memory-manager.md b/docs/images/agents/zh/deerflow-memory-manager.md
index b26990c0e..a81e1d792 100644
--- a/docs/images/agents/zh/deerflow-memory-manager.md
+++ b/docs/images/agents/zh/deerflow-memory-manager.md
@@ -2,78 +2,89 @@ DeerFlow 支持通过 MemoryManager 接入 OpenViking 作为长期记忆后端
## 步骤 1:配置 OpenViking 鉴权信息
-在启动 DeerFlow 的环境中配置 OpenViking 服务地址和 API Key:
+在 DeerFlow 项目根目录下编辑 `.env` 文件,添加 OpenViking USER API Key:
```bash
-export OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking"
-export OPENVIKING_API_KEY="[TODO]your-api-key"
+OPENVIKING_API_KEY=[TODO]your-api-key
```
-如果使用 `.env` 或部署平台的环境变量管理能力,请写入同名变量,并确认 DeerFlow 进程启动时能够读取到。
-
## 步骤 2:修改 DeerFlow 的 memory 配置
-在 DeerFlow 的配置文件中启用 MemoryManager,并将 provider 指向 OpenViking:
+打开项目根目录下的 `config.yaml`,找到 `memory:` 配置段,将默认的 DeerMem 配置替换为 OpenViking 配置:
```yaml
memory:
enabled: true
- provider: openviking
- openviking:
- base_url: ${OPENVIKING_BASE_URL}
- api_key: ${OPENVIKING_API_KEY}
- auto_write: true
- auto_recall: true
- inject_recalled_memory: true
+ injection_enabled: true
+ shutdown_flush_timeout_seconds: 30
+ manager_class: openviking
+ mode: middleware
+ backend_config:
+ base_url: [TODO]openviking-base-url
+ owner_user_id: default
+ api_key_env: OPENVIKING_API_KEY
+ startup_policy: fail_fast
+ failure_policy:
+ read: fail_open
+ write: log_and_drop
+ retrieval:
+ top_k: 8
+ score_threshold: 0.25
+ max_injection_chars: 12000
+ content_mode: overview
+ injection_query: >-
+ user profile preferences important entities events ongoing goals
+ constraints and prior decisions
```
-建议同时开启写入、召回和注入,确保 DeerFlow 能够在对话过程中持续沉淀长期记忆,并在后续任务中自动使用相关记忆。
-
## 步骤 3:重启 DeerFlow
-保存配置后重启 DeerFlow,使新的 memory 配置生效:
+保存 `.env` 和 `config.yaml` 后,重新启动 DeerFlow:
```bash
-pnpm dev
+make dev
```
-如果你通过 Docker、进程管理器或云服务部署 DeerFlow,请使用对应的重启方式,并确认新的环境变量已注入到运行时。
-
## 步骤 4:验证 OpenViking 是否接入成功
-启动后检查 DeerFlow 日志,确认 MemoryManager 初始化成功,且没有出现 OpenViking 鉴权或网络错误。
-
-也可以直接检查 OpenViking 服务连通性:
+在项目根目录下查看 Gateway 日志:
```bash
-curl -H "Authorization: Bearer ${OPENVIKING_API_KEY}" \
- "${OPENVIKING_BASE_URL}/health"
+grep -i "memory manager resolved\|openviking\|deermem" logs/gateway.log
```
-返回服务状态信息即表示 OpenViking 服务可访问。
+成功日志示例:
+
+```text
+Memory manager resolved: OpenVikingMemoryManager (manager_class='openviking')
+HTTP Request: GET [TODO]openviking-base-url/health "HTTP/1.1 200 OK"
+```
-## 步骤 5:验证记忆写入与召回是否正常
+## 步骤 5:验证写入与召回
-在 DeerFlow 中发起一轮包含稳定事实的对话,例如:
+可通过以下日志确认写入和召回是否正常:
-```text
-请记住:我的 DeerFlow 测试项目使用 OpenViking 作为长期记忆后端。
+```bash
+grep -Ei "messages/batch|commit|search/find|has_memory" logs/gateway.log | tail -100
```
-随后开启一轮新对话并询问:
+成功日志示例:
```text
-我的 DeerFlow 测试项目使用什么作为长期记忆后端?
+/messages/batch "HTTP/1.1 200 OK"
+/commit "HTTP/1.1 200 OK"
+/search/find "HTTP/1.1 200 OK"
+has_memory=True
```
-如果 DeerFlow 能够回答 OpenViking,说明记忆写入、召回和上下文注入链路已经生效。
-
## 故障排查
-| 现象 | 处理方式 |
-|------|----------|
-| MemoryManager 初始化失败 | 检查 `memory.enabled`、`provider` 和 OpenViking 配置项是否已写入 DeerFlow 实际加载的配置文件 |
-| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY` 是否正确、是否过期,以及请求头是否带有 `Bearer` 前缀 |
-| 记忆没有写入 | 确认 `auto_write` 已开启,并检查 DeerFlow 日志中是否有写入失败信息 |
-| 记忆无法召回 | 确认 `auto_recall` 和 `inject_recalled_memory` 已开启,并确保 OpenViking 中已有相关记忆 |
-| 本地可用、部署后不可用 | 检查部署环境是否正确注入 `OPENVIKING_BASE_URL` 和 `OPENVIKING_API_KEY` |
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| DeerFlow 启动失败,提示 OpenViking 配置错误 | `config.yaml` 中 OpenViking 配置不完整或格式错误 | 检查 `config.yaml` 中是否已配置 `manager_class: openviking`,并确认 `base_url`、`api_key_env` 等字段正确 |
+| DeerFlow 未接入 OpenViking | `memory.manager_class` 未改为 `openviking`,或修改配置后未重启服务 | 保存配置后重新启动 DeerFlow,并确认日志中出现 `OpenVikingMemoryManager` |
+| 远程认证失败,返回 401 或 403 | OpenViking API Key 缺失、错误或无权限 | 检查 `.env` 中的 `OPENVIKING_API_KEY` 是否正确 |
+| 检索失败,但 DeerFlow 仍继续回复 | 当前配置采用 `read: fail_open`,属于预期行为 | OpenViking 检索失败时不会注入记忆,但不会影响主 Agent 正常回复 |
+| 回复已生成,但记忆写入失败 | 当前配置采用 `write: log_and_drop`,写入失败会被记录到日志中 | 检查并修复 OpenViking 服务、网络和鉴权配置,后续新消息可继续写入 |
+| 已写入消息,但页面未立即看到记忆 | OpenViking 的摘要和记忆提取是异步完成的 | 等待后台任务完成后再查看 |
+| 服务关闭时仍有记忆操作未完成 | 系统会在 `shutdown_flush_timeout_seconds` 配置的时间内等待其完成 | 若等待超时,或 OpenViking 在关闭期间不可用,部分记忆写入可能无法完成。可适当调大该配置,并检查关闭期间 OpenViking 的网络和服务状态 |
diff --git a/docs/images/agents/zh/hermes.md b/docs/images/agents/zh/hermes.md
index c1ec619b0..a52fb38ed 100644
--- a/docs/images/agents/zh/hermes.md
+++ b/docs/images/agents/zh/hermes.md
@@ -26,7 +26,7 @@ https://api.vikingdb.cn-beijing.volces.com/openviking
hermes memory status
```
-配置完成后,Hermes 自动使用 OpenViking 作为长期记忆——`viking_remember`、`viking_recall` 等记忆工具即刻可用。
+配置完成后,Hermes 会通过 OpenViking memory provider 自动注入上下文、预取相关记忆,并在会话后同步和抽取记忆。可用工具包括 `viking_search`、`viking_read`、`viking_browse`、`viking_remember`、`viking_forget` 和 `viking_add_resource`。
## 参考文档
diff --git a/docs/images/agents/zh/index.json b/docs/images/agents/zh/index.json
index 4c533d5ff..8c4521d04 100644
--- a/docs/images/agents/zh/index.json
+++ b/docs/images/agents/zh/index.json
@@ -100,7 +100,7 @@
"id": "deerflow",
"name": "DeerFlow",
"tags": ["MemoryManager", "MCP"],
- "logo": "https://raw.githubusercontent.com/bytedance/deer-flow/main/frontend/public/images/deer.svg",
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/deer.png",
"summary": "DeerFlow 支持通过 MemoryManager 和 MCP 接入,实现记忆的自动写入、召回、注入及管理。建议同时启用两种方式,以获得完整的记忆体验。",
"detailPath": "https://docs.openviking.net/agents/zh/deerflow-memory-manager.md",
"tabs": [
diff --git a/docs/zh/agent-integrations/05-hermes.md b/docs/zh/agent-integrations/05-hermes.md
index 20d4d94e2..abc4795b4 100644
--- a/docs/zh/agent-integrations/05-hermes.md
+++ b/docs/zh/agent-integrations/05-hermes.md
@@ -33,7 +33,7 @@ hermes memory setup
hermes memory status
```
-配置完成后,Hermes 自动使用 OpenViking 作为长期记忆——`viking_remember`、`viking_recall` 等记忆工具即刻可用。
+配置完成后,Hermes 会通过 OpenViking memory provider 自动注入上下文、预取相关记忆,并在会话后同步和抽取记忆。可用工具包括 `viking_search`、`viking_read`、`viking_browse`、`viking_remember`、`viking_forget` 和 `viking_add_resource`。
## 参见