Skip to content

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

docs(agents): batch update zh setup guides (#2413)

Lilimamamae05216e5dbe1
diff --git a/docs/images/agents/zh/api.md b/docs/images/agents/zh/api.md
index c16d2156f..7f789cd6c 100644
--- a/docs/images/agents/zh/api.md
+++ b/docs/images/agents/zh/api.md
@@ -1,7 +1,5 @@
-## 步骤 1 选择 API Key
-复制页面中展示的 API Key 到你的 Agent 终端
-## 步骤 2 写入资源
+## 步骤 1: 写入资源
参考 GitHub 提供的资源写入示例,自动填入 API Key 和域名
```python
@@ -60,7 +58,7 @@ result = post_json(
print(json.dumps(result, ensure_ascii=False, indent=2))
```
-## 步骤 3 写入记忆
+## 步骤 2: 写入记忆
参考 GitHub 提供的记忆写入示例,自动填入 API Key 和域名
```python
diff --git a/docs/images/agents/zh/claude-code.md b/docs/images/agents/zh/claude-code.md
index ee1ea6cf1..c6e629ceb 100644
--- a/docs/images/agents/zh/claude-code.md
+++ b/docs/images/agents/zh/claude-code.md
@@ -1,10 +1,9 @@
-# Claude Code 记忆插件
为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 提供跨项目、跨 session 的长期记忆,越用越聪明。安装一次,每次对话自动召回和捕获,模型不需要主动调用任何工具。
源码:[examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
-## 安装
+## 步骤 1:安装
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
@@ -38,7 +37,8 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/e
</details>
-## 验证
+
+## 步骤 2:验证
```bash
type claude # 期望输出:claude is a shell function
@@ -52,6 +52,7 @@ type claude # 期望输出:claude is a shell function
如果插件似乎没在工作,设 `OPENVIKING_DEBUG=1` 看 `~/.openviking/logs/cc-hooks.log`。
+
## 工作原理
插件挂载到 Claude Code 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆,每轮回复后捕获新的对话内容,session 启动时注入用户画像和记忆索引,compact 前和 session 结束时提交待处理的消息,并为每个 subagent 分配隔离的记忆 session。所有写入操作异步执行,不会让你等待。
@@ -76,10 +77,12 @@ type claude # 期望输出:claude is a shell function
</details>
+
## 状态行
插件在 Claude Code 输入框下方渲染 OpenViking 状态:连接健康度、召回数量、捕获进度和 session 状态一目了然。完整段位说明和个性化 recipe 见 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
+
## 故障排查
| 现象 | 原因 | 修复 |
@@ -89,7 +92,8 @@ type claude # 期望输出:claude is a shell function
| MCP 工具连到 `127.0.0.1` 而不是远程 | 缺少函数包装 | 确认 `type claude` 返回 "shell function";见 [手动安装](#安装) |
| 远程认证 401 / 403 | API Key 错误或缺少租户头 | 检查 `OPENVIKING_API_KEY`;多租户还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
-## 参见
+
+## 参考文档
- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆
- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 完整环境变量表、hook 细节、架构图
diff --git a/docs/images/agents/zh/cli.md b/docs/images/agents/zh/cli.md
index bff7c35c9..ae41eba16 100644
--- a/docs/images/agents/zh/cli.md
+++ b/docs/images/agents/zh/cli.md
@@ -1,20 +1,22 @@
-# 命令行接入
+# CLI 命令行接入
面向开发者在本地终端直接安装、配置和使用 OpenViking CLI。
-在终端执行以下命令安装 OpenViking CLI,并进入配置流程:
+# 步骤1:在终端执行以下命令安装 OpenViking CLI,并进入配置流程:
```bash
npm i -g @openviking/cli && ov config
```
-按提示填写 OpenViking 服务地址和 API Key。服务地址可使用:
+
+# 步骤2:按提示填写 OpenViking 服务地址和 API Key。服务地址可使用:
```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```
-配置完成后,可运行以下命令查看 CLI 用法:
+
+# 步骤3:配置完成后,可运行以下命令查看 CLI 用法:
```bash
ov --help
diff --git a/docs/images/agents/zh/codex.md b/docs/images/agents/zh/codex.md
index 4916a9cd9..d403680c7 100644
--- a/docs/images/agents/zh/codex.md
+++ b/docs/images/agents/zh/codex.md
@@ -1,10 +1,9 @@
-# Codex 记忆插件
为 [Codex](https://developers.openai.com/codex) 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回,每轮结束后增量捕获,compaction 前提交给记忆抽取器。插件同时把 Codex 接到 OpenViking 的 `/mcp` 端点,模型可以直接调用 search、store 等工具管理记忆。
源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)
-## 安装
+## 步骤 1:安装
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
@@ -32,7 +31,8 @@ codex # 首次启动进 /hooks 审批一次
</details>
-## 验证
+
+## 步骤 2:验证
```bash
type codex # 期望输出:codex is a shell function
@@ -40,6 +40,7 @@ type codex # 期望输出:codex is a shell function
进入 Codex 后插件会在每次输入前召回记忆。设 `OPENVIKING_DEBUG=1` 可把事件写到 `~/.openviking/logs/codex-hooks.log`。
+
## 工作原理
插件挂载到 Codex 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆(`UserPromptSubmit`),每轮结束后把新的对话追加到 session(`Stop`),compaction 前补齐并 commit 完整 transcript(`PreCompact`)让记忆抽取器跑在完整上下文上。新 session 启动时还会清理前次运行的孤儿 session。
@@ -63,6 +64,7 @@ type codex # 期望输出:codex is a shell function
</details>
+
## 故障排查
| 现象 | 原因 | 修复 |
@@ -73,7 +75,8 @@ type codex # 期望输出:codex is a shell function
| 召回为空 | 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| Hook 401 但 MCP 可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次重读 ovcli.conf,MCP 在启动时读 env。改完重启 codex。 |
-## 参见
+
+## 参考文档
- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆
- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、架构图
diff --git a/docs/images/agents/zh/cursor.md b/docs/images/agents/zh/cursor.md
index a19a2c13c..4534dc078 100644
--- a/docs/images/agents/zh/cursor.md
+++ b/docs/images/agents/zh/cursor.md
@@ -1,10 +1,9 @@
-# Cursor MCP 接入
-# 一、前置准备:获取 API Key
+## 一、前置准备:获取 API Key
所有 MCP 客户端的接入都依赖同一个 **Authorization Token**,即 OpenViking 控制台中的 API Key。请先按以下步骤获取并妥善保存。
-## 1\.1 操作路径
+### 1\.1 操作路径
1. 在左侧菜单选择 **用户管理**
@@ -18,19 +17,19 @@
-# 二、Cursor 接入指南
+## 二、接入 Cursor 指南
以下为 OpenViking 标准接入 Cursor 的流程。
-## 2\.1 接入步骤
+### 2\.1 接入步骤
-### 步骤 1 · 打开设置
+#### 步骤 1:打开设置
在 Cursor 主界面右上角点击 **设置(齿轮图标)**,进入设置面板
![打开 Cursor 设置](https://docs.openviking.net/agents/image/cursor/02-open-settings.png)
-### 步骤 2 · 新增 MCP Server
+#### 步骤 2:新增 MCP Server
在左侧菜单中选择 **Tools \&amp; MCPs**,进入 MCP Servers 管理页。
@@ -44,7 +43,7 @@
-### 步骤 3 · 粘贴配置 JSON
+#### 步骤 3:粘贴配置 JSON
在弹出的 **mcp\.json** 文件中粘贴以下 JSON,并将 `Authorization` 替换为第一章中复制的 API Key:
@@ -65,13 +64,13 @@
![粘贴 MCP JSON 配置](https://docs.openviking.net/agents/image/cursor/05-paste-mcp-json.jpg)
-### 步骤 4 · 确认并启用
+#### 步骤 4:确认并启用
保存 mcp\.json 配置文件并关闭后,Cursor 会自动建立 MCP 连接并加载工具列表。连接成功后,**`ov\-mcp\-server`** 会出现在 **Installed MCP Servers** 列表中,同时会显示已启用的工具数量(图中的 “10 tools enabled”)。配置完成后,可直接看到 `ov\-mcp\-server` 条目旁的开关呈绿色开启状态,代表服务已正常加载并就绪:
![确认并启用 MCP Server](https://docs.openviking.net/agents/image/cursor/06-enable-server.png)
-### 步骤 5 · MCP 连通性检查
+#### 步骤 5:MCP 连通性检查
接入后建议通过两个简单 query 快速验证 MCP 是否正常工作。在 Cursor 对话框中依次输入:
@@ -87,7 +86,7 @@
-## 2\.2 配置参数说明
+### 2\.2 配置参数说明
|字段|必填|说明|
|---|---|---|
@@ -98,7 +97,7 @@
---
-# 三、常见问题(FAQ)
+## 三、常见问题(FAQ)
|问题|解决建议|
|---|---|
diff --git a/docs/images/agents/zh/openclaw.md b/docs/images/agents/zh/openclaw.md
index 97b1db38f..358aef618 100644
--- a/docs/images/agents/zh/openclaw.md
+++ b/docs/images/agents/zh/openclaw.md
@@ -1,17 +1,17 @@
-## 步骤 1 安装 OpenViking
+## 步骤 1:安装 OpenViking
在你的 OpenClaw 的机器终端,执行以下命令以安装 OpenViking Plugin
```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup
```
-## 步骤 2 输入以下信息
+## 步骤 2:输入以下信息
执行安装命令后会依次提示输入以下信息,可复制后粘贴到你的 Agent 终端
- Base URL: `https://api.vikingdb.cn-beijing.volces.com/openviking`
- API Key: 复制页面中展示的 API Key 到你的 Agent 终端
-## 步骤 3 重启 OpenClaw
+## 步骤 3:重启 OpenClaw
复制以下指令到 Agent 终端以重启 OpenClaw,重启后控制台将自动判断 Agent 接入状态
```bash
diff --git a/docs/images/agents/zh/opencode.md b/docs/images/agents/zh/opencode.md
index f8b512981..d8f117cd1 100644
--- a/docs/images/agents/zh/opencode.md
+++ b/docs/images/agents/zh/opencode.md
@@ -1,15 +1,14 @@
-# OpenCode 插件
OpenCode 有两个设计路径不同的插件变体,请按你的使用方式自行选择。
-## `opencode-memory-plugin` — 显式工具版本
+## 方式 1:`opencode-memory-plugin` — 显式工具版本
源码:[examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)
通过 OpenCode 的工具机制把 OpenViking 记忆暴露为显式工具。模型决定何时调用,数据按需获取。
-## `opencode/plugin` — 上下文注入版本
+## 方式 2:`opencode/plugin` — 上下文注入版本
源码:[examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)
-把已索引的代码仓库注入 OpenCode 上下文,并按需自动启动 OpenViking 服务器。
\ No newline at end of file
+把已索引的代码仓库注入 OpenCode 上下文,并按需自动启动 OpenViking 服务器。
diff --git a/docs/images/agents/zh/sdk.md b/docs/images/agents/zh/sdk.md
index b85e1e5f4..42b3598ea 100644
--- a/docs/images/agents/zh/sdk.md
+++ b/docs/images/agents/zh/sdk.md
@@ -24,10 +24,8 @@ client = SyncHTTPClient(
client.initialize()
```
-## 步骤 3 选择 API Key
-复制页面中展示的 API Key 到你的 Agent 终端
-## 步骤 4 写入资源
+## 步骤 3:写入资源
参考 GitHub 提供的规范写入示例,自动填入 API Key 和域名
```python
@@ -43,7 +41,7 @@ client.add_resource(
)
```
-## 步骤 5 写入记忆
+## 步骤 4:写入记忆
参考 GitHub 提供的记忆写入示例,自动填入 API Key 和域名
```python
diff --git a/docs/images/agents/zh/trae.md b/docs/images/agents/zh/trae.md
index 0471ee389..659f1a077 100644
--- a/docs/images/agents/zh/trae.md
+++ b/docs/images/agents/zh/trae.md
@@ -1,6 +1,5 @@
-# Trae MCP 接入
-# 一、适用场景
+## 一、适用场景
使用 OpenViking 实现:
@@ -16,11 +15,9 @@
---
-# 二、前置准备:获取 API Key
+## 二、前置准备:获取 API Key
-所有 MCP 客户端的接入都依赖同一个 **Authorization Token**,即 OpenViking 控制台中的 API Key。请先按以下步骤获取并妥善保存。
-
-## 2\.1 操作路径
+所有 MCP 客户端的接入都依赖同一个 **Authorization Token**,即 OpenViking 控制台中的 API Key。请先按以下步骤获取并妥善保存:
1. 在左侧菜单选择 **用户管理**
@@ -34,25 +31,25 @@
---
-# 三、Trae 接入指南
+## 三、Trae 接入指南
**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。以下为 OpenViking 的标准接入流程。
-## 3\.1 接入步骤
+### 3\.1 接入步骤
-### 步骤 1 · 打开设置
+#### 步骤 1:打开设置
在 Trae 主界面右上角点击 **设置(齿轮图标)**,进入设置面板。
![打开 Trae 设置](https://docs.openviking.net/agents/image/trae/02-open-settings.jpg)
-### 步骤 2 · 进入 MCP 配置页
+#### 步骤 2:进入 MCP 配置页
在左侧菜单中选择 **MCP**,进入 MCP Servers 管理页。
![进入 MCP 配置页](https://docs.openviking.net/agents/image/trae/03-mcp-settings.jpg)
-### 步骤 3 · 新增 MCP Server
+#### 步骤 3:新增 MCP Server
点击右侧的 **\+ 添加** 按钮,在下拉菜单中选择 **手动配置**。
@@ -60,7 +57,7 @@
![选择手动配置](https://docs.openviking.net/agents/image/trae/05-manual-config.png)
-### 步骤 4 · 粘贴配置 JSON
+#### 步骤 4:粘贴配置 JSON
在弹出的配置框中粘贴以下 JSON,并将 `Authorization` 替换为第二章中复制的 API Key:
@@ -81,13 +78,13 @@
![粘贴 MCP JSON 配置](https://docs.openviking.net/agents/image/trae/06-paste-mcp-json.jpg)
-### 步骤 5 · 确认并启用
+#### 步骤 5:确认并启用
点击 **确认** 按钮,Trae 会自动建立 MCP 连接并加载工具列表。连接成功后,`ov\-mcp\-server` 将出现在已配置的 MCP Servers 列表中。配置完成后,可在 MCP 管理页看到 `ov\-mcp\-server` 已加载并启用,右侧开关呈绿色:
![确认并启用 MCP Server](https://docs.openviking.net/agents/image/trae/07-enable-server.jpg)
-### 步骤 6 · MCP 连通性检查
+#### 步骤 6:MCP 连通性检查
接入后建议通过两个简单 query 快速验证 MCP 是否正常工作。在 Trae 对话框中依次输入:
@@ -103,7 +100,7 @@
-## 3\.2 配置参数说明
+### 3\.2 配置参数说明
|字段|必填|说明|
|---|---|---|
@@ -114,7 +111,7 @@
---
-# 四、常见问题(FAQ)
+## 四、常见问题(FAQ)
|问题|解决建议|
|---|---|