Skip to content

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

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.md
index 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:
```python
import json
@@ -15,12 +9,13 @@ from pathlib import Path
import requests
url = "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.md
index 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
```bash
bash <(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
```bash
type 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 diagram
diff --git a/docs/images/agents/en/cli.md b/docs/images/agents/en/cli.md
index 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:
```bash
npm 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:
```text
https://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:
```bash
ov --help
diff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.md
index 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
```bash
bash <(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
```bash
type 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 diagram
diff --git a/docs/images/agents/en/cursor.md b/docs/images/agents/en/cursor.md
index 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.
-
-![Copy OpenViking API Key](https://docs.openviking.net/agents/image/cursor/01-api-key.jpg)
-
-# 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 settings
In the Cursor main window, click **Settings** in the upper-right corner to open the settings panel.
![Open Cursor settings](https://docs.openviking.net/agents/image/cursor/02-open-settings.png)
-### Step 2 - Add an MCP Server
+### Step 2: Add an MCP Server
In the left menu, select **Tools & MCPs** to open the MCP Servers page.
@@ -38,9 +18,9 @@ Click **Add Custom MCP**.
![Add custom MCP server](https://docs.openviking.net/agents/image/cursor/04-add-custom-mcp.png)
-### 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>`.
-
-![Paste MCP JSON configuration](https://docs.openviking.net/agents/image/cursor/05-paste-mcp-json.jpg)
-
-### Step 4 - Confirm and enable
+### Step 4: Confirm and enable
After 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.
![Confirm and enable MCP Server](https://docs.openviking.net/agents/image/cursor/06-enable-server.png)
-### 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
+```
![Run ov ls](https://docs.openviking.net/agents/image/cursor/07-ov-ls.png)
-**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
+```
![Run ov health](https://docs.openviking.net/agents/image/cursor/08-ov-health.png)
-**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.md
index 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
```bash
hermes 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
```bash
hermes memory status
@@ -26,7 +22,7 @@ hermes memory status
After 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 service
diff --git a/docs/images/agents/en/mcp.md b/docs/images/agents/en/mcp.md
index 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 connectivity
Enter `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.md
index 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:
```bash
openclaw 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 OpenClaw
Copy 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.md
index 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 version
Source: [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 version
Source: [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.md
index 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:
```bash
pip 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:
+
```python
from openviking.client import SyncHTTPClient
url = "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.md
index 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 cases
Use 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.
+![Open Trae settings](https://docs.openviking.net/agents/image/trae/02-open-settings.jpg)
-## 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.
+![Open the MCP configuration page](https://docs.openviking.net/agents/image/trae/03-mcp-settings.jpg)
-### 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
+![Add MCP Server](https://docs.openviking.net/agents/image/trae/04-add-mcp-server.jpg)
-Click the **+ Add** button on the right, then choose **Manual configuration** from the dropdown.
+![Choose manual configuration](https://docs.openviking.net/agents/image/trae/05-manual-config.png)
-### 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>`.
+![Paste MCP JSON configuration](https://docs.openviking.net/agents/image/trae/06-paste-mcp-json.jpg)
+
+### 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.
+
+![Confirm and enable MCP Server](https://docs.openviking.net/agents/image/trae/07-enable-server.jpg)
-### 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
+```
+
+![Run ov ls](https://docs.openviking.net/agents/image/trae/08-ov-ls.jpg)
-**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.
+![Run ov health](https://docs.openviking.net/agents/image/trae/09-ov-health.jpg)
-**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) | ![Trae MCP schema compatibility error](https://docs.openviking.net/agents/image/trae/10-schema-error.png)<br>![Trae MCP schema compatibility detail](https://docs.openviking.net/agents/image/trae/11-schema-error-detail.png)<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.md
index 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.md
index 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 \&lt;API Key\&gt;`,来源见第一章|
----
-
## 三、常见问题(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.md
index 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 \&lt;API Key\&gt;`。
### 步骤 2:测试 MCP 工具连通性
输入 `ov health` 检查 ov 的版本和连接状态
diff --git a/docs/images/agents/zh/trae.md b/docs/images/agents/zh/trae.md
index 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 仓库或公开渠道。建议通过环境变量或加密配置注入。
-
-![获取 OpenViking API Key](https://docs.openviking.net/agents/image/trae/01-api-key.jpg)
-
----
-
-## 三、Trae 接入指南
-
-**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。以下为 OpenViking 的标准接入流程。
+## 二、Trae 接入 OpenViking 操作步骤
-### 3\.1 接入步骤
+**Trae** 是字节跳动推出的 AI IDE,原生支持通过 MCP 协议加载外部工具与上下文服务。请在 trae 按以下步骤操作:
-#### 步骤 1:打开设置
+### 步骤 1:打开 Trae 设置
在 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
点击右侧的 **\+ 添加** 按钮,在下拉菜单中选择 **手动配置**。
@@ -57,9 +36,9 @@
![选择手动配置](https://docs.openviking.net/agents/image/trae/05-manual-config.png)
-#### 步骤 4:粘贴配置 JSON
+### 步骤 4:粘贴配置 JSON
-在弹出的配置框中粘贴以下 JSON,并将 `Authorization` 替换为第二章中复制的 API Key:
+在弹出的配置框中粘贴以下 JSON:
```json
{
@@ -74,25 +53,31 @@
}
```
-**关键说明**:`Authorization` 的值需带上 `Bearer` 前缀(注意空格),完整格式为 `Bearer \&lt;API Key\&gt;`。
-
![粘贴 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 对话框中依次输入:
-**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构。
+**① ****`ov ls`** — 列出 OpenViking 根目录内容,确认连接畅通、可正确返回目录结构:
+
+```bash
+ov ls
+```
![运行 ov ls 验证连接](https://docs.openviking.net/agents/image/trae/08-ov-ls.jpg)
-**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份。
+**② ****`ov health`** — 调用 health 工具,确认 OpenViking 服务端状态与当前用户身份:
+
+```bash
+ov health
+```
![运行 ov health 验证服务状态](https://docs.openviking.net/agents/image/trae/09-ov-health.jpg)
@@ -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 \&lt;API Key\&gt;`|
+|`headers\.Authorization`|是|格式 `Bearer \&lt;API Key\&gt;`,来源见第二章|
+
+---
## 四、常见问题(FAQ)