Skip to content

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

docs: add agent integration assets (#2306)

yufeng18897e46d272
diff --git a/.github/workflows/docs-tos.yml b/.github/workflows/docs-tos.yml
index 0cd1821ec..868ffba4e 100644
--- a/.github/workflows/docs-tos.yml
+++ b/.github/workflows/docs-tos.yml
@@ -97,6 +97,7 @@ jobs:
DIST_DIR="docs/.vitepress/dist"
HTML_CACHE_CONTROL="public, max-age=0, must-revalidate"
STATIC_CACHE_CONTROL="public, max-age=31536000, immutable"
+ NO_CACHE_CONTROL="no-store, no-cache, must-revalidate, max-age=0"
aws s3 cp "${DIST_DIR}" "s3://${TOS_BUCKET}/" \
--endpoint-url "https://${TOS_S3_ENDPOINT}" \
@@ -126,6 +127,14 @@ jobs:
--cache-control "${STATIC_CACHE_CONTROL}" \
--only-show-errors
+ if [ -d "${DIST_DIR}/agents" ]; then
+ aws s3 cp "${DIST_DIR}/agents" "s3://${TOS_BUCKET}/agents/" \
+ --endpoint-url "https://${TOS_S3_ENDPOINT}" \
+ --recursive \
+ --cache-control "${NO_CACHE_CONTROL}" \
+ --only-show-errors
+ fi
+
- name: Report TOS deployment failure
if: steps.setup_python.outcome == 'failure' || steps.install_aws_cli.outcome == 'failure' || steps.upload_tos.outcome == 'failure'
run: |
diff --git a/docs/images/agents/claude-code.md b/docs/images/agents/claude-code.md
new file mode 100644
index 000000000..ee1ea6cf1
--- /dev/null
+++ b/docs/images/agents/claude-code.md
@@ -0,0 +1,98 @@
+# 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/)
+
+## 安装
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
+```
+
+脚本会检查依赖、配置 OpenViking 连接并安装插件。每一步都是幂等的——重复执行安全。
+
+安装完成后启动 Claude Code,问它上次 session 聊过什么——它记得。
+
+<details>
+<summary><b>手动安装</b></summary>
+
+如果你更喜欢手动操作:
+
+1. **Shell 函数包装** — 在 `~/.zshrc` 或 `~/.bashrc` 末尾追加一个 `claude()` 函数,每次调用时从 `~/.openviking/ovcli.conf` 注入 `OPENVIKING_URL` 和 `OPENVIKING_API_KEY`。这样 API Key 只在 `claude` 进程树内有效。完整函数和安全说明见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf)。
+
+2. **安装插件**,在 OpenViking 仓库根目录:
+
+ ```bash
+ claude plugin marketplace add "$(pwd)/examples"
+ claude plugin install claude-code-memory-plugin@openviking-plugins-local
+ ```
+
+3. **启动 Claude Code**,执行 `/mcp` 确认 OpenViking 这一项显示的是你的服务器 URL。
+
+> 还没有 `ovcli.conf`?先按 [部署指南 → CLI](../guides/03-deployment.md#cli) 创建。
+>
+> 纯本地模式(`http://127.0.0.1:1933`,无鉴权)?跳过第 1 步——插件会静默使用本地默认值。
+>
+> Claude Code < 2.0?见 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。
+
+</details>
+
+## 验证
+
+```bash
+type claude # 期望输出:claude is a shell function
+```
+
+进入 Claude Code 后:
+
+- `/plugins` → 在 Installed 中找到 **openviking-memory**(下属 **openviking** MCP 应显示已连接)
+- `/mcp` → OpenViking 这一项应显示你的服务器 URL 和有效认证
+- `/openviking-memory:ov` → 展示服务器状态、身份、召回/注入统计和开关状态
+
+如果插件似乎没在工作,设 `OPENVIKING_DEBUG=1` 看 `~/.openviking/logs/cc-hooks.log`。
+
+## 工作原理
+
+插件挂载到 Claude Code 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆,每轮回复后捕获新的对话内容,session 启动时注入用户画像和记忆索引,compact 前和 session 结束时提交待处理的消息,并为每个 subagent 分配隔离的记忆 session。所有写入操作异步执行,不会让你等待。
+
+<details>
+<summary><b>配置</b></summary>
+
+配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动召回 |
+| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮最多注入的记忆条数 |
+| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联内容的 token 预算 |
+| `OPENVIKING_AUTO_CAPTURE` | `true` | 每轮结束后自动捕获 |
+| `OPENVIKING_BYPASS_SESSION` | `false` | 跳过当前 session 的所有 hook |
+| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV glob 模式自动跳过 |
+| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启/关闭 |
+| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/cc-hooks.log` |
+
+多租户场景设置 `OPENVIKING_ACCOUNT`、`OPENVIKING_USER`、`OPENVIKING_AGENT_ID`。完整环境变量列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。
+
+</details>
+
+## 状态行
+
+插件在 Claude Code 输入框下方渲染 OpenViking 状态:连接健康度、召回数量、捕获进度和 session 状态一目了然。完整段位说明和个性化 recipe 见 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。
+
+## 故障排查
+
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| 插件未激活 | 找不到 `ov.conf` / `ovcli.conf` | 跑 [安装脚本](#安装),或设 `OPENVIKING_MEMORY_ENABLED=1` + URL/API_KEY |
+| Hook 触发但召回为空 | 服务器没起来或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| 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 细节、架构图
+- [迁移说明](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/MIGRATION.md) — 从旧版插件升级
+- [MCP 客户端](./06-mcp-clients.md) — MCP 工具参数与其他客户端
+- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置
diff --git a/docs/images/agents/codex.md b/docs/images/agents/codex.md
new file mode 100644
index 000000000..4916a9cd9
--- /dev/null
+++ b/docs/images/agents/codex.md
@@ -0,0 +1,82 @@
+# 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/)
+
+## 安装
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
+```
+
+脚本会检查依赖、配置 OpenViking 连接并注册插件。每一步幂等,反复执行安全。
+
+安装完成后:
+
+```bash
+source ~/.zshrc # 或 ~/.bashrc
+codex # 首次启动进 /hooks 审批一次
+```
+
+<details>
+<summary><b>手动安装</b></summary>
+
+前置:Node.js >= 22、Codex >= 0.130.0、`codex_hooks` feature 已启用。
+
+1. **Shell 函数包装** — 在 shell rc 中追加一个 `codex()` 函数,每次调用时从 ovcli.conf 注入 OpenViking 环境变量。完整函数见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md)。
+
+2. **插件安装** — 注册本地 marketplace 并启用插件。具体命令见 `setup-helper/install.sh`。
+
+3. **占位符渲染** — `.mcp.json` 和 `hooks.json` 中的占位符在拷贝到 Codex 缓存时需替换为绝对值。installer 会自动做。
+
+</details>
+
+## 验证
+
+```bash
+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。
+
+> **已知盲区**:Codex 在 `SIGTERM` / `Ctrl+C` / `/exit` 时不触发任何 hook。孤儿 session 由下一次 `SessionStart` 的闲置 TTL 清理(30 分钟)或活动窗口启发式回收。
+
+<details>
+<summary><b>配置</b></summary>
+
+配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |
+| `OPENVIKING_API_KEY` | — | API key(通过 `Authorization: Bearer` 发送) |
+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart 活动窗口阈值 |
+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |
+| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/codex-hooks.log` |
+
+调参(`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 等)见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。
+
+</details>
+
+## 故障排查
+
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| `MCP server is not logged in` | 启动时 `OPENVIKING_API_KEY` 不在 env 里 | 确认 `codex()` 函数已 source,`ovcli.conf` 有 `api_key` |
+| `4 hooks need review` | 首次启动的安全审批 | 在 Codex 输入 `/hooks` 审批 |
+| 审批后仍 `hook (failed) exited with code 1` | 缓存里占位符未渲染 | 重新跑一次一行安装脚本 |
+| 召回为空 | 服务器不可达或 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) — 完整环境变量、架构图
+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树
+- [MCP 客户端](./06-mcp-clients.md) — MCP 协议、工具列表、其他客户端
+- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置
diff --git a/docs/images/agents/hermes.md b/docs/images/agents/hermes.md
new file mode 100644
index 000000000..10b9079f0
--- /dev/null
+++ b/docs/images/agents/hermes.md
@@ -0,0 +1,33 @@
+# Hermes Agent
+
+[Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research) 内置 OpenViking 记忆提供方。无需安装插件——把 Hermes 指向你的 OpenViking 服务即可,记忆存储、召回和抽取均原生支持。
+
+## 配置
+
+运行 Hermes 记忆配置向导:
+
+```bash
+hermes memory setup
+```
+
+向导会询问:
+
+- **OpenViking 服务 URL** — 自托管服务器(默认 `http://127.0.0.1:1933`)或火山引擎 OpenViking Cloud
+- **API Key** — 本地开发模式留空
+- **租户 account / user / agent ID** — 多租户部署时使用
+
+配置保存在 Hermes 的 `config.yaml` 和 `.env` 文件中。
+
+## 验证
+
+```bash
+hermes memory status
+```
+
+配置完成后,Hermes 自动使用 OpenViking 作为长期记忆——`viking_remember`、`viking_recall` 等记忆工具即刻可用。
+
+## 参见
+
+- [Hermes — OpenViking memory provider 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 完整配置指南
+- [部署指南](../guides/03-deployment.md) — 搭建 OpenViking 服务
+- [鉴权](../guides/04-authentication.md) — 远程访问的 API Key 设置
diff --git a/docs/images/agents/index.json b/docs/images/agents/index.json
new file mode 100644
index 000000000..7fe7a7d30
--- /dev/null
+++ b/docs/images/agents/index.json
@@ -0,0 +1,63 @@
+{
+ "version": 1,
+ "updatedAt": "2026-05-29",
+ "cdnBaseUrl": "https://docs.openviking.net/",
+ "agents": [
+ {
+ "id": "openclaw",
+ "name": "OpenClaw",
+ "tags": ["Plugin"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/OpenClaw.png",
+ "summary": "Plugin 接入,作为 OpenClaw 的 context engine,支持多 Agent 跨会话记忆与自迭代,通过 npm 安装助手工具一键完成配置",
+ "detailPath": "https://docs.openviking.net/agents/openclaw.md"
+ },
+ {
+ "id": "hermes",
+ "name": "Hermes",
+ "tags": ["Provider"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",
+ "summary": "Hermes 官方内置 OpenViking 作为记忆提供方。无需安装插件——直接把 Hermes 指向你的 OpenViking 服务即可,记忆存储、召回和抽取均原生支持",
+ "detailPath": "https://docs.openviking.net/agents/hermes.md"
+ },
+ {
+ "id": "claude-code",
+ "name": "Claude Code",
+ "tags": ["Plugin"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Claude-Code.png",
+ "summary": "为 Claude Code 提供跨项目、跨 session 的长期记忆,越用越聪明。安装一次,每次对话自动召回和捕获,模型不需要主动调用任何工具",
+ "detailPath": "https://docs.openviking.net/agents/claude-code.md"
+ },
+ {
+ "id": "codex",
+ "name": "Codex",
+ "tags": ["Plugin"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/codex.png",
+ "summary": "为 Codex 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回,每轮结束后增量捕获,compaction 前提交给记忆抽取器",
+ "detailPath": "https://docs.openviking.net/agents/codex.md"
+ },
+ {
+ "id": "cursor",
+ "name": "Cursor",
+ "tags": ["MCP"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Cursor.png",
+ "summary": "通过 MCP 标准协议接入,为 Codex 提供支撑日常编码 和 Agent 开发场景的上下文管理",
+ "detailPath": null
+ },
+ {
+ "id": "trae",
+ "name": "TRAE",
+ "tags": ["MCP"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Trae.png",
+ "summary": "通过 MCP 标准协议接入,为 TRAE 提供支撑日常编码 和 Agent 开发场景的上下文管理,可以修改规则和命令来保证更稳定的 MCP 工具使用",
+ "detailPath": "https://docs.openviking.net/agents/trae.md"
+ },
+ {
+ "id": "opencode",
+ "name": "Opencode",
+ "tags": ["Plugin"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/OpenCode.png",
+ "summary": "提供两种 OpenCode 插件,可以模型自主选择使用,也可以注入上下文使用",
+ "detailPath": "https://docs.openviking.net/agents/opencode.md"
+ }
+ ]
+}
diff --git a/docs/images/agents/openclaw.md b/docs/images/agents/openclaw.md
new file mode 100644
index 000000000..97b1db38f
--- /dev/null
+++ b/docs/images/agents/openclaw.md
@@ -0,0 +1,19 @@
+## 步骤 1 安装 OpenViking
+在你的 OpenClaw 的机器终端,执行以下命令以安装 OpenViking Plugin
+
+```bash
+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 接入状态
+
+```bash
+openclaw gateway restart
+```
diff --git a/docs/images/agents/opencode.md b/docs/images/agents/opencode.md
new file mode 100644
index 000000000..f8b512981
--- /dev/null
+++ b/docs/images/agents/opencode.md
@@ -0,0 +1,15 @@
+# OpenCode 插件
+
+OpenCode 有两个设计路径不同的插件变体,请按你的使用方式自行选择。
+
+## `opencode-memory-plugin` — 显式工具版本
+
+源码:[examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)
+
+通过 OpenCode 的工具机制把 OpenViking 记忆暴露为显式工具。模型决定何时调用,数据按需获取。
+
+## `opencode/plugin` — 上下文注入版本
+
+源码:[examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)
+
+把已索引的代码仓库注入 OpenCode 上下文,并按需自动启动 OpenViking 服务器。
\ No newline at end of file
diff --git a/docs/images/agents/trae.md b/docs/images/agents/trae.md
new file mode 100644
index 000000000..63be76e22
--- /dev/null
+++ b/docs/images/agents/trae.md
@@ -0,0 +1,128 @@
+# Trae MCP 接入
+
+# 一、适用场景
+
+使用 OpenViking 实现:
+
+- 跨会话记住技术栈偏好(语言版本、框架、依赖管理工具、构建系统)
+
+- 沉淀编码风格偏好(命名约定、注释风格、是否写单测、TDD/BDD 习惯)
+
+- 记住常用工程上下文(monorepo 结构、构建命令、部署流程、环境差异)
+
+- 记忆历史决策与\&\#34;踩坑笔记\&\#34;(为什么不用 X、上次用 Y 出过什么问题)
+
+- 个人长期任务目标 / OKR / Roadmap 沉淀,Agent 在规划任务时自动对齐
+
+---
+
+# 二、前置准备:获取 API Key
+
+所有 MCP 客户端的接入都依赖同一个 **Authorization Token**,即 OpenViking 控制台中的 API Key。请先按以下步骤获取并妥善保存。
+
+## 2\.1 操作路径
+
+1. 在左侧菜单选择 **用户管理**
+
+2. 在用户列表中找到对应用户(个人版默认为 `default` / `admin`),点击 API Key 列右侧的 **复制** 图标
+
+3. 将复制得到的 `ZGV\.\.\.hiMg` 形式的字符串妥善保存,作为后续所有 Agent 接入的 `Authorization` 值
+
+**安全提示**:API Key 等同于账户密钥,请勿提交到 Git 仓库或公开渠道。建议通过环境变量或加密配置注入。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MTNkMDA0ZDBhZGRmODlkNmNjMGRiMGEwZTIyMzZlNThfMmNkMmZlZjA1ZWJjNTAyMGMzODFiNmRiZDk2ZTU3ZDhfSUQ6NzY0NDUxMTgwNDM5NjI3NjkzNl8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+---
+
+# 三、Trae 接入指南
+
+**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。以下为 OpenViking 的标准接入流程。
+
+## 3\.1 接入步骤
+
+### 步骤 1 · 打开设置
+
+在 Trae 主界面右上角点击 **设置(齿轮图标)**,进入设置面板。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=ZjI2NTRmZGYzZWZlM2QxOWFlNGQzNzRlM2UzMWY5YmZfZTMzMWRhMDdiN2MwNmVmNzU0OWQ5MTQ3YTk2YmUwMGRfSUQ6NzY0NDUxMTk4NjYyNjAwNTk0OF8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+### 步骤 2 · 进入 MCP 配置页
+
+在左侧菜单中选择 **MCP**,进入 MCP Servers 管理页。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MDk3NGYwN2ZhNWU3NTg1ZTI3ZWMyYzMyZTlhZDkwNDJfMDgyZGQwNWMzMjkyN2Y0NmU3OTU2ZTJmMGRkZmI4YmJfSUQ6NzY0NDUxMjA1Njk2NTY5NjQ4MV8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+### 步骤 3 · 新增 MCP Server
+
+点击右侧的 **\+ 添加** 按钮,在下拉菜单中选择 **手动配置**。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=YjY4NTg3OGM4MzJkNjE4OGUzNzY2MThiNmI1YjRhNTBfZDU4ZmUwZTU0MzU5OTQ0OWE3ZDNmMzJmODg1NzYyNDJfSUQ6NzY0NDUxMjE2NDcyNDU5MTU0N18xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MjFmMWE0MmY3Njc5MTVmN2E3NjY3ODQ2MWY0YWEyZTRfZGFlMjI3YzU3MTRmYzVhNWI1NGVkYzJiZmY5NGZiMTRfSUQ6NzY0NDU2NTk1NzU2NTk0MjcyNl8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+### 步骤 4 · 粘贴配置 JSON
+
+在弹出的配置框中粘贴以下 JSON,并将 `Authorization` 替换为第二章中复制的 API Key:
+
+```json
+{
+ "mcpServers": {
+ "ov-mcp-server": {
+ "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
+ "headers": {
+ "Authorization": "Bearer ZGVmYXV********YzdlZjhiMg"
+ }
+ }
+ }
+}
+```
+
+**关键说明**:`Authorization` 的值需带上 `Bearer` 前缀(注意空格),完整格式为 `Bearer \&lt;API Key\&gt;`。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=NzVjZmJkNTJmZDZiYTg4YWM0M2RjN2NmMzVjMjA2ZDNfY2MxN2ZkOGI1ZjZiZDFiNWI2YTEzODI2Mzg3ZDNiYmRfSUQ6NzY0NDUxMjE5MzU0NTcwMjU5M18xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+### 步骤 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)
+
+### 步骤 6 · MCP 连通性检查
+
+接入后建议通过两个简单 query 快速验证 MCP 是否正常工作。在 Trae 对话框中依次输入:
+
+**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=OWVmODE5ZDViZTQ4YzQxYmE1NTEwYmMyOWMwMWQ3NTlfNDAwYThmNGJlNzQ3MzQ5YWRkYmE5MTUxZWMwMWJjM2JfSUQ6NzY0NDU2NzQ3Nzc3NDUwMjg2MV8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份。
+
+![Image](https://internal-api-drive-stream.larkoffice.com/space/api/box/stream/download/authcode/?code=MmYxYWZkZTNlYjMxMGY1NzZkZjBiNWQ5YmI1OWQ5NjNfZDJjMjdiNTc5ZTE4MWFlZTg0NjAyMzkwOTYyMjkzNGJfSUQ6NzY0NDU2NzQ4ODkxMDc1NzA0Ml8xNzgwMDM5ODY4OjE3ODAxMjYyNjhfVjM)
+
+**验收标准**:`ov ls` 能返回 `agent / resources / session / user` 等目录;`ov health` 返回 `service initialized` 与当前用户名,即表示接入成功。
+
+
+
+## 3\.2 配置参数说明
+
+|字段|必填|说明|
+|---|---|---|
+|`mcpServers`|是|MCP Server 配置根节点|
+|`ov\-mcp\-server`|是|服务别名,可自定义;建议保持与上下文识别一致|
+|`url`|是|OpenViking MCP 服务端点;CN 区固定为 `https://api\.vikingdb\.cn\-beijing\.volces\.com/openviking/mcp`|
+|`headers\.Authorization`|是|格式 `Bearer \&lt;API Key\&gt;`,来源见第二章|
+
+---
+
+# 四、常见问题(FAQ)
+
+|问题|解决建议|
+|---|---|
+|连接失败 / 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|
+
+
+
+> (注:内容由 AI 生成,请谨慎参考)