Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add agent integration assets (#2306)
yufeng18897e46d272
diff --git a/.github/workflows/docs-tos.yml b/.github/workflows/docs-tos.ymlindex 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 failureif: 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 filediff --git a/docs/images/agents/trae.md b/docs/images/agents/trae.mdnew file mode 100644index 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 仓库或公开渠道。建议通过环境变量或加密配置注入。++++---++# 三、Trae 接入指南++**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。以下为 OpenViking 的标准接入流程。++## 3\.1 接入步骤++### 步骤 1 · 打开设置++在 Trae 主界面右上角点击 **设置(齿轮图标)**,进入设置面板。++++### 步骤 2 · 进入 MCP 配置页++在左侧菜单中选择 **MCP**,进入 MCP Servers 管理页。++++### 步骤 3 · 新增 MCP Server++点击右侧的 **\+ 添加** 按钮,在下拉菜单中选择 **手动配置**。++++++### 步骤 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 \<API Key\>`。++++### 步骤 5 · 确认并启用++点击 **确认** 按钮,Trae 会自动建立 MCP 连接并加载工具列表。连接成功后,`ov\-mcp\-server` 将出现在已配置的 MCP Servers 列表中。配置完成后,可在 MCP 管理页看到 `ov\-mcp\-server` 已加载并启用,右侧开关呈绿色:++++### 步骤 6 · MCP 连通性检查++接入后建议通过两个简单 query 快速验证 MCP 是否正常工作。在 Trae 对话框中依次输入:++**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构。++++**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份。++++**验收标准**:`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 \<API Key\>`,来源见第二章|++---++# 四、常见问题(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\)|<br><br>尝试切换模型或升级到最新版 Trae|++++> (注:内容由 AI 生成,请谨慎参考)