Skip to content

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

docs: update agent integration docs (#2377)

yufeng15f7d38face2
diff --git a/docs/images/agents/en/agent-cli.md b/docs/images/agents/en/agent-cli.md
new file mode 100644
index 000000000..f0f1e017b
--- /dev/null
+++ b/docs/images/agents/en/agent-cli.md
@@ -0,0 +1,18 @@
+# Agent CLI Integration
+
+For AI agents. Send the following instruction to your agent so it can install and configure OpenViking CLI, then learn how to use it.
+
+```text
+Write the following content to ~/.openviking/ovcli.conf:
+{"url":"https://api.vikingdb.cn-beijing.volces.com/openviking","api_key":"Please ask user for Volcengine OpenViking API key."}
+
+Ask the user for the API Key. If ~/.openviking/ovcli.conf already exists and the content conflicts, ask the user whether to back up the original file before overwriting it.
+
+Install OpenViking CLI:
+npm i -g @openviking/cli
+
+After installation, run:
+ov --help
+
+Explore the CLI usage and write the OpenViking CLI workflow into your long-term memory.
+```
diff --git a/docs/images/agents/en/cli.md b/docs/images/agents/en/cli.md
index ca902820b..b17f33150 100644
--- a/docs/images/agents/en/cli.md
+++ b/docs/images/agents/en/cli.md
@@ -1,6 +1,6 @@
-# CLI Integration
+# Command Line Integration
-## Install from the command line
+For developers who want to install, configure, and use OpenViking CLI directly from a local terminal.
Run the following command in your terminal to install OpenViking CLI and start configuration:
@@ -19,22 +19,3 @@ After configuration, inspect CLI usage with:
```bash
ov --help
```
-
-## Install through an agent conversation
-
-The Agent CLI setup flow will be improved in a follow-up PR. For now, send the following instruction to your agent:
-
-```text
-Write the following content to ~/.openviking/ovcli.conf:
-{"url":"https://api.vikingdb.cn-beijing.volces.com/openviking","api_key":"Please ask user for Volcengine OpenViking API key."}
-
-Ask the user for the API Key. If ~/.openviking/ovcli.conf already exists and the content conflicts, ask the user whether to back up the original file before overwriting it.
-
-Install OpenViking CLI:
-npm i -g @openviking/cli
-
-After installation, run:
-ov --help
-
-Explore the CLI usage and write the OpenViking CLI workflow into your long-term memory.
-```
diff --git a/docs/images/agents/en/index.json b/docs/images/agents/en/index.json
index 2799db3a8..3e8e5a34b 100644
--- a/docs/images/agents/en/index.json
+++ b/docs/images/agents/en/index.json
@@ -1,6 +1,6 @@
{
"version": 1,
- "updatedAt": "2026-06-01",
+ "updatedAt": "2026-06-02",
"cdnBaseUrl": "https://docs.openviking.net/",
"accessMethods": [
{
@@ -14,9 +14,16 @@
"id": "cli",
"name": "CLI Integration",
"icon": "terminal",
- "summary": "Connect agents through the OpenViking command line.",
+ "summary": "Install, configure, and use OpenViking CLI directly from a terminal.",
"detailPath": "https://docs.openviking.net/agents/en/cli.md"
},
+ {
+ "id": "agent-cli",
+ "name": "Agent CLI Integration",
+ "icon": "paperclip",
+ "summary": "Send setup instructions to an AI agent so it can learn and remember the CLI workflow.",
+ "detailPath": "https://docs.openviking.net/agents/en/agent-cli.md"
+ },
{
"id": "api",
"name": "API Integration",
@@ -43,7 +50,7 @@
},
{
"id": "hermes",
- "name": "Hermes",
+ "name": "Hermes Agent",
"tags": ["Provider"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",
"summary": "Hermes includes OpenViking as a native memory provider. Point Hermes to your OpenViking service to enable storage, recall, and extraction.",
@@ -83,7 +90,7 @@
},
{
"id": "opencode",
- "name": "Opencode",
+ "name": "OpenCode",
"tags": ["Plugin"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/OpenCode.png",
"summary": "Provides OpenCode plugins that can expose OpenViking either as model-selected tools or injected context.",
diff --git a/docs/images/agents/image/trae/01-api-key.jpg b/docs/images/agents/image/trae/01-api-key.jpg
new file mode 100644
index 000000000..8f9c6ccb8
Binary files /dev/null and b/docs/images/agents/image/trae/01-api-key.jpg differ
diff --git a/docs/images/agents/image/trae/02-open-settings.jpg b/docs/images/agents/image/trae/02-open-settings.jpg
new file mode 100644
index 000000000..3b0c6616b
Binary files /dev/null and b/docs/images/agents/image/trae/02-open-settings.jpg differ
diff --git a/docs/images/agents/image/trae/03-mcp-settings.jpg b/docs/images/agents/image/trae/03-mcp-settings.jpg
new file mode 100644
index 000000000..c99aa6d63
Binary files /dev/null and b/docs/images/agents/image/trae/03-mcp-settings.jpg differ
diff --git a/docs/images/agents/image/trae/04-add-mcp-server.jpg b/docs/images/agents/image/trae/04-add-mcp-server.jpg
new file mode 100644
index 000000000..70221cfae
Binary files /dev/null and b/docs/images/agents/image/trae/04-add-mcp-server.jpg differ
diff --git a/docs/images/agents/image/trae/05-manual-config.png b/docs/images/agents/image/trae/05-manual-config.png
new file mode 100644
index 000000000..fcd19b9b2
Binary files /dev/null and b/docs/images/agents/image/trae/05-manual-config.png differ
diff --git a/docs/images/agents/image/trae/06-paste-mcp-json.jpg b/docs/images/agents/image/trae/06-paste-mcp-json.jpg
new file mode 100644
index 000000000..73bdf1785
Binary files /dev/null and b/docs/images/agents/image/trae/06-paste-mcp-json.jpg differ
diff --git a/docs/images/agents/image/trae/07-enable-server.jpg b/docs/images/agents/image/trae/07-enable-server.jpg
new file mode 100644
index 000000000..3574986e9
Binary files /dev/null and b/docs/images/agents/image/trae/07-enable-server.jpg differ
diff --git a/docs/images/agents/image/trae/08-ov-ls.jpg b/docs/images/agents/image/trae/08-ov-ls.jpg
new file mode 100644
index 000000000..6ca8f9bc0
Binary files /dev/null and b/docs/images/agents/image/trae/08-ov-ls.jpg differ
diff --git a/docs/images/agents/image/trae/09-ov-health.jpg b/docs/images/agents/image/trae/09-ov-health.jpg
new file mode 100644
index 000000000..c4aa001a4
Binary files /dev/null and b/docs/images/agents/image/trae/09-ov-health.jpg differ
diff --git a/docs/images/agents/image/trae/10-schema-error.png b/docs/images/agents/image/trae/10-schema-error.png
new file mode 100644
index 000000000..bb9e08de9
Binary files /dev/null and b/docs/images/agents/image/trae/10-schema-error.png differ
diff --git a/docs/images/agents/image/trae/11-schema-error-detail.png b/docs/images/agents/image/trae/11-schema-error-detail.png
new file mode 100644
index 000000000..b71446e90
Binary files /dev/null and b/docs/images/agents/image/trae/11-schema-error-detail.png differ
diff --git a/docs/images/agents/zh/agent-cli.md b/docs/images/agents/zh/agent-cli.md
new file mode 100644
index 000000000..59567e7a6
--- /dev/null
+++ b/docs/images/agents/zh/agent-cli.md
@@ -0,0 +1,18 @@
+# Agent CLI 接入
+
+面向 AI Agent 使用。把下面的指令发送给你的 Agent,让它完成 OpenViking CLI 安装、配置和用法学习。
+
+```text
+请在 ~/.openviking/ovcli.conf 写入以下内容:
+{"url":"https://api.vikingdb.cn-beijing.volces.com/openviking","api_key":"Please ask user for Volcengine OpenViking API key."}
+
+请向用户询问 API Key。如发现 ~/.openviking/ovcli.conf 已存在且内容冲突,请先询问用户是否备份原文件,并在得到确认后再覆盖。
+
+请安装 OpenViking CLI:
+npm i -g @openviking/cli
+
+安装完成后,请运行:
+ov --help
+
+请探索 CLI 用法,并把 OpenViking CLI 的使用方式写入你的长期记忆。
+```
diff --git a/docs/images/agents/zh/cli.md b/docs/images/agents/zh/cli.md
index f537d8b86..bff7c35c9 100644
--- a/docs/images/agents/zh/cli.md
+++ b/docs/images/agents/zh/cli.md
@@ -1,6 +1,6 @@
-# CLI 接入
+# 命令行接入
-## CLI 命令行安装
+面向开发者在本地终端直接安装、配置和使用 OpenViking CLI。
在终端执行以下命令安装 OpenViking CLI,并进入配置流程:
@@ -19,22 +19,3 @@ https://api.vikingdb.cn-beijing.volces.com/openviking
```bash
ov --help
```
-
-## Agent 对话安装
-
-下个 PR 将继续优化 Agent CLI 安装流程,目前可先把以下指令发送给你的 Agent,让 Agent 帮你完成安装和配置:
-
-```text
-请在 ~/.openviking/ovcli.conf 写入以下内容:
-{"url":"https://api.vikingdb.cn-beijing.volces.com/openviking","api_key":"Please ask user for Volcengine OpenViking API key."}
-
-请向用户询问 API Key。如发现 ~/.openviking/ovcli.conf 已存在且内容冲突,请先询问用户是否备份原文件,并在得到确认后再覆盖。
-
-请安装 OpenViking CLI:
-npm i -g @openviking/cli
-
-安装完成后,请运行:
-ov --help
-
-请探索 CLI 用法,并把 OpenViking CLI 的使用方式写入你的长期记忆。
-```
diff --git a/docs/images/agents/zh/index.json b/docs/images/agents/zh/index.json
index 9ac5886f0..1ded85e69 100644
--- a/docs/images/agents/zh/index.json
+++ b/docs/images/agents/zh/index.json
@@ -1,6 +1,6 @@
{
"version": 1,
- "updatedAt": "2026-06-01",
+ "updatedAt": "2026-06-02",
"cdnBaseUrl": "https://docs.openviking.net/",
"accessMethods": [
{
@@ -14,9 +14,16 @@
"id": "cli",
"name": "CLI 接入",
"icon": "terminal",
- "summary": "命令行接入 Agent,使用灵活性更高",
+ "summary": "面向开发者在终端直接安装、配置和使用 OpenViking CLI",
"detailPath": "https://docs.openviking.net/agents/zh/cli.md"
},
+ {
+ "id": "agent-cli",
+ "name": "Agent CLI 接入",
+ "icon": "paperclip",
+ "summary": "把安装配置指令交给 AI Agent,让它像 skill 一样学会并记住 CLI 用法",
+ "detailPath": "https://docs.openviking.net/agents/zh/agent-cli.md"
+ },
{
"id": "api",
"name": "API 接入",
@@ -43,7 +50,7 @@
},
{
"id": "hermes",
- "name": "Hermes",
+ "name": "Hermes Agent",
"tags": ["Provider"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",
"summary": "Hermes 官方内置 OpenViking 作为记忆提供方。无需安装插件——直接把 Hermes 指向你的 OpenViking 服务即可,记忆存储、召回和抽取均原生支持",
@@ -70,7 +77,7 @@
"name": "Cursor",
"tags": ["MCP"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Cursor.png",
- "summary": "通过 MCP 标准协议接入,为 Codex 提供支撑日常编码 和 Agent 开发场景的上下文管理",
+ "summary": "通过 MCP 标准协议接入,为 Cursor 提供支撑日常编码和 Agent 开发场景的上下文管理",
"detailPath": "https://docs.openviking.net/agents/zh/cursor.md"
},
{
@@ -83,7 +90,7 @@
},
{
"id": "opencode",
- "name": "Opencode",
+ "name": "OpenCode",
"tags": ["Plugin"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/OpenCode.png",
"summary": "提供两种 OpenCode 插件,可以模型自主选择使用,也可以注入上下文使用",
diff --git a/docs/images/agents/zh/trae.md b/docs/images/agents/zh/trae.md
index 5dc190881..0471ee389 100644
--- a/docs/images/agents/zh/trae.md
+++ b/docs/images/agents/zh/trae.md
@@ -30,7 +30,7 @@
**安全提示**:API Key 等同于账户密钥,请勿提交到 Git 仓库或公开渠道。建议通过环境变量或加密配置注入。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MTNkMDA0ZDBhZGRmODlkNmNjMGRiMGEwZTIyMzZlNThfMmNkMmZlZjA1ZWJjNTAyMGMzODFiNmRiZDk2ZTU3ZDhfSUQ6NzY0NDUxMTgwNDM5NjI3NjkzNl8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![获取 OpenViking API Key](https://docs.openviking.net/agents/image/trae/01-api-key.jpg)
---
@@ -44,21 +44,21 @@
在 Trae 主界面右上角点击 **设置(齿轮图标)**,进入设置面板。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=ZjI2NTRmZGYzZWZlM2QxOWFlNGQzNzRlM2UzMWY5YmZfZTMzMWRhMDdiN2MwNmVmNzU0OWQ5MTQ3YTk2YmUwMGRfSUQ6NzY0NDUxMTk4NjYyNjAwNTk0OF8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![打开 Trae 设置](https://docs.openviking.net/agents/image/trae/02-open-settings.jpg)
### 步骤 2 · 进入 MCP 配置页
在左侧菜单中选择 **MCP**,进入 MCP Servers 管理页。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MDk3NGYwN2ZhNWU3NTg1ZTI3ZWMyYzMyZTlhZDkwNDJfMDgyZGQwNWMzMjkyN2Y0NmU3OTU2ZTJmMGRkZmI4YmJfSUQ6NzY0NDUxMjA1Njk2NTY5NjQ4MV8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![进入 MCP 配置页](https://docs.openviking.net/agents/image/trae/03-mcp-settings.jpg)
### 步骤 3 · 新增 MCP Server
点击右侧的 **\+ 添加** 按钮,在下拉菜单中选择 **手动配置**。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=YjY4NTg3OGM4MzJkNjE4OGUzNzY2MThiNmI1YjRhNTBfZDU4ZmUwZTU0MzU5OTQ0OWE3ZDNmMzJmODg1NzYyNDJfSUQ6NzY0NDUxMjE2NDcyNDU5MTU0N18xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![添加 MCP Server](https://docs.openviking.net/agents/image/trae/04-add-mcp-server.jpg)
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MjFmMWE0MmY3Njc5MTVmN2E3NjY3ODQ2MWY0YWEyZTRfZGFlMjI3YzU3MTRmYzVhNWI1NGVkYzJiZmY5NGZiMTRfSUQ6NzY0NDU2NTk1NzU2NTk0MjcyNl8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![选择手动配置](https://docs.openviking.net/agents/image/trae/05-manual-config.png)
### 步骤 4 · 粘贴配置 JSON
@@ -79,13 +79,13 @@
**关键说明**:`Authorization` 的值需带上 `Bearer` 前缀(注意空格),完整格式为 `Bearer \<API Key\>`。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=NzVjZmJkNTJmZDZiYTg4YWM0M2RjN2NmMzVjMjA2ZDNfY2MxN2ZkOGI1ZjZiZDFiNWI2YTEzODI2Mzg3ZDNiYmRfSUQ6NzY0NDUxMjE5MzU0NTcwMjU5M18xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![粘贴 MCP JSON 配置](https://docs.openviking.net/agents/image/trae/06-paste-mcp-json.jpg)
### 步骤 5 · 确认并启用
点击 **确认** 按钮,Trae 会自动建立 MCP 连接并加载工具列表。连接成功后,`ov\-mcp\-server` 将出现在已配置的 MCP Servers 列表中。配置完成后,可在 MCP 管理页看到 `ov\-mcp\-server` 已加载并启用,右侧开关呈绿色:
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=Y2Q1MDhiODQxNDZlNjI3ZjU0Yjg0YTMzN2E1ODk3ZDJfYTU0OGIwZTBiMmFlZGRlOWUwNjBmNDYwZDljMmQ2NDNfSUQ6NzY0NDUyNDg4MTkzMzE3NjAxNV8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![确认并启用 MCP Server](https://docs.openviking.net/agents/image/trae/07-enable-server.jpg)
### 步骤 6 · MCP 连通性检查
@@ -93,11 +93,11 @@
**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=OWVmODE5ZDViZTQ4YzQxYmE1NTEwYmMyOWMwMWQ3NTlfNDAwYThmNGJlNzQ3MzQ5YWRkYmE5MTUxZWMwMWJjM2JfSUQ6NzY0NDU2NzQ3Nzc3NDUwMjg2MV8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![运行 ov ls 验证连接](https://docs.openviking.net/agents/image/trae/08-ov-ls.jpg)
**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份。
-![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MmYxYWZkZTNlYjMxMGY1NzZkZjBiNWQ5YmI1OWQ5NjNfZDJjMjdiNTc5ZTE4MWFlZTg0NjAyMzkwOTYyMjkzNGJfSUQ6NzY0NDU2NzQ4ODkxMDc1NzA0Ml8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+![运行 ov health 验证服务状态](https://docs.openviking.net/agents/image/trae/09-ov-health.jpg)
**验收标准**:`ov ls` 能返回 `agent / resources / session / user` 等目录;`ov health` 返回 `service initialized` 与当前用户名,即表示接入成功。
@@ -121,4 +121,4 @@
|连接失败 / 401 Unauthorized|检查 `Authorization` 是否带 `Bearer` 前缀;确认 API Key 未过期或被重置|
|连接失败 / 网络超时<br>|确认网络可访问 `api\.vikingdb\.cn\-beijing\.volces\.com`;企业网络请配置代理白名单|
|Agent 无法识别工具|检查 MCP Server 是否已\&\#34;启用\&\#34;;部分客户端需重启进程后加载新配置|
-|mcp工具因 argument schema 与当前模型不兼容,请切换/修复 mcp server 或切换模型 \(4027\)|![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MDYwNjgxYmY1ZWRjOTZmMDIwNzFjOTFjYjA0ZTljOWZfNTE4MTllMDkxYTNiNDBlYTViYmIyMWExYWI0Y2I2YjBfSUQ6NzY0NDU2NzQwNDg1NjU0NDE5OF8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)<br>![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MGYxMzAwNTM5OGE2ZDExZTU0NmZjZDU3YmRhYjljMjZfMzgwZDhiOTVmMjcwNGM0MTU2ZWYxMzZlNTJmY2RmODNfSUQ6NzY0NDU2NzU2MjU4NzgwMjU4NF8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)<br>尝试切换模型或升级到最新版 Trae|
+|mcp工具因 argument schema 与当前模型不兼容,请切换/修复 mcp server 或切换模型 \(4027\)|![Trae MCP schema 兼容性报错](https://docs.openviking.net/agents/image/trae/10-schema-error.png)<br>![Trae MCP schema 兼容性详情](https://docs.openviking.net/agents/image/trae/11-schema-error-detail.png)<br>尝试切换模型或升级到最新版 Trae|