Agent 接入--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

控制台文档

Agent 接入

接入说明

OpenViking Service 支持 MCP、CLI、API、SDK 接入您的自研 Agent 框架，同时对主流 Agent 框架进行生态适配。
当前文档仅展示了常用 Agent 接入步骤，更多 Agent 您可以在控制台上点击【接入 Agent】进入查看

认证说明

⚠️ 注意：Agent 接入 OpenViking 时，必须使用 OpenViking 的 APIKey 作为唯一认证，并关联到对应的数据
获取参考：

OpenClaw 接入

说明

集成方式：Plugin 接入，作为 OpenClaw 的 context engine，支持多 Agent 跨会话记忆与自迭代，通过 npm 安装助手工具一键完成配置

前置条件：您已经在本地或者云服务器上部署了 OpenClaw 2026.5.2 或更新的版本

步骤 1 安装 OpenViking
在你的 OpenClaw 的机器终端，执行以下命令以安装 OpenViking Plugin

openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup

步骤 2 输入以下信息
执行安装命令后会依次提示输入以下信息，可复制后粘贴到你的 Agent 终端

Base URL: https://api.vikingdb.cn-beijing.volces.com/openviking
API Key: 复制页面中展示的 API Key 到你的 Agent 终端

步骤 3 重启 OpenClaw
复制以下指令到 Agent 终端以重启 OpenClaw，重启后控制台将自动判断 Agent 接入状态

openclaw gateway restart

Hermes Agent 接入

说明

集成方式：Hermes 官方内置 OpenViking 作为记忆提供方。无需安装插件——直接把 Hermes 指向你的 OpenViking 服务即可，记忆存储、召回和抽取均原生支持

配置
运行 Hermes 记忆配置向导：

hermes memory setup

向导会询问：

OpenViking 服务 URL — 自托管服务器或火山引擎 OpenViking Service
API Key — 火山引擎 OpenViking Service 时填 API Key
租户 account / user / agent ID — 多租户部署时使用

配置保存在 Hermes 的 config.yaml 和 .env 文件中。

验证

hermes memory status

配置完成后，Hermes 自动使用 OpenViking 作为长期记忆——viking_remember、viking_recall 等记忆工具即刻可用。

Claude Code 接入

说明

集成方式：Plugin 接入，为 Claude Code 添加跨项目、跨会话（session）的长期记忆功能。安装完成后，每轮对话均会自动召回相关记忆并捕获新内容，无需模型主动调用任何工具

步骤 1：安装

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)

该脚本将自动检查依赖项、配置 OpenViking 连接并完成插件安装，支持重复运行（幂等操作）。
安装完成后，需在当前终端激活 claude 的封装函数（wrapper），或者直接打开一个新的终端窗口：

source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh

通过自定义命令启动 Claude Code？例如包装脚本 cc-custom，或“基础命令 + 子命令”形式的多词启动器——在安装时的“Extra launch commands”一步填入（或运行脚本时传入 OPENVIKING_CC_WRAP_EXTRA='cc-custom'），即可让它们一并注入凭据。

使用一段时间后，即便在全新的对话中提及过往的话题，Claude Code 也能准确回忆起来。

步骤 2：验证

type claude        # 期望输出：claude is a shell function

若上一步输出的是一个路径而非 shell function，说明 wrapper 尚未生效，请先 source 那行 wrapper（或新开一个终端）再启动；否则 claude 会静默连到本地 127.0.0.1 且不带鉴权。

在 type claude 显示为 shell function 的终端中运行 claude 启动，随后：

输入 /plugins → 在 Installed 列表中应能找到 openviking-memory（其子项openviking MCP 应显示为已连接状态）。
输入 /mcp → OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。
输入 /openviking-memory:ov → 查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。

若插件未正常工作，可设置环境变量 OPENVIKING_DEBUG=1，并查看日志文件 ~/.openviking/logs/cc-hooks.log 以排查问题。

Codex 接入

说明

