OpenClaw + OpenViking 上下文引擎插件

使用 OpenViking 作为 OpenClaw 的长期记忆后端。在 OpenClaw 中，此插件注册为 openviking 上下文引擎。安装后，OpenClaw 将自动记忆对话中的重要信息，并在响应前召回相关上下文。

ℹ️ 历史兼容性说明

传统的 OpenViking/OpenClaw 集成在 OpenClaw 2026.3.12 附近存在一个已知问题，即对话可能在插件加载后挂起。 该问题仅影响传统插件路径；本文档中描述的当前上下文引擎插件 2.0 不受此影响，因此新安装无需因此降级 OpenClaw。 插件 2.0 也不向后兼容传统的 memory-openviking 插件及其配置，因此升级必须替换旧设置，而不是混合使用两个版本。 插件 2.0 还依赖于 OpenClaw 的上下文引擎功能，不支持旧版 OpenClaw；使用此插件前请先升级 OpenClaw。 如果您正在排查传统部署的问题，请参阅 #591 和上游修复 PR：openclaw/openclaw#34673、openclaw/openclaw#33547。

🚀 插件 2.0（上下文引擎架构）

本文档涵盖当前基于上下文引擎架构的 OpenViking 插件 2.0，这是 AI 编码助手的推荐集成路径。 有关设计背景和早期讨论，请参阅： https://github.com/volcengine/OpenViking/discussions/525

• 一键安装
• 手动设置
  • 前置要求
  • 本地模式（个人使用）
  • 远程模式（团队共享）
  • 火山引擎 ECS 部署
• 启动与验证
• 配置参考
• 日常使用
• Web 控制台（可视化）
• 故障排除
• 卸载

适用于想要快速获得本地体验的用户。安装助手会自动处理环境检测、依赖安装和配置文件生成。

npm install -g openclaw-openviking-setup-helper
ov-install

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash

安装助手将引导您完成：

1. 环境检查 — 检测 Python >= 3.10、Node.js、cmake 等
2. 选择 OpenClaw 实例 — 如果本地安装了多个实例，列出供您选择
3. 选择部署模式 — 本地或远程（见下文）
4. 生成配置 — 自动写入 ~/.openviking/ov.conf 和 ~/.openclaw/openviking.env

ov-install [options]

  -y, --yes              非交互式，使用默认值
  --workdir <path>       OpenClaw 配置目录（默认：~/.openclaw）
  -h, --help             显示帮助

环境变量：
  OPENVIKING_PYTHON       Python 路径
  OPENVIKING_CONFIG_FILE  ov.conf 路径
  OPENVIKING_REPO         本地 OpenViking 仓库路径
  OPENVIKING_ARK_API_KEY  火山引擎 API Key（-y 模式下跳过提示）

python3 --version   # >= 3.10
node -v              # >= v22
openclaw --version   # 已安装

• Python: https://www.python.org/downloads/
• Node.js: https://nodejs.org/
• OpenClaw: npm install -g openclaw && openclaw onboard

最简单的选项 — 几乎无需配置。记忆服务与您的OpenClaw一起在本地运行。您只需要一个火山引擎Ark API Key。

python3 -m pip install openviking --upgrade

验证：python3 -c "import openviking; print('ok')"

遇到 externally-managed-environment？使用一键安装程序（自动处理 venv）或手动创建一个：

python3 -m venv ~/.openviking/venv && ~/.openviking/venv/bin/pip install openviking

# 方法 A：npm 安装（推荐，跨平台）
npm install -g openclaw-openviking-setup-helper
ov-install

# 方法 B：curl 一键安装（Linux / macOS）
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash

选择 本地 模式，保持默认设置，并输入您的 Ark API Key。

生成的配置文件：

• ~/.openviking/ov.conf — OpenViking 服务配置
• ~/.openclaw/openviking.env — 环境变量（Python 路径等）

source ~/.openclaw/openviking.env && openclaw gateway restart

在本地模式下，您必须先 source 环境文件 — 插件会自动启动一个 OpenViking子进程。

openclaw status
# ContextEngine 行应显示：enabled (plugin openviking)

适用于多个OpenClaw实例或团队使用。部署一个独立的OpenViking服务，供多个agents共享。客户端无需 Python/OpenViking。

编辑 ~/.openviking/ov.conf — 设置 root_api_key 以启用多租户：

