Skip to content

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

docs: clarify OpenCode integration setup (#3053)

Qin Haojiea8b9ff57cdfb
diff --git a/docs/en/agent-integrations/06-mcp-clients.md b/docs/en/agent-integrations/06-mcp-clients.md
index 7f3fcbdb4..4612f1629 100644
--- a/docs/en/agent-integrations/06-mcp-clients.md
+++ b/docs/en/agent-integrations/06-mcp-clients.md
@@ -37,10 +37,30 @@ Add `--scope user` to make the config global across all projects.
> For auto-recall and auto-capture without manual tool calls, use the [Claude Code Memory Plugin](./02-claude-code.md) instead.
-### Trae / Cursor / ChatGPT / Codex / OpenCode
+### Trae / Cursor / ChatGPT / Codex
Standard `mcpServers` config as shown above — all verified with API key auth.
+### OpenCode
+
+Use OpenCode's native `mcp` config in `~/.config/opencode/opencode.json`:
+
+```json
+{
+ "mcp": {
+ "openviking": {
+ "type": "remote",
+ "url": "https://your-server.com/mcp",
+ "enabled": true,
+ "oauth": false,
+ "headers": {
+ "Authorization": "Bearer your-api-key-here"
+ }
+ }
+ }
+}
+```
+
### Claude Desktop / Claude.ai (OAuth)
These clients require OAuth 2.1 — API keys cannot be passed directly. OpenViking ships a native OAuth 2.1 implementation, so no external proxy is needed.
diff --git a/docs/en/agent-integrations/08-community-plugins.md b/docs/en/agent-integrations/08-community-plugins.md
index 8af5c492c..4cfbc8a18 100644
--- a/docs/en/agent-integrations/08-community-plugins.md
+++ b/docs/en/agent-integrations/08-community-plugins.md
@@ -48,15 +48,22 @@ curl http://localhost:1933/health
### Install
-The published npm package is `@openviking/opencode-plugin`; verify availability with `npm view @openviking/opencode-plugin version`. For package installs, add the plugin to `~/.config/opencode/opencode.json`. If package installation is not available in your environment yet, use the source install path below.
+The published npm package is `@openviking/opencode-plugin`. For a first-time OpenCode config:
-```json
+```bash
+mkdir -p ~/.config/opencode
+cat > ~/.config/opencode/opencode.json <<'JSON'
{
+ "$schema": "https://opencode.ai/config.json",
"plugin": ["@openviking/opencode-plugin"]
}
+JSON
+opencode
```
-For development, debugging, or PR testing, install the plugin from this repository instead:
+If `~/.config/opencode/opencode.json` already exists, do not overwrite it; only merge `"@openviking/opencode-plugin"` into the existing `plugin` array. OpenCode downloads the npm package at startup.
+
+If package installation is not available in your environment, use the source install path below.
```bash
git clone https://github.com/volcengine/OpenViking.git
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
index f1f0a3597..ff1fc7913 100644
--- a/docs/en/guides/06-mcp-integration.md
+++ b/docs/en/guides/06-mcp-integration.md
@@ -22,7 +22,7 @@ The following platforms have been successfully integrated with OpenViking MCP:
| **Trae** | Standard MCP config |
| **Cursor** | Standard MCP config |
| **ChatGPT & Codex** | Standard MCP config |
-| **OpenCode** | Standard MCP config |
+| **OpenCode** | Native OpenCode `mcp` config |
| **Manus** | Standard MCP config |
| **Claude.ai / Claude Desktop** | Native OAuth 2.1 (see [11-oauth](11-oauth.md)) |
@@ -82,6 +82,26 @@ Or in `.mcp.json`:
Add `--scope user` to make the config global (shared across all projects).
+### OpenCode
+
+Configure `~/.config/opencode/opencode.json`:
+
+```json
+{
+ "mcp": {
+ "openviking": {
+ "type": "remote",
+ "url": "https://your-server.com/mcp",
+ "enabled": true,
+ "oauth": false,
+ "headers": {
+ "Authorization": "Bearer your-api-key-here"
+ }
+ }
+ }
+}
+```
+
### Claude.ai / Claude Desktop (OAuth)
These clients only accept OAuth 2.1 — API Keys cannot be passed directly.
diff --git a/docs/images/agents/en/opencode.md b/docs/images/agents/en/opencode.md
index d4622fb82..2e554ca21 100644
--- a/docs/images/agents/en/opencode.md
+++ b/docs/images/agents/en/opencode.md
@@ -24,15 +24,22 @@ For remote or multi-tenant deployments, prepare an OpenViking API key.
## Step 2: Install the plugin
-The published npm package is `@openviking/opencode-plugin`; verify availability with `npm view @openviking/opencode-plugin version`. For package installs, add the plugin to `~/.config/opencode/opencode.json`. If package installation is not available in your environment yet, use the source install path below.
+The published npm package is `@openviking/opencode-plugin`. For a first-time OpenCode config:
-```json
+```bash
+mkdir -p ~/.config/opencode
+cat > ~/.config/opencode/opencode.json <<'JSON'
{
+ "$schema": "https://opencode.ai/config.json",
"plugin": ["@openviking/opencode-plugin"]
}
+JSON
+opencode
```
-For development, debugging, or PR testing, copy the plugin from the OpenViking repository:
+If `~/.config/opencode/opencode.json` already exists, do not overwrite it; only merge `"@openviking/opencode-plugin"` into the existing `plugin` array. OpenCode downloads the npm package at startup.
+
+If package installation is not available in your environment, use the source install path below.
```bash
git clone https://github.com/volcengine/OpenViking.git
diff --git a/docs/images/agents/zh/opencode.md b/docs/images/agents/zh/opencode.md
index 884a0279d..72108c902 100644
--- a/docs/images/agents/zh/opencode.md
+++ b/docs/images/agents/zh/opencode.md
@@ -25,15 +25,22 @@ curl http://localhost:1933/health
## 步骤 2:安装插件
-已发布的 npm 包是 `@openviking/opencode-plugin`,可以用 `npm view @openviking/opencode-plugin version` 验证当前可用版本。使用 package 安装时,把插件加入 `~/.config/opencode/opencode.json`。如果当前环境还不能通过 package 安装,请使用下面的源码安装路径。
+已发布的 npm 包是 `@openviking/opencode-plugin`。首次配置 OpenCode 时:
-```json
+```bash
+mkdir -p ~/.config/opencode
+cat > ~/.config/opencode/opencode.json <<'JSON'
{
+ "$schema": "https://opencode.ai/config.json",
"plugin": ["@openviking/opencode-plugin"]
}
+JSON
+opencode
```
-开发、调试或 PR 测试时,可以从 OpenViking 仓库复制插件:
+已有 `~/.config/opencode/opencode.json` 时,不要覆盖原文件;只把 `"@openviking/opencode-plugin"` 合并到已有的 `plugin` 数组。OpenCode 启动时会自动下载这个 npm 包。
+
+如果当前环境不能通过 package 安装,请使用下面的源码安装路径。
```bash
git clone https://github.com/volcengine/OpenViking.git
diff --git a/docs/zh/agent-integrations/06-mcp-clients.md b/docs/zh/agent-integrations/06-mcp-clients.md
index ca567a310..68e4549d5 100644
--- a/docs/zh/agent-integrations/06-mcp-clients.md
+++ b/docs/zh/agent-integrations/06-mcp-clients.md
@@ -37,10 +37,30 @@ claude mcp add --transport http openviking \
> 如果你需要免工具调用的自动召回与自动捕获,请使用 [Claude Code 记忆插件](./02-claude-code.md)。
-### Trae / Cursor / ChatGPT / Codex / OpenCode
+### Trae / Cursor / ChatGPT / Codex
使用上面的标准 `mcpServers` 配置即可——均已通过 API Key 鉴权验证。
+### OpenCode
+
+在 `~/.config/opencode/opencode.json` 中使用 OpenCode 原生 `mcp` 配置:
+
+```json
+{
+ "mcp": {
+ "openviking": {
+ "type": "remote",
+ "url": "https://your-server.com/mcp",
+ "enabled": true,
+ "oauth": false,
+ "headers": {
+ "Authorization": "Bearer your-api-key-here"
+ }
+ }
+ }
+}
+```
+
### Claude Desktop / Claude.ai (OAuth)
这些客户端要求 OAuth 2.1——无法直接传 API Key。OpenViking 自带原生 OAuth 2.1 实现,无需外部代理。
diff --git a/docs/zh/agent-integrations/08-community-plugins.md b/docs/zh/agent-integrations/08-community-plugins.md
index 9c4a5108d..7692dc383 100644
--- a/docs/zh/agent-integrations/08-community-plugins.md
+++ b/docs/zh/agent-integrations/08-community-plugins.md
@@ -48,15 +48,22 @@ curl http://localhost:1933/health
### 安装
-已发布的 npm 包是 `@openviking/opencode-plugin`,可以用 `npm view @openviking/opencode-plugin version` 验证当前可用版本。使用 package 安装时,把插件加入 `~/.config/opencode/opencode.json`。如果当前环境还不能通过 package 安装,请使用下面的源码安装路径。
+已发布的 npm 包是 `@openviking/opencode-plugin`。首次配置 OpenCode 时:
-```json
+```bash
+mkdir -p ~/.config/opencode
+cat > ~/.config/opencode/opencode.json <<'JSON'
{
+ "$schema": "https://opencode.ai/config.json",
"plugin": ["@openviking/opencode-plugin"]
}
+JSON
+opencode
```
-开发、调试或 PR 测试时,可以从本仓库源码安装:
+已有 `~/.config/opencode/opencode.json` 时,不要覆盖原文件;只把 `"@openviking/opencode-plugin"` 合并到已有的 `plugin` 数组。OpenCode 启动时会自动下载这个 npm 包。
+
+如果当前环境不能通过 package 安装,请使用下面的源码安装路径。
```bash
git clone https://github.com/volcengine/OpenViking.git
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
index 58ab81f5c..ec3ba88ce 100644
--- a/docs/zh/guides/06-mcp-integration.md
+++ b/docs/zh/guides/06-mcp-integration.md
@@ -22,7 +22,7 @@ MCP 端点位于 `http://<server>:1933/mcp`,与 REST API 同进程、同端口
| **Trae** | 标准 MCP 配置 |
| **Cursor** | 标准 MCP 配置 |
| **ChatGPT & Codex** | 标准 MCP 配置 |
-| **OpenCode** | 标准 MCP 配置 |
+| **OpenCode** | OpenCode 原生 `mcp` 配置 |
| **Manus** | 标准 MCP 配置 |
| **Claude.ai / Claude Desktop** | 原生 OAuth 2.1(见 [11-oauth](11-oauth.md)) |
@@ -82,6 +82,26 @@ claude mcp add --transport http openviking \
加 `--scope user` 可将配置设为全局(所有项目共享)。
+### OpenCode
+
+在 `~/.config/opencode/opencode.json` 中配置:
+
+```json
+{
+ "mcp": {
+ "openviking": {
+ "type": "remote",
+ "url": "https://your-server.com/mcp",
+ "enabled": true,
+ "oauth": false,
+ "headers": {
+ "Authorization": "Bearer your-api-key-here"
+ }
+ }
+ }
+}
+```
+
### Claude.ai / Claude Desktop(OAuth)
这些客户端只接受 OAuth 2.1,不接受 API Key。OpenViking 已经原生实现 OAuth 2.1(DCR + PKCE + opaque token,SQLite 后端,配合 Studio consent 授权页),不再需要外部代理。