集成方式：Plugin 接入，为 Codex 提供持久化的跨会话（session）记忆。一次安装，即可实现：在用户每次输入前自动召回记忆，每轮对话结束后进行增量捕获，并在上下文压缩（compaction）前将记忆提交给抽取器

步骤 1：安装

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)

该脚本会自动检查依赖、配置 OpenViking 连接并注册插件。所有步骤均具有幂等性，可安全地重复执行。
安装完成后，在当前终端激活 codex 封装函数（或重新打开一个终端窗口）：

source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh
codex              # 首次启动需执行 /hooks 进行一次安全审批

通过自定义命令启动 Codex？例如包装脚本 codex-custom，或“基础命令 + 子命令”形式的多词启动器——在安装时的“Extra launch commands”一步填入（或运行脚本时传入 OPENVIKING_CODEX_WRAP_EXTRA='codex-custom'），即可让它们一并注入凭据。

步骤 2：验证

type codex         # 期望输出：codex is a shell function

若上一步输出的是一个路径而非 shell function，说明 wrapper 尚未生效，请先 source 那行 wrapper（或新开一个终端）再启动；否则 codex 启动时拿不到 OPENVIKING_API_KEY，会报 MCP server is not logged in。

进入 Codex 后，插件将在每次输入前自动召回记忆。将环境变量 OPENVIKING_DEBUG 设置为 1，可将事件日志输出至 ~/.openviking/logs/codex-hooks.log。

CLI 接入

终端安装

步骤1：安装 OpenViking CLI，并进入配置流程：

npm i -g @openviking/cli && ov config

步骤2：按提示填写 OpenViking Base URL 和 API Key

Base URL: 复制以下 Base URL 到你的终端

https://api.vikingdb.cn-beijing.volces.com/openviking

API Key: 复制以下 API Key 到你的终端

ZGVmY*****IwZQ

步骤3：配置完成后，可运行以下命令查看 CLI 用法：

ov --help

Agent 安装

将下方提示词复制给你的 AI 助手（Claude Code、Codex、Cursor、Trae 等），它会自动完成 OpenViking CLI 安装、配置和用法学习：

请先向用户询问 OpenViking API Key，并记为 OPENVIKING_API_KEY。

请在 ~/.openviking/ovcli.conf 写入以下内容：
{
  "url": "https://api.vikingdb.cn-beijing.volces.com/openviking",
  "api_key": "ZGVmY*****IwZQ"
}

如发现 ~/.openviking/ovcli.conf 已存在且内容冲突，请先询问用户是否备份原文件，并在得到确认后再覆盖。

请安装 OpenViking CLI：
npm i -g @openviking/cli

安装完成后，请运行：
ov --help

请探索 CLI 用法，并把 OpenViking CLI 的使用方式写入你的长期记忆。

MCP 接入

步骤 1：MCP 配置

{
  "mcpServers": {
    "ov-mcp-server": {
      "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
      "headers": {
        "Authorization": "Bearer ZGVmY*****IwZQ"
      }
    }
  }
}

步骤 2：测试 MCP 工具连通性
输入 ov health 检查 ov 的版本和连接状态

ov health

MCP 支持的工具范围如下：

工具	描述
add_resource	Add a remote resource (HTTP/HTTPS URL or git URL) to OpenViking. Asynchronous - processed in the background. Local file paths are not supported here; use the 'ov add-resource`CLI for local files. \|
find	Fast semantic retrieval without session context. Returns ranked memories, resources, and skills with URI, abstract, and score.
forget	Permanently delete a viking:// URI from OpenViking. This is irreversible. Only use when the user explicitly asks to forget or delete something. Always confirm with the user before calling this tool. Use the search tool first to find the exact URI, then pass it here. Set recursive=true only when the user explicitly asks to delete a directory tree.
glob	Find viking:// files matching a glob pattern (e.g. */.md, *.py). Use this for filename matching; use the search tool for content-based retrieval.
grep	Search content in viking:// files using regex patterns (like grep). Supports multiple patterns searched concurrently. Use this for exact text matching; use the search tool for semantic retrieval.
health	Check whether the OpenViking server is healthy.
list	List files and subdirectories under a viking:// directory URI. Use recursive=true for deep listing.
read	Read full content from one or more viking:// file URIs. Pass a single URI string or a list for batch reads. For directory listing, use the list tool instead.
remember	Store information into OpenViking long-term memory. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting.
search	Deep semantic retrieval with optional session context and intent analysis. Returns ranked memories, resources, and skills with URI, abstract, and score.

