Skip to content

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

docs: add general agent integration guides (#2354)

yufeng5752ceb8fb20
diff --git a/.github/workflows/docs-tos.yml b/.github/workflows/docs-tos.yml
index f45139a29..2d66e098c 100644
--- a/.github/workflows/docs-tos.yml
+++ b/.github/workflows/docs-tos.yml
@@ -134,14 +134,15 @@ jobs:
--cache-control "${NO_CACHE_CONTROL}" \
--only-show-errors
- if [ -f "${DIST_DIR}/agents/index.json" ]; then
- aws s3 cp "${DIST_DIR}/agents/index.json" "s3://${TOS_BUCKET}/agents/index.json" \
+ while IFS= read -r -d '' json_file; do
+ rel_path="${json_file#${DIST_DIR}/agents/}"
+ aws s3 cp "${json_file}" "s3://${TOS_BUCKET}/agents/${rel_path}" \
--endpoint-url "https://${TOS_S3_ENDPOINT}" \
--content-type "application/json; charset=utf-8" \
--content-disposition "inline" \
--cache-control "${NO_CACHE_CONTROL}" \
--only-show-errors
- fi
+ done < <(find "${DIST_DIR}/agents" -type f -name "*.json" -print0)
while IFS= read -r -d '' markdown_file; do
rel_path="${markdown_file#${DIST_DIR}/agents/}"
diff --git a/docs/images/agents/en/api.md b/docs/images/agents/en/api.md
new file mode 100644
index 000000000..8ac426e83
--- /dev/null
+++ b/docs/images/agents/en/api.md
@@ -0,0 +1,86 @@
+# API Integration
+
+## 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:
+
+```python
+import json
+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"
+
+headers = {
+ "Content-Type": "application/json",
+ "Authorization": "Bearer " + api_key,
+ "X-OpenViking-Agent": agent_id,
+}
+
+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()
+
+with file_path.open("rb") as file:
+ result = requests.post(
+ f"{url}/api/v1/resources/temp_upload",
+ headers={
+ "Authorization": "Bearer " + api_key,
+ "X-OpenViking-Agent": agent_id,
+ },
+ files={"file": (file_path.name, file, "application/octet-stream")},
+ timeout=120.0,
+ )
+result.raise_for_status()
+temp_file_id = result.json()["result"]["temp_file_id"]
+
+result = post_json(
+ "/api/v1/resources",
+ {
+ "temp_file_id": temp_file_id,
+ "source_name": file_path.name,
+ "to": resource_to,
+ "reason": reason,
+ },
+ 120.0,
+)
+print(json.dumps(result, ensure_ascii=False, indent=2))
+```
+
+## Step 3: Add memory
+
+Create a session, add a message, and commit the session:
+
+```python
+text = "I am a developer"
+
+session = post_json("/api/v1/sessions", {}, 360.0)
+session_id = session["result"]["session_id"]
+
+post_json(
+ f"/api/v1/sessions/{session_id}/messages",
+ {
+ "role": "user",
+ "parts": [{"type": "text", "text": text}],
+ },
+ 360.0,
+)
+
+result = post_json(
+ f"/api/v1/sessions/{session_id}/commit",
+ {"telemetry": False},
+ 360.0,
+)
+print(json.dumps(result, ensure_ascii=False, indent=2))
+```
diff --git a/docs/images/agents/en/claude-code.md b/docs/images/agents/en/claude-code.md
new file mode 100644
index 000000000..b662ab1ad
--- /dev/null
+++ b/docs/images/agents/en/claude-code.md
@@ -0,0 +1,27 @@
+# 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; recall and capture happen automatically on every conversation.
+
+## Install
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)
+```
+
+The installer checks dependencies, configures the OpenViking connection, and installs the plugin.
+
+## Verify
+
+```bash
+type claude
+```
+
+Expected output: `claude is a shell function`.
+
+In Claude Code:
+
+- `/plugins`: find `openviking-memory` in Installed
+- `/mcp`: confirm the OpenViking MCP endpoint is connected
+- `/openviking-memory:ov`: view server status, identity, recall, and capture state
+
+Set `OPENVIKING_DEBUG=1` to write debug logs to `~/.openviking/logs/cc-hooks.log`.
diff --git a/docs/images/agents/en/cli.md b/docs/images/agents/en/cli.md
new file mode 100644
index 000000000..ca902820b
--- /dev/null
+++ b/docs/images/agents/en/cli.md
@@ -0,0 +1,40 @@
+# CLI Integration
+
+## Install from the command line
+
+Run the following command in your terminal to install OpenViking CLI and start configuration:
+
+```bash
+npm i -g @openviking/cli && ov config
+```
+
+Use this service URL when prompted:
+
+```text
+https://api.vikingdb.cn-beijing.volces.com/openviking
+```
+
+After configuration, inspect CLI usage with:
+
+```bash
+ov --help
+```
+
+## Install through an agent conversation
+
+The Agent CLI setup flow will be improved in a follow-up PR. For now, send the following instruction to your agent:
+
+```text
+Write the following content to ~/.openviking/ovcli.conf:
+{"url":"https://api.vikingdb.cn-beijing.volces.com/openviking","api_key":"Please ask user for Volcengine OpenViking API key."}
+
+Ask the user for the API Key. If ~/.openviking/ovcli.conf already exists and the content conflicts, ask the user whether to back up the original file before overwriting it.
+
+Install OpenViking CLI:
+npm i -g @openviking/cli
+
+After installation, run:
+ov --help
+
+Explore the CLI usage and write the OpenViking CLI workflow into your long-term memory.
+```
diff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.md
new file mode 100644
index 000000000..b19f314e7
--- /dev/null
+++ b/docs/images/agents/en/codex.md
@@ -0,0 +1,32 @@
+# Codex Memory Plugin
+
+Add persistent cross-session memory to Codex. The plugin recalls relevant memory before each user prompt, captures conversation updates after each turn, commits before compaction, and connects Codex to the OpenViking MCP endpoint.
+
+## Install
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
+```
+
+After installation:
+
+```bash
+source ~/.zshrc
+codex
+```
+
+Approve hooks on first launch if Codex asks for review.
+
+## Verify
+
+```bash
+type codex
+```
+
+Expected output: `codex is a shell function`.
+
+Set `OPENVIKING_DEBUG=1` to write events to `~/.openviking/logs/codex-hooks.log`.
+
+## Notes
+
+Codex does not trigger hooks on `SIGTERM`, `Ctrl+C`, or `/exit`. The plugin cleans up orphan sessions on the next `SessionStart` with an idle TTL.
diff --git a/docs/images/agents/en/cursor.md b/docs/images/agents/en/cursor.md
new file mode 100644
index 000000000..927e5b6e0
--- /dev/null
+++ b/docs/images/agents/en/cursor.md
@@ -0,0 +1,49 @@
+# Cursor MCP Integration
+
+## Step 1: Get an API Key
+
+OpenViking MCP clients use the API Key from the OpenViking console as the authorization token. Copy it before configuring Cursor.
+
+## Step 2: Open Cursor MCP settings
+
+In Cursor, open Settings and go to **Tools & MCPs**.
+
+## Step 3: Add a custom MCP server
+
+Click **Add Custom MCP**, then add the following configuration to `mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "ov-mcp-server": {
+ "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
+ "headers": {
+ "Authorization": "Bearer <API Key>"
+ }
+ }
+ }
+}
+```
+
+The `Authorization` value must include the `Bearer` prefix.
+
+## Step 4: Enable and verify
+
+Save `mcp.json`. Cursor should load `ov-mcp-server` and show the enabled tools.
+
+Run these queries in Cursor:
+
+```text
+ov ls
+ov health
+```
+
+`ov ls` should return OpenViking root directories such as `agent`, `resources`, `session`, and `user`. `ov health` should return service status and the current identity.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `401 Unauthorized` | Check that `Authorization` includes `Bearer <API Key>` and that the API Key is valid. |
+| Network timeout | Confirm the network can reach `api.vikingdb.cn-beijing.volces.com`. |
+| Agent cannot see tools | Confirm the MCP server is enabled. Some clients need a restart after config changes. |
diff --git a/docs/images/agents/en/hermes.md b/docs/images/agents/en/hermes.md
new file mode 100644
index 000000000..149f5e425
--- /dev/null
+++ b/docs/images/agents/en/hermes.md
@@ -0,0 +1,27 @@
+# Hermes Agent
+
+[Hermes Agent](https://hermes-agent.nousresearch.com/) includes OpenViking as a native memory provider. No plugin installation is required.
+
+## Configure memory
+
+Run the Hermes memory setup wizard:
+
+```bash
+hermes memory setup
+```
+
+The wizard asks for:
+
+- OpenViking service URL, such as `https://api.vikingdb.cn-beijing.volces.com/openviking`
+- API Key
+- Tenant account, user, and agent ID for multi-tenant deployments
+
+Hermes stores the configuration in `config.yaml` and `.env`.
+
+## Verify
+
+```bash
+hermes memory status
+```
+
+After setup, Hermes uses OpenViking for long-term memory storage, recall, and extraction.
diff --git a/docs/images/agents/en/index.json b/docs/images/agents/en/index.json
new file mode 100644
index 000000000..2799db3a8
--- /dev/null
+++ b/docs/images/agents/en/index.json
@@ -0,0 +1,93 @@
+{
+ "version": 1,
+ "updatedAt": "2026-06-01",
+ "cdnBaseUrl": "https://docs.openviking.net/",
+ "accessMethods": [
+ {
+ "id": "mcp",
+ "name": "MCP Integration",
+ "icon": "link",
+ "summary": "Connect from any client that supports MCP.",
+ "detailPath": "https://docs.openviking.net/agents/en/mcp.md"
+ },
+ {
+ "id": "cli",
+ "name": "CLI Integration",
+ "icon": "terminal",
+ "summary": "Connect agents through the OpenViking command line.",
+ "detailPath": "https://docs.openviking.net/agents/en/cli.md"
+ },
+ {
+ "id": "api",
+ "name": "API Integration",
+ "icon": "code",
+ "summary": "Call OpenViking capabilities through the REST API.",
+ "detailPath": "https://docs.openviking.net/agents/en/api.md"
+ },
+ {
+ "id": "sdk",
+ "name": "SDK Integration",
+ "icon": "paperclip",
+ "summary": "Use SDK wrappers for faster and cleaner integration.",
+ "detailPath": "https://docs.openviking.net/agents/en/sdk.md"
+ }
+ ],
+ "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 integration for OpenClaw as a context engine, with cross-agent memory and one-command setup through the npm helper.",
+ "detailPath": "https://docs.openviking.net/agents/en/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 includes OpenViking as a native memory provider. Point Hermes to your OpenViking service to enable storage, recall, and extraction.",
+ "detailPath": "https://docs.openviking.net/agents/en/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": "Adds long-term memory to Claude Code across projects and sessions. Install once; recall and capture run automatically.",
+ "detailPath": "https://docs.openviking.net/agents/en/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": "Adds persistent cross-session memory to Codex through lifecycle hooks and the OpenViking MCP endpoint.",
+ "detailPath": "https://docs.openviking.net/agents/en/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": "Connect Cursor through MCP to provide coding and agent-development context management.",
+ "detailPath": "https://docs.openviking.net/agents/en/cursor.md"
+ },
+ {
+ "id": "trae",
+ "name": "TRAE",
+ "tags": ["MCP"],
+ "logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Trae.png",
+ "summary": "Connect TRAE through MCP and use OpenViking for coding context, memory, and resource management.",
+ "detailPath": "https://docs.openviking.net/agents/en/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": "Provides OpenCode plugins that can expose OpenViking either as model-selected tools or injected context.",
+ "detailPath": "https://docs.openviking.net/agents/en/opencode.md"
+ }
+ ]
+}
diff --git a/docs/images/agents/en/mcp.md b/docs/images/agents/en/mcp.md
new file mode 100644
index 000000000..2f81528cd
--- /dev/null
+++ b/docs/images/agents/en/mcp.md
@@ -0,0 +1,30 @@
+# MCP Integration
+
+## Step 1: Configure MCP
+
+Add the OpenViking MCP server to your MCP client configuration:
+
+```json
+{
+ "mcpServers": {
+ "ov-mcp-server": {
+ "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
+ "headers": {
+ "Authorization": "Bearer <API Key>"
+ }
+ }
+ }
+}
+```
+
+The `Authorization` value must include the `Bearer` prefix and one space before the API key.
+
+## Step 2: Verify the connection
+
+Ask your agent to run:
+
+```text
+ov health
+```
+
+If the tool returns the OpenViking version and service status, the MCP connection is ready.
diff --git a/docs/images/agents/en/openclaw.md b/docs/images/agents/en/openclaw.md
new file mode 100644
index 000000000..7a1a044dd
--- /dev/null
+++ b/docs/images/agents/en/openclaw.md
@@ -0,0 +1,24 @@
+# OpenClaw Plugin
+
+## Step 1: Install OpenViking
+
+Run the following command in the terminal where OpenClaw is installed:
+
+```bash
+openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup
+```
+
+## Step 2: Enter connection information
+
+The setup command will prompt for:
+
+- Base URL: `https://api.vikingdb.cn-beijing.volces.com/openviking`
+- API Key: copy the API Key shown in the OpenViking console
+
+## Step 3: Restart OpenClaw
+
+Restart OpenClaw so the plugin can load the new configuration:
+
+```bash
+openclaw gateway restart
+```
diff --git a/docs/images/agents/en/opencode.md b/docs/images/agents/en/opencode.md
new file mode 100644
index 000000000..498036341
--- /dev/null
+++ b/docs/images/agents/en/opencode.md
@@ -0,0 +1,18 @@
+# Opencode Plugin
+
+OpenViking provides two OpenCode plugin modes:
+
+- tool mode, where the model can choose when to call OpenViking tools
+- context mode, where OpenViking injects relevant context into the session
+
+## Configure
+
+Install the OpenViking OpenCode plugin from the OpenViking plugin package or local marketplace, then configure the service URL and API Key:
+
+```text
+https://api.vikingdb.cn-beijing.volces.com/openviking
+```
+
+## Verify
+
+Start OpenCode and confirm the OpenViking plugin is loaded. Ask the agent to inspect OpenViking status or search memory to verify connectivity.
diff --git a/docs/images/agents/en/sdk.md b/docs/images/agents/en/sdk.md
new file mode 100644
index 000000000..150032e57
--- /dev/null
+++ b/docs/images/agents/en/sdk.md
@@ -0,0 +1,60 @@
+# SDK Integration
+
+## Step 1: Install OpenViking
+
+Install or upgrade the Python package:
+
+```bash
+pip install openviking --upgrade --force-reinstall
+```
+
+## Step 2: Initialize the client
+
+```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>"
+
+client = SyncHTTPClient(
+ url=url,
+ api_key=api_key,
+ agent_id=agent_id,
+ timeout=120.0,
+)
+client.initialize()
+```
+
+## Step 3: Choose an API Key
+
+Copy the API Key shown in the OpenViking console and pass it to the SDK client.
+
+## Step 4: Add a resource
+
+```python
+file_path = "<your-file-path>"
+resource_to = "viking://resources"
+reason = "External API documentation"
+
+client.add_resource(
+ path=file_path,
+ to=resource_to,
+ reason=reason,
+)
+```
+
+## Step 5: Add memory
+
+```python
+text = "I am a developer"
+
+session = client.create_session()
+session_id = session["session_id"]
+client.add_message(
+ session_id,
+ "user",
+ parts=[{"type": "text", "text": text}],
+)
+result = client.commit_session(session_id)
+```
diff --git a/docs/images/agents/en/trae.md b/docs/images/agents/en/trae.md
new file mode 100644
index 000000000..0a08a44d1
--- /dev/null
+++ b/docs/images/agents/en/trae.md
@@ -0,0 +1,47 @@
+# TRAE MCP Integration
+
+## Step 1: Get an API Key
+
+Copy the API Key from the OpenViking console. It will be used as the MCP `Authorization` token.
+
+## Step 2: Open TRAE MCP settings
+
+In TRAE, open Settings and select **MCP** to enter the MCP Servers page.
+
+## Step 3: Add an MCP server
+
+Choose manual configuration and paste:
+
+```json
+{
+ "mcpServers": {
+ "ov-mcp-server": {
+ "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp",
+ "headers": {
+ "Authorization": "Bearer <API Key>"
+ }
+ }
+ }
+}
+```
+
+## Step 4: Enable and verify
+
+After saving, TRAE should load `ov-mcp-server` and enable the tools.
+
+Run:
+
+```text
+ov ls
+ov health
+```
+
+The integration is ready when `ov ls` returns OpenViking directories and `ov health` returns service status.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `401 Unauthorized` | Check the API Key and the `Bearer` prefix. |
+| Network timeout | Confirm the network can reach the OpenViking API domain. |
+| Tool schema is incompatible with the current model | Switch models or upgrade TRAE to the latest version. |
diff --git a/docs/images/agents/zh/api.md b/docs/images/agents/zh/api.md
new file mode 100644
index 000000000..c16d2156f
--- /dev/null
+++ b/docs/images/agents/zh/api.md
@@ -0,0 +1,95 @@
+## 步骤 1 选择 API Key
+复制页面中展示的 API Key 到你的 Agent 终端
+
+## 步骤 2 写入资源
+参考 GitHub 提供的资源写入示例,自动填入 API Key 和域名
+
+```python
+import json
+from pathlib import Path
+
+import requests
+
+url = " `https://api.vikingdb.cn-beijing.volces.com/openviking` "
+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,
+ "X-OpenViking-Agent": agent_id,
+}
+
+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()
+
+
+# 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",
+ headers={
+ "Authorization": "Bearer " + api_key,
+ "X-OpenViking-Agent": agent_id,
+ },
+ files={"file": (file_path.name, file, "application/octet-stream")},
+ timeout=120.0,
+ )
+result.raise_for_status()
+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",
+ {
+ "temp_file_id": temp_file_id,
+ "source_name": file_path.name,
+ "to": resource_to,
+ "reason": reason,
+ },
+ 120.0,
+)
+print(json.dumps(result, ensure_ascii=False, indent=2))
+```
+
+## 步骤 3 写入记忆
+参考 GitHub 提供的记忆写入示例,自动填入 API Key 和域名
+
+```python
+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",
+ {
+ "role": "user",
+ "parts": [{"type": "text", "text": text}],
+ },
+ 360.0,
+)
+
+# Commit the session.
+result = post_json(
+ f"/api/v1/sessions/{session_id}/commit",
+ {"telemetry": False},
+ 360.0,
+)
+print(json.dumps(result, ensure_ascii=False, indent=2))
+```
diff --git a/docs/images/agents/claude-code.md b/docs/images/agents/zh/claude-code.md
similarity index 100%
rename from docs/images/agents/claude-code.md
rename to docs/images/agents/zh/claude-code.md
diff --git a/docs/images/agents/zh/cli.md b/docs/images/agents/zh/cli.md
new file mode 100644
index 000000000..f537d8b86
--- /dev/null
+++ b/docs/images/agents/zh/cli.md
@@ -0,0 +1,40 @@
+# CLI 接入
+
+## CLI 命令行安装
+
+在终端执行以下命令安装 OpenViking CLI,并进入配置流程:
+
+```bash
+npm i -g @openviking/cli && ov config
+```
+
+按提示填写 OpenViking 服务地址和 API Key。服务地址可使用:
+
+```text
+https://api.vikingdb.cn-beijing.volces.com/openviking
+```
+
+配置完成后,可运行以下命令查看 CLI 用法:
+
+```bash
+ov --help
+```
+
+## Agent 对话安装
+
+下个 PR 将继续优化 Agent CLI 安装流程,目前可先把以下指令发送给你的 Agent,让 Agent 帮你完成安装和配置:
+
+```text
+请在 ~/.openviking/ovcli.conf 写入以下内容:
+{"url":"https://api.vikingdb.cn-beijing.volces.com/openviking","api_key":"Please ask user for Volcengine OpenViking API key."}
+
+请向用户询问 API Key。如发现 ~/.openviking/ovcli.conf 已存在且内容冲突,请先询问用户是否备份原文件,并在得到确认后再覆盖。
+
+请安装 OpenViking CLI:
+npm i -g @openviking/cli
+
+安装完成后,请运行:
+ov --help
+
+请探索 CLI 用法,并把 OpenViking CLI 的使用方式写入你的长期记忆。
+```
diff --git a/docs/images/agents/codex.md b/docs/images/agents/zh/codex.md
similarity index 100%
rename from docs/images/agents/codex.md
rename to docs/images/agents/zh/codex.md
diff --git a/docs/images/agents/cursor.md b/docs/images/agents/zh/cursor.md
similarity index 100%
rename from docs/images/agents/cursor.md
rename to docs/images/agents/zh/cursor.md
diff --git a/docs/images/agents/hermes.md b/docs/images/agents/zh/hermes.md
similarity index 100%
rename from docs/images/agents/hermes.md
rename to docs/images/agents/zh/hermes.md
diff --git a/docs/images/agents/index.json b/docs/images/agents/zh/index.json
similarity index 65%
rename from docs/images/agents/index.json
rename to docs/images/agents/zh/index.json
index a260419aa..9ac5886f0 100644
--- a/docs/images/agents/index.json
+++ b/docs/images/agents/zh/index.json
@@ -1,7 +1,37 @@
{
"version": 1,
- "updatedAt": "2026-05-29",
+ "updatedAt": "2026-06-01",
"cdnBaseUrl": "https://docs.openviking.net/",
+ "accessMethods": [
+ {
+ "id": "mcp",
+ "name": "MCP 接入",
+ "icon": "link",
+ "summary": "与任意支持 MCP 的客户端接入",
+ "detailPath": "https://docs.openviking.net/agents/zh/mcp.md"
+ },
+ {
+ "id": "cli",
+ "name": "CLI 接入",
+ "icon": "terminal",
+ "summary": "命令行接入 Agent,使用灵活性更高",
+ "detailPath": "https://docs.openviking.net/agents/zh/cli.md"
+ },
+ {
+ "id": "api",
+ "name": "API 接入",
+ "icon": "code",
+ "summary": "标准 REST API,灵活调用所有能力",
+ "detailPath": "https://docs.openviking.net/agents/zh/api.md"
+ },
+ {
+ "id": "sdk",
+ "name": "SDK 接入",
+ "icon": "paperclip",
+ "summary": "多语言 SDK 封装,集成更便捷、高效",
+ "detailPath": "https://docs.openviking.net/agents/zh/sdk.md"
+ }
+ ],
"agents": [
{
"id": "openclaw",
@@ -9,7 +39,7 @@
"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"
+ "detailPath": "https://docs.openviking.net/agents/zh/openclaw.md"
},
{
"id": "hermes",
@@ -17,7 +47,7 @@
"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"
+ "detailPath": "https://docs.openviking.net/agents/zh/hermes.md"
},
{
"id": "claude-code",
@@ -25,7 +55,7 @@
"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"
+ "detailPath": "https://docs.openviking.net/agents/zh/claude-code.md"
},
{
"id": "codex",
@@ -33,7 +63,7 @@
"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"
+ "detailPath": "https://docs.openviking.net/agents/zh/codex.md"
},
{
"id": "cursor",
@@ -41,7 +71,7 @@
"tags": ["MCP"],
"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Cursor.png",
"summary": "通过 MCP 标准协议接入,为 Codex 提供支撑日常编码 和 Agent 开发场景的上下文管理",
- "detailPath": "https://docs.openviking.net/agents/cursor.md"
+ "detailPath": "https://docs.openviking.net/agents/zh/cursor.md"
},
{
"id": "trae",
@@ -49,7 +79,7 @@
"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"
+ "detailPath": "https://docs.openviking.net/agents/zh/trae.md"
},
{
"id": "opencode",
@@ -57,7 +87,7 @@
"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"
+ "detailPath": "https://docs.openviking.net/agents/zh/opencode.md"
}
]
}
diff --git a/docs/images/agents/zh/mcp.md b/docs/images/agents/zh/mcp.md
new file mode 100644
index 000000000..b0bc02ce1
--- /dev/null
+++ b/docs/images/agents/zh/mcp.md
@@ -0,0 +1,22 @@
+# MCP 接入
+
+步骤 1 MCP 配置
+
+```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;`。
+
+步骤 2 测试 MCP 工具连通性
+
+输入 `ov health` 检查 ov 的版本和连接状态
diff --git a/docs/images/agents/openclaw.md b/docs/images/agents/zh/openclaw.md
similarity index 100%
rename from docs/images/agents/openclaw.md
rename to docs/images/agents/zh/openclaw.md
diff --git a/docs/images/agents/opencode.md b/docs/images/agents/zh/opencode.md
similarity index 100%
rename from docs/images/agents/opencode.md
rename to docs/images/agents/zh/opencode.md
diff --git a/docs/images/agents/zh/sdk.md b/docs/images/agents/zh/sdk.md
new file mode 100644
index 000000000..b85e1e5f4
--- /dev/null
+++ b/docs/images/agents/zh/sdk.md
@@ -0,0 +1,61 @@
+## 步骤 1 安装 OpenViking
+执行以下命令以安装 OpenViking
+
+```bash
+pip install openviking --upgrade --force-reinstall
+```
+
+## 步骤 2 初始化客户端
+参考 GitHub 提供的规范写入示例,自动填入 API Key 和域名
+
+```python
+from openviking.client import SyncHTTPClient
+
+url = " `https://api.vikingdb.cn-beijing.volces.com/openviking` "
+api_key = "[TODO]your-api-key"
+agent_id = "[TODO]your-agent-id"
+
+client = SyncHTTPClient(
+ url=url,
+ api_key=api_key,
+ agent_id=agent_id,
+ timeout=120.0,
+)
+client.initialize()
+```
+
+## 步骤 3 选择 API Key
+复制页面中展示的 API Key 到你的 Agent 终端
+
+## 步骤 4 写入资源
+参考 GitHub 提供的规范写入示例,自动填入 API Key 和域名
+
+```python
+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,
+ reason=reason,
+)
+```
+
+## 步骤 5 写入记忆
+参考 GitHub 提供的记忆写入示例,自动填入 API Key 和域名
+
+```python
+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(
+ session_id,
+ "user",
+ parts=[{"type": "text", "text": text}],
+)
+result = client.commit_session(session_id)
+```
diff --git a/docs/images/agents/trae.md b/docs/images/agents/zh/trae.md
similarity index 99%
rename from docs/images/agents/trae.md
rename to docs/images/agents/zh/trae.md
index 63be76e22..5dc190881 100644
--- a/docs/images/agents/trae.md
+++ b/docs/images/agents/zh/trae.md
@@ -122,7 +122,3 @@
|连接失败 / 网络超时<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 生成,请谨慎参考)