OpenClaw + OpenViking Context-Engine Plugin

Use OpenViking as the long-term memory backend for OpenClaw. In OpenClaw, this plugin is registered as the openviking context engine. Once installed, OpenClaw will automatically remember important information from conversations and recall relevant context before responding.

ℹ️ Historical Compatibility Note

Legacy OpenViking/OpenClaw integrations had a known issue around OpenClaw 2026.3.12 where conversations could hang after the plugin loaded. That issue affected the legacy plugin path; the current context-engine Plugin 2.0 described in this document is not affected, so new installations do not need to downgrade OpenClaw for this reason. Plugin 2.0 is also not backward-compatible with the legacy memory-openviking plugin and its configuration, so upgrades must replace the old setup instead of mixing the two versions. Plugin 2.0 also depends on OpenClaw's context-engine capability and does not support older OpenClaw releases; upgrade OpenClaw first before using this plugin. If you are troubleshooting a legacy deployment, see #591 and upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.

🚀 Plugin 2.0 (Context-Engine Architecture)

This document covers the current OpenViking Plugin 2.0 built on the context-engine architecture, which is the recommended integration path for AI coding assistants. For design background and earlier discussion, see: https://github.com/volcengine/OpenViking/discussions/525

• One-Click Installation
• Manual Setup
  • Prerequisites
  • Local Mode (Personal Use)
  • Remote Mode (Team Sharing)
  • Volcengine ECS Deployment
• Starting & Verification
• Configuration Reference
• Daily Usage
• Web Console (Visualization)
• Troubleshooting
• Uninstallation

For users who want a quick local experience. The setup helper handles environment detection, dependency installation, and config file generation automatically.

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

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

The setup helper will walk you through:

1. Environment check — Detects Python >= 3.10, Node.js, cmake, etc.
2. Select OpenClaw instance — If multiple instances are installed locally, lists them for you to choose
3. Select deployment mode — Local or Remote (see below)
4. Generate config — Writes ~/.openviking/ov.conf and ~/.openclaw/openviking.env automatically

ov-install [options]

  -y, --yes              Non-interactive, use defaults
  --workdir <path>       OpenClaw config directory (default: ~/.openclaw)
  -h, --help             Show help

Env vars:
  OPENVIKING_PYTHON       Python path
  OPENVIKING_CONFIG_FILE  ov.conf path
  OPENVIKING_REPO         Local OpenViking repo path
  OPENVIKING_ARK_API_KEY  Volcengine API Key (skip prompt in -y mode)

python3 --version   # >= 3.10
node -v              # >= v22
openclaw --version   # installed

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

The simplest option — nearly zero configuration. The memory service runs alongside your OpenClaw agent locally. You only need a Volcengine Ark API Key.

python3 -m pip install openviking --upgrade

Verify: python3 -c "import openviking; print('ok')"

Hit externally-managed-environment? Use the one-click installer (handles venv automatically) or create one manually:

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

# Method A: npm install (recommended, cross-platform)
npm install -g openclaw-openviking-setup-helper
ov-install

# Method B: curl one-click (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/install.sh | bash

Select local mode, keep defaults, and enter your Ark API Key.

Generated config files:

• ~/.openviking/ov.conf — OpenViking service config
• ~/.openclaw/openviking.env — Environment variables (Python path, etc.)

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

In Local mode you must source the env file first — the plugin auto-starts an OpenViking subprocess.

openclaw status
# ContextEngine row should show: enabled (plugin openviking)

For multiple OpenClaw instances or team use. Deploy a standalone OpenViking service that is shared across agents. No Python/OpenViking needed on the client side.

Edit ~/.openviking/ov.conf — set root_api_key to enable multi-tenancy:

{
  "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
  }
}

Start the service:

openviking-server

# Create team + admin
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"
  }'

# Add member
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

# Remote mode — no env sourcing needed
openclaw gateway restart
openclaw status

Deploy OpenClaw + OpenViking on Volcengine ECS. See Volcengine docs for details.

ECS instances restrict global pip installs under root to protect system Python. Create a venv first.

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

# 2. Load environment
source /root/.openclaw/openviking.env

# 3. Start OpenViking server
python -m openviking.server.bootstrap

# 4. Start Web Console (ensure security group allows TCP 8020 inbound)
python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933

Access http://<public-ip>:8020 to use the Web Console.

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

openclaw gateway restart

openclaw status
# ContextEngine row should show: 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: When set, all HTTP requests must include the X-API-Key header. Defaults to null in Local mode (auth disabled).

Auto-generated by the setup helper, stores environment variables like the Python path:

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

# Start (Local mode — source env first)
source ~/.openclaw/openviking.env && openclaw gateway

# Start (Remote mode — no env needed)
openclaw gateway

# Disable the context engine
openclaw config set plugins.slots.contextEngine legacy

# Re-enable OpenViking as the context engine
openclaw config set plugins.slots.contextEngine openviking

Restart the gateway after changing the context-engine slot.

OpenViking provides a Web Console for debugging and inspecting stored memories.

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

Open http://127.0.0.1:8020 in your browser.

# OpenViking logs
cat ~/.openviking/data/log/openviking.log

# OpenClaw gateway logs
cat ~/.openclaw/logs/gateway.log
cat ~/.openclaw/logs/gateway.err.log

# Check if OpenViking process is alive
lsof -i:1933

# Quick connectivity check
curl http://localhost:1933
# Expected: {"detail":"Not Found"}

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

See also: INSTALL-ZH.md (中文详细安装指南) · INSTALL.md (English Install Guide) · INSTALL-AGENT.md (Agent Install Guide)