{
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "root_api_key": "<your-root-api-key>",
    "cors_origins": ["*"]
  },
  "storage": {
    "workspace": "~/.openviking/data",
    "vectordb": {
      "name": "context",
      "backend": "local"
    },
    "agfs": {
      "log_level": "warn",
      "backend": "local"
    }
  },
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "<your-ark-api-key>",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "api_key": "<your-ark-api-key>",
    "model": "doubao-seed-2-0-pro-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "temperature": 0.1,
    "max_retries": 3
  }
}

启动服务：

openviking-server

# 创建团队 + 管理员
curl -X POST http://localhost:1933/api/v1/admin/accounts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <root-api-key>" \
  -d '{
    "account_id": "my-team",
    "admin_user_id": "admin"
  }'

# 添加成员
curl -X POST http://localhost:1933/api/v1/admin/accounts/my-team/users \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <root-or-admin-key>" \
  -d '{
    "user_id": "xiaomei",
    "role": "user"
  }'

openclaw plugins enable openviking
openclaw config set gateway.mode local
openclaw config set plugins.slots.contextEngine openviking
openclaw config set plugins.entries.openviking.config.mode remote
openclaw config set plugins.entries.openviking.config.baseUrl "http://your-server:1933"
openclaw config set plugins.entries.openviking.config.apiKey "<user-api-key>"
openclaw config set plugins.entries.openviking.config.agentId "<agent-id>"
openclaw config set plugins.entries.openviking.config.autoRecall true --json
openclaw config set plugins.entries.openviking.config.autoCapture true --json

# 远程模式 — 无需 source 环境文件
openclaw gateway restart
openclaw status

在火山引擎 ECS 上部署 OpenClaw + OpenViking。详见 火山引擎文档。

ECS 实例限制在 root 下全局 pip 安装以保护系统 Python。请先创建 venv。

# 1. 安装
npm install -g openclaw-openviking-setup-helper
ov-install

# 2. 加载环境
source /root/.openclaw/openviking.env

# 3. 启动 OpenViking 服务器
python -m openviking.server.bootstrap

# 4. 启动 Web 控制台（确保入站安全组允许 TCP 8020）
python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933

访问 http://<public-ip>:8020 使用 Web 控制台。

source ~/.openclaw/openviking.env && openclaw gateway restart

openclaw gateway restart

openclaw status
# ContextEngine 行应显示：enabled (plugin openviking)

openclaw config get plugins.entries.openviking.config

{
  "root_api_key": null,
  "server": { "host": "127.0.0.1", "port": 1933 },
  "storage": {
    "workspace": "~/.openviking/data",
    "vectordb": { "backend": "local" },
    "agfs": { "backend": "local", "port": 1833 }
  },
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "<your-ark-api-key>",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "api_key": "<your-ark-api-key>",
    "model": "doubao-seed-2-0-pro-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  }
}

root_api_key：设置后，所有 HTTP 请求必须包含 X-API-Key 头。本地模式下默认为 null（禁用身份验证）。

由安装助手自动生成，存储环境变量（如 Python 路径）：

export OPENVIKING_PYTHON='/usr/local/bin/python3'

# 启动（本地模式 — 先 source 环境文件）
source ~/.openclaw/openviking.env && openclaw gateway

# 启动（远程模式 — 无需环境文件）
openclaw gateway

# 禁用上下文引擎
openclaw config set plugins.slots.contextEngine legacy

# 重新启用 OpenViking 作为上下文引擎
openclaw config set plugins.slots.contextEngine openviking

更改上下文引擎插槽后请重启网关。

OpenViking 提供 Web 控制台用于调试和检查存储的记忆。

python -m openviking.console.bootstrap \
  --host 127.0.0.1 \
  --port 8020 \
  --openviking-url http://127.0.0.1:1933 \
  --write-enabled

在浏览器中打开 http://127.0.0.1:8020。

# OpenViking 日志
cat ~/.openviking/data/log/openviking.log

# OpenClaw 网关日志
cat ~/.openclaw/logs/gateway.log
cat ~/.openclaw/logs/gateway.err.log

# 检查 OpenViking 进程是否存活
lsof -i:1933

# 快速连接检查
curl http://localhost:1933
# 预期：{"detail":"Not Found"}

lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9
python3 -m pip uninstall openviking -y && rm -rf ~/.openviking

另见： INSTALL-ZH.md（中文详细安装指南）· INSTALL.md（英文安装指南）· INSTALL-AGENT.md（Agent 安装指南）