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(agents): sync en agent guides with current zh docs (#2423)
Lilimamamafe4dfa0bcea5
diff --git a/docs/images/agents/en/api.md b/docs/images/agents/en/api.mdindex 8ac426e83..55a272aab 100644--- a/docs/images/agents/en/api.md+++ b/docs/images/agents/en/api.md@@ -1,12 +1,6 @@-# API Integration+## Step 1: Add a resource-## Step 1: Choose an API Key--Copy the API Key shown in the OpenViking console and pass it to your agent environment.--## Step 2: Add a resource--Use the REST API to upload a local file and create a resource:+Refer to the resource write example from GitHub and fill in the API Key and domain automatically:```pythonimport json@@ -15,12 +9,13 @@ from pathlib import Pathimport requestsurl = "https://api.vikingdb.cn-beijing.volces.com/openviking"-api_key = "<your-api-key>"-agent_id = "<your-agent-id>"-file_path = Path("<your-file-path>")-resource_to = "viking://resources/test.txt"-reason = "External API documentation"+api_key = "[TODO]your-api-key"+agent_id = "[TODO]your-agent-id"+file_path = Path("[TODO]your-file-path") # e.g. test.txt+resource_to = "[TODO]your-resource-path" # e.g. viking://resources/test.txt+reason = "[TODO]your-reason" # e.g. External API documentation+# 1. Initialize request headers.headers = {"Content-Type": "application/json","Authorization": "Bearer " + api_key,@@ -32,6 +27,7 @@ def post_json(path: str, payload: dict, timeout: float):response.raise_for_status()return response.json()+# 2. Upload the local file to a temporary resource.with file_path.open("rb") as file:result = requests.post(f"{url}/api/v1/resources/temp_upload",@@ -43,8 +39,11 @@ with file_path.open("rb") as file:timeout=120.0,)result.raise_for_status()-temp_file_id = result.json()["result"]["temp_file_id"]+result = result.json()+print(json.dumps(result, ensure_ascii=False, indent=2))+temp_file_id = result["result"]["temp_file_id"]+# 3. Create a resource from the temporary file.result = post_json("/api/v1/resources",{@@ -58,16 +57,23 @@ result = post_json(print(json.dumps(result, ensure_ascii=False, indent=2))```-## Step 3: Add memory+## Step 2: Add memory-Create a session, add a message, and commit the session:+Refer to the memory write example from GitHub and fill in the API Key and domain automatically:```python-text = "I am a developer"+text = "[TODO]your-message-text" # e.g. I am a developer++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()+# Create a session.session = post_json("/api/v1/sessions", {}, 360.0)session_id = session["result"]["session_id"]+# Add a message.post_json(f"/api/v1/sessions/{session_id}/messages",{@@ -77,6 +83,7 @@ post_json(360.0,)+# Commit the session.result = post_json(f"/api/v1/sessions/{session_id}/commit",{"telemetry": False},diff --git a/docs/images/agents/en/claude-code.md b/docs/images/agents/en/claude-code.mdindex b13de1639..cf660661b 100644--- a/docs/images/agents/en/claude-code.md+++ b/docs/images/agents/en/claude-code.md@@ -1,10 +1,8 @@-# Claude Code Memory Plugin-Add cross-project, cross-session long-term memory to [Claude Code](https://docs.claude.com/en/docs/claude-code/overview). Install once; every conversation automatically recalls and captures memory, and the model does not need to call any tools manually.Source: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [Blog: motivation and demo](https://blog.openviking.ai/post/openviking-coding-agent/)-## Install+## Step 1: Install```bashbash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)@@ -38,7 +36,7 @@ If you prefer to install manually:</details>-## Verify+## Step 2: Verify```bashtype claude # Expected: claude is a shell function@@ -89,7 +87,7 @@ The plugin renders OpenViking status below the Claude Code input box: connection| MCP tools connect to `127.0.0.1` instead of remote | Missing shell function wrapper | Confirm `type claude` returns "shell function"; see [Manual installation](#install) || Remote auth returns 401 / 403 | API key is wrong or tenant headers are missing | Check `OPENVIKING_API_KEY`; for multi-tenant deployments also verify `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |-## See also+## Reference docs- [Blog: OpenViking for Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) - Why and how to add long-term memory to your coding agent- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) - Full environment variable table, hook details, and architecture diagramdiff --git a/docs/images/agents/en/cli.md b/docs/images/agents/en/cli.mdindex b17f33150..e728a2f36 100644--- a/docs/images/agents/en/cli.md+++ b/docs/images/agents/en/cli.md@@ -1,20 +1,18 @@-# Command Line Integration-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:+### Step 1: Run the following command in your terminal to install OpenViking CLI and enter the configuration flow:```bashnpm i -g @openviking/cli && ov config```-Use this service URL when prompted:+### Step 2: When prompted, enter the OpenViking service URL and API Key. You can use the following service URL:```texthttps://api.vikingdb.cn-beijing.volces.com/openviking```-After configuration, inspect CLI usage with:+### Step 3: After configuration, run the following command to view CLI usage:```bashov --helpdiff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.mdindex be3dff166..7213f38da 100644--- a/docs/images/agents/en/codex.md+++ b/docs/images/agents/en/codex.md@@ -1,10 +1,8 @@-# Codex Memory Plugin-Add persistent cross-session memory to [Codex](https://developers.openai.com/codex). Install once: the plugin automatically recalls memory before every user prompt, captures updates after each turn, and commits before compaction. It also connects Codex to OpenViking's `/mcp` endpoint so the model can directly call tools such as search and store.Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: motivation and demo](https://blog.openviking.ai/post/openviking-coding-agent/)-## Install+## Step 1: Install```bashbash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)@@ -32,7 +30,7 @@ Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `codex_hooks` feature en</details>-## Verify+## Step 2: Verify```bashtype codex # Expected: codex is a shell function@@ -73,7 +71,7 @@ For tuning options such as `OPENVIKING_RECALL_LIMIT` and `OPENVIKING_CAPTURE_ASS| Recall is empty | Server is unreachable or URL is wrong | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` || Hooks get 401 while MCP works, or vice versa | Environment and `ovcli.conf` differ | Hooks reread `ovcli.conf` each time; MCP reads env at startup. Restart Codex after changes. |-## See also+## Reference docs- [Blog: OpenViking for Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) - Why and how to add long-term memory to your coding agent- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) - Full environment variables and architecture diagramdiff --git a/docs/images/agents/en/cursor.md b/docs/images/agents/en/cursor.mdindex 9c237eeab..295a7eff1 100644--- a/docs/images/agents/en/cursor.md+++ b/docs/images/agents/en/cursor.md@@ -1,34 +1,14 @@-# Cursor MCP Integration+## 1. Cursor Integration Steps for OpenViking-# 1. Prerequisite: Get an API Key+Follow the steps below in Cursor to connect OpenViking:-All MCP clients use the same **Authorization Token**, which is the API Key from the OpenViking console. Get it first and keep it secure.--## 1.1 Where to find it--1. In the left menu, choose **User Management**.--2. Find the target user in the user list. For personal editions, the default user is usually `default` / `admin`. Click the **copy** icon in the API Key column.--3. Save the copied `ZGV...hiMg` string. It will be used as the `Authorization` value for agent integration.--**Security note**: The API Key is equivalent to an account secret. Do not commit it to Git or publish it anywhere. Prefer environment variables or encrypted configuration.----# 2. Cursor Integration Guide--This is the standard OpenViking flow for connecting Cursor.--## 2.1 Integration steps--### Step 1 - Open settings+### Step 1: Open Cursor settingsIn the Cursor main window, click **Settings** in the upper-right corner to open the settings panel.-### Step 2 - Add an MCP Server+### Step 2: Add an MCP ServerIn the left menu, select **Tools & MCPs** to open the MCP Servers page.@@ -38,9 +18,9 @@ Click **Add Custom MCP**.-### Step 3 - Paste the JSON configuration+### Step 3: Paste the JSON configuration-In the opened **mcp.json** file, paste the following JSON and replace `Authorization` with the API Key copied in section 1:+In the opened **mcp.json** file, paste the following JSON. The `Authorization` and other fields are already filled with the API Key value:```json{@@ -55,42 +35,46 @@ In the opened **mcp.json** file, paste the following JSON and replace `Authoriza}```-**Important**: The `Authorization` value must include the `Bearer` prefix and a space. The full format is `Bearer <API Key>`.----### Step 4 - Confirm and enable+### Step 4: Confirm and enableAfter saving and closing `mcp.json`, Cursor automatically connects to the MCP server and loads the tools. When the connection succeeds, **`ov-mcp-server`** appears in the **Installed MCP Servers** list with the enabled tool count, such as "10 tools enabled". The switch next to `ov-mcp-server` should be green, which means the service is loaded and ready.-### Step 5 - Check MCP connectivity+### Step 5: Check MCP connectivity-After connecting, run two simple queries in Cursor to verify the MCP server:+After connecting, it is recommended to run two simple queries to verify the MCP server:-**1.** **`ov ls`** - List OpenViking root directories and confirm the connection returns the expected structure.+**1.** **`ov ls`** - List the OpenViking root directories to confirm the connection is available and the directory structure is returned correctly:++```bash+ov ls+```-**2.** **`ov health`** - Call the health tool to confirm server status and current identity.+**2.** **`ov health`** - Call the health tool to confirm the OpenViking service status and current identity:++```bash+ov health+```-**Acceptance criteria**: `ov ls` returns directories such as `agent / resources / session / user`; `ov health` returns `service initialized` and the current username.+### Step 6: Acceptance criteria-## 2.2 Configuration fields+`ov ls` returns directories such as `agent / resources / session / user`; `ov health` returns `service initialized` and the current username. This means the integration succeeded.++## 2. Configuration fields| Field | Required | Description ||---|---|---|| `mcpServers` | Yes | Root node for MCP server configuration || `ov-mcp-server` | Yes | Service alias. It can be customized, but keeping this name helps contextual recognition || `url` | Yes | OpenViking MCP endpoint. For CN, use `https://api.vikingdb.cn-beijing.volces.com/openviking/mcp` |-| `headers.Authorization` | Yes | Format: `Bearer <API Key>`. Source: section 1 |-----+| `headers.Authorization` | Yes | Format: `Bearer <API Key>`. Filled in during the steps above |-# 3. FAQ+## 3. FAQ| Problem | Suggested fix ||---|---|diff --git a/docs/images/agents/en/hermes.md b/docs/images/agents/en/hermes.mdindex 89fe28fa4..a065ec639 100644--- a/docs/images/agents/en/hermes.md+++ b/docs/images/agents/en/hermes.md@@ -1,10 +1,6 @@-# Hermes Agent-[Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research) includes OpenViking as a built-in memory provider. No plugin installation is required. Point Hermes to your OpenViking service to enable native memory storage, recall, and extraction.-## Configure--Run the Hermes memory setup wizard:+## Step 1: Run the Hermes memory setup wizard```bashhermes memory setup@@ -18,7 +14,7 @@ The wizard asks for:The configuration is saved to Hermes `config.yaml` and `.env` files.-## Verify+## Step 2: Verify Hermes memory status```bashhermes memory status@@ -26,7 +22,7 @@ hermes memory statusAfter configuration, Hermes automatically uses OpenViking as long-term memory. Memory tools such as `viking_remember` and `viking_recall` are available immediately.-## See also+## Reference docs- [Hermes - OpenViking memory provider documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) - Full configuration guide- [Deployment Guide](../guides/03-deployment.md) - Set up the OpenViking servicediff --git a/docs/images/agents/en/mcp.md b/docs/images/agents/en/mcp.mdindex 9c4df1864..d7a992c16 100644--- a/docs/images/agents/en/mcp.md+++ b/docs/images/agents/en/mcp.md@@ -1,6 +1,4 @@-# MCP Integration--Step 1 MCP configuration+### Step 1: MCP configuration```json{@@ -15,8 +13,9 @@ Step 1 MCP configuration}```-**Important**: The `Authorization` value must include the `Bearer` prefix and a space. The full format is `Bearer <API Key>`.--Step 2 Test MCP tool connectivity+### Step 2: Test MCP tool connectivityEnter `ov health` to check the OpenViking version and connection status.+```bash+ov health+```diff --git a/docs/images/agents/en/openclaw.md b/docs/images/agents/en/openclaw.mdindex c99cf205f..05f3f105b 100644--- a/docs/images/agents/en/openclaw.md+++ b/docs/images/agents/en/openclaw.md@@ -1,19 +1,22 @@-## Step 1 Install OpenViking+## Step 1: Install OpenViking-On the machine running OpenClaw, run the following command to install the OpenViking plugin:+On the terminal of the machine running OpenClaw, run the following command to install the OpenViking plugin:```bashopenclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup```-## Step 2 Enter the following information+## Step 2: Copy the Base URL and API Key-After running the install command, the setup wizard prompts for the following values. Copy and paste them into your agent terminal:+After running the install command, the setup flow prompts for the Base URL and API Key. Copy them and paste them into your agent terminal:-- Base URL: `https://api.vikingdb.cn-beijing.volces.com/openviking`+- Base URL: Copy the following Base URL into your agent terminal+```text+https://api.vikingdb.cn-beijing.volces.com/openviking+```- API Key: Copy the API Key shown on the page into your agent terminal-## Step 3 Restart OpenClaw+## Step 3: Restart OpenClawCopy the following command into the agent terminal to restart OpenClaw. After restart, the console automatically detects the agent connection status.diff --git a/docs/images/agents/en/opencode.md b/docs/images/agents/en/opencode.mdindex a38600ab7..957a66723 100644--- a/docs/images/agents/en/opencode.md+++ b/docs/images/agents/en/opencode.md@@ -1,14 +1,12 @@-# OpenCode Plugin-OpenCode has two plugin variants with different designs. Choose the one that matches how you want to use it.-## `opencode-memory-plugin` - Explicit tool version+## Option 1: `opencode-memory-plugin` - Explicit tool versionSource: [examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)This variant exposes OpenViking memory as explicit tools through OpenCode's tool mechanism. The model decides when to call them, and data is fetched on demand.-## `opencode/plugin` - Context injection version+## Option 2: `opencode/plugin` - Context injection versionSource: [examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)diff --git a/docs/images/agents/en/sdk.md b/docs/images/agents/en/sdk.mdindex 150032e57..f5c777aae 100644--- a/docs/images/agents/en/sdk.md+++ b/docs/images/agents/en/sdk.md@@ -1,8 +1,6 @@-# SDK Integration-## Step 1: Install OpenViking-Install or upgrade the Python package:+Run the following command to install OpenViking:```bashpip install openviking --upgrade --force-reinstall@@ -10,12 +8,14 @@ pip install openviking --upgrade --force-reinstall## Step 2: Initialize the client+Refer to the standard write example from GitHub and fill in the API Key and domain automatically:+```pythonfrom openviking.client import SyncHTTPClienturl = "https://api.vikingdb.cn-beijing.volces.com/openviking"-api_key = "<your-api-key>"-agent_id = "<your-agent-id>"+api_key = "[TODO]your-api-key"+agent_id = "[TODO]your-agent-id"client = SyncHTTPClient(url=url,@@ -26,17 +26,16 @@ client = SyncHTTPClient(client.initialize()```-## Step 3: Choose an API Key+## Step 3: Add a resource-Copy the API Key shown in the OpenViking console and pass it to the SDK client.--## Step 4: Add a resource+Refer to the standard resource write example from GitHub and fill in the API Key and domain automatically:```python-file_path = "<your-file-path>"-resource_to = "viking://resources"-reason = "External API documentation"+file_path = "[TODO]your-file-path"+resource_to = "[TODO]your-resource-path" # e.g. viking://resources+reason = "[TODO]your-reason" # e.g. External API documentation+# Reuse the initialized client.client.add_resource(path=file_path,to=resource_to,@@ -44,11 +43,14 @@ client.add_resource()```-## Step 5: Add memory+## Step 4: Add memory++Refer to the memory write example from GitHub and fill in the API Key and domain automatically:```python-text = "I am a developer"+text = "[TODO]your-message-text" # e.g. I am a developer+# Reuse the initialized client.session = client.create_session()session_id = session["session_id"]client.add_message(diff --git a/docs/images/agents/en/trae.md b/docs/images/agents/en/trae.mdindex d10e90eb0..ff253c00c 100644--- a/docs/images/agents/en/trae.md+++ b/docs/images/agents/en/trae.md@@ -1,58 +1,44 @@-# Trae MCP Integration--# 1. Use cases+## 1. Use casesUse OpenViking to:-- Remember technology stack preferences across sessions, including language versions, frameworks, package managers, and build systems.--- Persist coding style preferences, including naming conventions, comment style, whether to write tests, and TDD/BDD habits.--- Remember common project context, such as monorepo structure, build commands, deployment flow, and environment differences.--- Store historical decisions and troubleshooting notes, such as why option X was avoided or what failed last time with option Y.--- Persist long-term personal goals, OKRs, or roadmaps so the agent can align with them while planning tasks.-------# 2. Prerequisite: Get an API Key+- Remember technology stack preferences across sessions, including language versions, frameworks, package managers, and build systems-All MCP clients use the same **Authorization Token**, which is the API Key from the OpenViking console. Get it first and keep it secure.+- Preserve coding style preferences, such as naming conventions, comment style, whether to write unit tests, and TDD/BDD habits-## 2.1 Where to find it+- Remember common project context, such as monorepo structure, build commands, deployment workflows, and environment differences-1. In the left menu, choose **User Management**.+- Store historical decisions and troubleshooting notes, such as why option X was avoided or what issue happened last time with option Y-2. Find the target user in the user list. For personal editions, the default user is usually `default` / `admin`. Click the **copy** icon in the API Key column.+- Persist long-term personal goals, OKRs, and roadmap context so the agent can align with them while planning work-3. Save the copied `ZGV...hiMg` string. It will be used as the `Authorization` value for agent integration.+## 2. Trae Integration Steps for OpenViking-**Security note**: The API Key is equivalent to an account secret. Do not commit it to Git or publish it anywhere. Prefer environment variables or encrypted configuration.+**Trae** is an AI IDE from ByteDance that natively supports loading external tools and context services through MCP. Follow the steps below in Trae.----+### Step 1: Open Trae settings-# 3. Trae Integration Guide+In the Trae main window, click **Settings** (gear icon) in the upper-right corner to open the settings panel.-**Trae** is an AI IDE from ByteDance. It natively supports loading external tools and context services through MCP. This is the standard OpenViking integration flow.+-## 3.1 Integration steps+### Step 2: Open the MCP configuration page-### Step 1 - Open settings+In the left menu, select **MCP** to open the MCP Servers management page.-In the Trae main window, click **Settings** in the upper-right corner to open the settings panel.+-### Step 2 - Open the MCP configuration page+### Step 3: Add an MCP Server-In the left menu, select **MCP** to open the MCP Servers page.+Click the **+ Add** button on the right, then choose **Manual configuration** from the dropdown menu.-### Step 3 - Add an MCP Server+-Click the **+ Add** button on the right, then choose **Manual configuration** from the dropdown.+-### Step 4 - Paste the JSON configuration+### Step 4: Paste the JSON configuration-In the configuration dialog, paste the following JSON and replace `Authorization` with the API Key copied in section 2:+Paste the following JSON into the configuration dialog:```json{@@ -67,38 +53,52 @@ In the configuration dialog, paste the following JSON and replace `Authorization}```-**Important**: The `Authorization` value must include the `Bearer` prefix and a space. The full format is `Bearer <API Key>`.+++### Step 5: Confirm and enable++Click **Confirm**. Trae automatically establishes the MCP connection and loads the tool list. When the connection succeeds, `ov-mcp-server` appears in the configured MCP Servers list. After setup, you can see that `ov-mcp-server` is loaded and enabled on the MCP management page, with the switch on the right shown in green.++-### Step 5 - Confirm and enable+### Step 6: Check MCP connectivity-Click **Confirm**. Trae automatically connects to the MCP server and loads the tools. When the connection succeeds, `ov-mcp-server` appears in the configured MCP Servers list. The switch on the right should be green, which means the server is loaded and enabled.+After connecting, it is recommended to run two simple queries in Trae to verify that MCP is working correctly:-### Step 6 - Check MCP connectivity+**1.** **`ov ls`** - List the OpenViking root directory contents to confirm the connection is available and the directory structure is returned correctly:-After connecting, run two simple queries in Trae to verify the MCP server:+```bash+ov ls+```++-**1.** **`ov ls`** - List OpenViking root directories and confirm the connection returns the expected structure.+**2.** **`ov health`** - Call the health tool to confirm the OpenViking server status and current user identity:++```bash+ov health+```-**2.** **`ov health`** - Call the health tool to confirm server status and current identity.+-**Acceptance criteria**: `ov ls` returns directories such as `agent / resources / session / user`; `ov health` returns `service initialized` and the current username.+**Acceptance criteria**: `ov ls` returns directories such as `agent / resources / session / user`; `ov health` returns `service initialized` and the current username, which means the integration succeeded.-## 3.2 Configuration fields+## 3. Configuration fields| Field | Required | Description ||---|---|---|-| `mcpServers` | Yes | Root node for MCP server configuration |-| `ov-mcp-server` | Yes | Service alias. It can be customized, but keeping this name helps contextual recognition |+| `mcpServers` | Yes | Root node for MCP Server configuration |+| `ov-mcp-server` | Yes | Service alias. It can be customized, but keeping this name is recommended for contextual recognition || `url` | Yes | OpenViking MCP endpoint. For CN, use `https://api.vikingdb.cn-beijing.volces.com/openviking/mcp` |-| `headers.Authorization` | Yes | Format: `Bearer <API Key>`. Source: section 2 |+| `headers.Authorization` | Yes | Format: `Bearer <API Key>`. Source: see chapter 2 |----# 4. FAQ+## 4. FAQ| Problem | Suggested fix ||---|---|-| Connection failed / 401 Unauthorized | Check that `Authorization` includes the `Bearer` prefix and that the API Key is valid |-| Connection failed / network timeout | Confirm the network can reach `api.vikingdb.cn-beijing.volces.com`; add an allowlist entry for corporate networks if needed |-| Agent cannot see tools | Confirm the MCP server is enabled. Some clients need a process restart before loading new config |-| MCP tool reports argument schema incompatibility with the current model, or asks you to switch/fix the MCP server or model (4027) | Try switching models or upgrading Trae to the latest version |+| Connection failed / 401 Unauthorized | Check that `Authorization` includes the `Bearer` prefix and confirm the API Key has not expired or been reset |+| Connection failed / network timeout | Confirm the network can reach `api.vikingdb.cn-beijing.volces.com`; for corporate networks, add the domain to the proxy allowlist |+| Agent cannot recognize tools | Confirm the MCP Server is enabled; some clients need a process restart before loading the new configuration |+| MCP tools are incompatible with the current model because of the argument schema; switch or fix the MCP server, or switch the model (4027) | <br><br>Try switching models or upgrading Trae to the latest version |diff --git a/docs/images/agents/zh/claude-code.md b/docs/images/agents/zh/claude-code.mdindex 86cf4886a..9acc6b1b9 100644--- a/docs/images/agents/zh/claude-code.md+++ b/docs/images/agents/zh/claude-code.md@@ -1,5 +1,3 @@-# 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/)diff --git a/docs/images/agents/zh/cursor.md b/docs/images/agents/zh/cursor.mdindex 1fc19b4f9..b40a4b83d 100644--- a/docs/images/agents/zh/cursor.md+++ b/docs/images/agents/zh/cursor.md@@ -78,8 +78,6 @@ ov health|`url`|是|OpenViking MCP 服务端点;CN 区固定为 `https://api\.vikingdb\.cn\-beijing\.volces\.com/openviking/mcp`||`headers\.Authorization`|是|格式 `Bearer \<API Key\>`,来源见第一章|-----## 三、常见问题(FAQ)|问题|解决建议|@@ -87,4 +85,3 @@ ov health|连接失败 / 401 Unauthorized|检查 `Authorization` 是否带 `Bearer` 前缀;确认 API Key 未过期或被重置||连接失败 / 网络超时<br>|确认网络可访问 `api\.vikingdb\.cn\-beijing\.volces\.com`;企业网络请配置代理白名单||Agent 无法识别工具|检查 MCP Server 是否已\&\#34;启用\&\#34;;部分客户端需重启进程后加载新配置|-diff --git a/docs/images/agents/zh/mcp.md b/docs/images/agents/zh/mcp.mdindex f2bfdbf9f..03d762aea 100644--- a/docs/images/agents/zh/mcp.md+++ b/docs/images/agents/zh/mcp.md@@ -1,5 +1,3 @@-# MCP 接入-### 步骤 1:MCP 配置```json@@ -15,7 +13,6 @@}```-**关键说明**:`Authorization` 的值需带上 `Bearer` 前缀(注意空格),完整格式为 `Bearer \<API Key\>`。### 步骤 2:测试 MCP 工具连通性输入 `ov health` 检查 ov 的版本和连接状态diff --git a/docs/images/agents/zh/trae.md b/docs/images/agents/zh/trae.mdindex a80643b2e..b380b59c8 100644--- a/docs/images/agents/zh/trae.md+++ b/docs/images/agents/zh/trae.md@@ -1,4 +1,3 @@-## 一、适用场景使用 OpenViking 实现:@@ -13,43 +12,23 @@- 个人长期任务目标 / OKR / Roadmap 沉淀,Agent 在规划任务时自动对齐------## 二、前置准备:获取 API Key--所有 MCP 客户端的接入都依赖同一个 **Authorization Token**,即 OpenViking 控制台中的 API Key。请先按以下步骤获取并妥善保存:--1. 在左侧菜单选择 **用户管理**--2. 在用户列表中找到对应用户(个人版默认为 `default` / `admin`),点击 API Key 列右侧的 **复制** 图标--3. 将复制得到的 `ZGV\.\.\.hiMg` 形式的字符串妥善保存,作为后续所有 Agent 接入的 `Authorization` 值--**安全提示**:API Key 等同于账户密钥,请勿提交到 Git 仓库或公开渠道。建议通过环境变量或加密配置注入。---------## 三、Trae 接入指南--**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。以下为 OpenViking 的标准接入流程。+## 二、Trae 接入 OpenViking 操作步骤-### 3\.1 接入步骤+**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。请在 trae 按以下步骤操作:-#### 步骤 1:打开设置+### 步骤 1:打开 Trae 设置在 Trae 主界面右上角点击 **设置(齿轮图标)**,进入设置面板。-#### 步骤 2:进入 MCP 配置页+### 步骤 2:进入 MCP 配置页在左侧菜单中选择 **MCP**,进入 MCP Servers 管理页。-#### 步骤 3:新增 MCP Server+### 步骤 3:新增 MCP Server点击右侧的 **\+ 添加** 按钮,在下拉菜单中选择 **手动配置**。@@ -57,9 +36,9 @@-#### 步骤 4:粘贴配置 JSON+### 步骤 4:粘贴配置 JSON-在弹出的配置框中粘贴以下 JSON,并将 `Authorization` 替换为第二章中复制的 API Key:+在弹出的配置框中粘贴以下 JSON:```json{@@ -74,25 +53,31 @@}```-**关键说明**:`Authorization` 的值需带上 `Bearer` 前缀(注意空格),完整格式为 `Bearer \<API Key\>`。--#### 步骤 5:确认并启用+### 步骤 5:确认并启用点击 **确认** 按钮,Trae 会自动建立 MCP 连接并加载工具列表。连接成功后,`ov\-mcp\-server` 将出现在已配置的 MCP Servers 列表中。配置完成后,可在 MCP 管理页看到 `ov\-mcp\-server` 已加载并启用,右侧开关呈绿色:-#### 步骤 6:MCP 连通性检查+### 步骤 6:MCP 连通性检查接入后建议通过两个简单 query 快速验证 MCP 是否正常工作。在 Trae 对话框中依次输入:-**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构。+**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构:++```bash+ov ls+```-**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份。+**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份:++```bash+ov health+```@@ -100,14 +85,16 @@-### 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\>`|+|`headers\.Authorization`|是|格式 `Bearer \<API Key\>`,来源见第二章|++---## 四、常见问题(FAQ)