SDK 接入

步骤 1：安装 OpenViking Service
执行以下命令安装 OpenViking pipy 包：

pip install openviking --upgrade --force-reinstall

步骤 2：初始化客户端
建议使用同步 HTTP 客户端连接商业化服务。

from openviking.client import SyncHTTPClient

url = "https://api.vikingdb.cn-beijing.volces.com/openviking"
api_key = "your-api-key" #可在【用户管理页面】复制
agent_id = "your-agent-id" #自定义agent-id

client = SyncHTTPClient(
    url=url,
    api_key=api_key,
    agent_id=agent_id,
    timeout=120.0,
)
client.initialize()

参数说明：

url：火山引擎提供的 OpenViking Service 服务地址
api_key：【用户管理】页面展示的 API Key（挂个超链）
agent_id：当前 Agent 的标识，用于隔离 Agent 侧上下文
timeout：单次请求超时时间，上传文件或提交会话时建议适当放大

步骤 3：选择并配置 API Key
将控制台页面中展示的 API Key 复制到你的 Agent 运行环境中，建议通过环境变量或安全配置中心进行注入，而不要直接硬编码在代码里。
例如：

export OPENVIKING_API_KEY="your-api-key"

然后在代码中读取：

import os
import openviking as ov

client = ov.SyncHTTPClient(
    url="https://api.vikingdb.cn-beijing.volces.com/openviking",
    api_key=os.environ["OPENVIKING_API_KEY"],
    agent_id="your-agent-id",
    timeout=120.0,
)
client.initialize()

步骤 4：写入资源
资源写入用于把外部知识导入 OpenViking Service。SDK 可以直接接收本地文件路径、目录路径或远端 URL，并自动处理上传细节。

file_path = "your-file-path"
resource_to = "your-resource-path"  # e.g. viking://resources/demo/api.md
reason = "your-reason"  # e.g. External API documentation

result = client.add_resource(
    path=file_path,
    to=resource_to,
    reason=reason,
    wait=True,
)

print(result)

to 必须位于 viking://resources/... 作用域下
如果 path 是本地文件，SDK 会自动先上传再调用服务端接口
如果 wait=True，接口会等待资源处理完成后再返回，更适合导入后马上检索的场景
如果不希望阻塞，也可以使用默认异步模式，然后显式调用 client.wait_processed()

例如：

result = client.add_resource(
    path=file_path,
    to=resource_to,
    reason=reason,
)

client.wait_processed()

步骤 5：写入记忆
记忆写入建议通过会话方式完成。下面示例演示如何将一条用户消息写入会话，并通过提交触发后续记忆提取。

text = "your-message-text"  # e.g. I am a developer

session = client.create_session()
session_id = session["result"]["session_id"] if "result" in session else session["session_id"]

client.add_message(
    session_id,
    "user",
    parts=[{"type": "text", "text": text}],
)

result = client.commit_session(session_id)
print(result)

create_session() 用于创建一条新的会话链路
add_message() 用于向会话中追加消息
commit_session() 会触发会话归档和记忆提取
提交结果通常会返回 task_id，表示后台任务已被接受

API 接入

如果您希望通过平台网关、工作流引擎、低代码平台直接调用接口，推荐使用 HTTP API 接入。
步骤 1：选择 API Key
将控制台页面展示的 API Key 放入你的 Agent 运行环境，并在请求头中传递。
OpenViking Service 同时支持两种鉴权方式，详情见 API 鉴权说明
步骤 2：写入资源
对于裸 HTTP 接口，本地文件不能直接作为 path 传给 /api/v1/resources。标准流程是：

先调用 POST /api/v1/resources/temp_upload 上传本地文件
获取返回的 temp_file_id
再调用 POST /api/v1/resources，把临时文件写入目标资源路径

示例如下：

import json
from pathlib import Path

import requests

url = "https://api.vikingdb.cn-beijing.volces.com/openviking"
api_key = "your-api-key" #可在【用户管理页面】复制
agent_id = "your-agent-id" #自定义agent-id
file_path = Path("your-file-path")  # e.g. test.txt
resource_to = "your-resource-path"  # e.g. viking://resources/demo/test.txt
reason = "your-reason"  # e.g. External API documentation

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + api_key,
    "X-OpenViking-Agent": agent_id,
}


def post_json(path: str, payload: dict, timeout: float):
    response = requests.post(
        f"{url}{path}",
        headers=headers,
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


with file_path.open("rb") as file:
    result = requests.post(
        f"{url}/api/v1/resources/temp_upload",
        headers={
            "Authorization": "Bearer " + api_key,
            "X-OpenViking-Agent": agent_id,
        },
        files={"file": (file_path.name, file, "application/octet-stream")},
        timeout=120.0,
    )

result.raise_for_status()
result = result.json()
print(json.dumps(result, ensure_ascii=False, indent=2))

temp_file_id = result["result"]["temp_file_id"]

result = post_json(
    "/api/v1/resources",
    {
        "temp_file_id": temp_file_id,
        "source_name": file_path.name,
        "to": resource_to,
        "reason": reason,
    },
    120.0,
)

print(json.dumps(result, ensure_ascii=False, indent=2))

说明：

/api/v1/resources 可以直接接收远端 URL，但不接受宿主机本地路径
X-OpenViking-Agent 是可选请求头；如果不传，服务端默认使用 default

步骤 3：写入记忆
通过 API 写入记忆时，同样遵循“创建会话 - 添加消息 - 提交会话”的流程。

import json
import requests

url = "https://api.vikingdb.cn-beijing.volces.com/openviking"
api_key = "your-api-key" #可在【用户管理页面】复制
agent_id = "your-agent-id" #自定义agent-id
text = "your-message-text"  # e.g. I am a developer

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + api_key,
    "X-OpenViking-Agent": agent_id,
}


def post_json(path: str, payload: dict, timeout: float):
    response = requests.post(
        f"{url}{path}",
        headers=headers,
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


session = post_json("/api/v1/sessions", {}, 360.0)
session_id = session["result"]["session_id"]

post_json(
    f"/api/v1/sessions/{session_id}/messages",
    {
        "role": "user",
        "parts": [{"type": "text", "text": text}],
    },
    360.0,
)

result = post_json(
    f"/api/v1/sessions/{session_id}/commit",
    {"telemetry": False},
    360.0,
)

print(json.dumps(result, ensure_ascii=False, indent=2))

说明：

/api/v1/sessions 用于创建会话
/api/v1/sessions/{id}/messages 用于追加消息
/api/v1/sessions/{id}/commit 用于触发归档与记忆提取
如果你的 Agent 只需要写入纯文本，也可以把 parts 改为简单的 content

SDK 接入与 API 接入如何选择

场景	推荐方式	原因
Python Agent / Python 服务	SDK 接入	封装更完整，开发效率更高
非 Python 技术栈	API 接入	更通用，便于跨语言接入
本地文件批量导入	SDK 接入	自动处理上传细节
网关、编排平台、工作流平台	API 接入	便于统一代理和权限控制

补充说明

1. `agent_id` 的作用

agent_id 用于标识当前 Agent，不同 Agent 建议使用不同 agent_id，如果不传，服务端通常使用默认值。

2. 资源路径如何填写

资源目标路径应填写到 viking://resources/...
推荐按项目、场景或知识类型进行目录化组织

例如：

viking://resources/product-docs/
viking://resources/api/auth.md
viking://resources/support/faq/

最近更新时间：2026.06.10 20:19:10

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

终端安装 #

Agent 安装 #

补充说明 #

1. agent_id 的作用 #

2. 资源路径如何填写 #

终端安装

Agent 安装

补充说明

1. `agent_id` 的作用

2. 资源路径如何填写