OpenClaw + OpenViking Memory Plugin

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

⚠️ OpenClaw >= 2026.3.12 Compatibility Issue

OpenClaw 2026.3.12 and later have a known issue that causes conversations to hang after loading the plugin. This is not a bug in our plugin — the root cause is OpenClaw 3.12's slug generator (automatic conversation naming), which has a hardcoded 15s timeout that cascades when the LLM provider responds slowly, blocking the entire session initialization pipeline. Additionally, 3.12's new plugin trust mechanism may affect loading order for locally installed plugins. A separate issue: the before_agent_start auto-recall hook lacks timeout protection, which can cause the agent to hang silently (#673).

Workaround: Downgrade to 2026.3.11: npm install -g openclaw@2026.3.11

Upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547. See #591 for details.

🚀 Plugin 2.0 In Design

We are designing Plugin 2.0, rebuilt on the context-engine architecture — the best practice for integrating OpenViking with AI coding assistants. Join the discussion: #525

One-Click Installation
Manual Setup
Starting & Verification
Configuration Reference
Daily Usage
Web Console (Visualization)
Troubleshooting
Uninstallation

One-Click Installation

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

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-memory-plugin/install.sh | bash

The setup helper will walk you through:

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

Setup helper options

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)

Manual Setup

Prerequisites

Component	Version	Purpose
Python	>= 3.10	OpenViking runtime (Local mode)
Node.js	>= 22	OpenClaw runtime
Volcengine Ark API Key	—	Embedding + VLM model calls

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@2026.3.11 && openclaw onboard

Local Mode (Personal Use)

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

Step 1: Install OpenViking

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

Step 2: Run the Setup Helper

# 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-memory-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.)

Step 3: Start

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

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

Step 4: Verify

openclaw status
# Memory row should show: enabled (plugin memory-openviking)

Remote Mode (Team Sharing)

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.

Step 1: Deploy the OpenViking Service

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

Step 2: Create Team & Users

# 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"
  }'

Step 3: Configure the OpenClaw Plugin

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

Step 4: Start & Verify

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

Volcengine ECS Deployment

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.

Starting & Verification

Local Mode

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

Remote Mode

openclaw gateway restart

Check Plugin Status

openclaw status
# Memory row should show: enabled (plugin memory-openviking)

View Plugin Config

openclaw config get plugins.entries.memory-openviking.config

Configuration Reference

`~/.openviking/ov.conf` (Local Mode)

{
  "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).

Plugin Config Options

Option	Default	Description
`mode`	`remote`	`local` (start local server) or `remote` (connect to remote)
`baseUrl`	`http://127.0.0.1:1933`	OpenViking server URL (Remote mode)
`apiKey`	—	OpenViking API Key (optional)
`agentId`	auto-generated	Agent identifier, distinguishes OpenClaw instances. Auto-generates `openclaw-<hostname>-<random>` if unset
`configPath`	`~/.openviking/ov.conf`	Config file path (Local mode)
`port`	`1933`	Local server port (Local mode)
`targetUri`	`viking://user/memories`	Default memory search scope
`autoCapture`	`true`	Auto-extract memories after conversations
`captureMode`	`semantic`	Extraction mode: `semantic` (full semantic) / `keyword` (trigger-word only)
`captureMaxLength`	`24000`	Max text length per capture
`autoRecall`	`true`	Auto-recall relevant memories before conversations
`recallLimit`	`6`	Max memories injected during auto-recall
`recallScoreThreshold`	`0.01`	Minimum relevance score for recall
`ingestReplyAssist`	`true`	Add reply guidance when multi-party conversation text is detected

`~/.openclaw/openviking.env`

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

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

Daily Usage

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

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

# Disable memory
openclaw config set plugins.slots.memory none

# Re-enable memory
openclaw config set plugins.slots.memory memory-openviking

Restart the gateway after changing the memory slot.

Web Console (Visualization)

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.

Troubleshooting

Common Issues

Symptom	Cause	Fix
Conversation hangs, no response	OpenClaw >= 2026.3.12 compatibility issue	Downgrade to `2026.3.11`: `npm install -g openclaw@2026.3.11`. See #591
Agent hangs silently, no output	auto-recall missing timeout protection	Disable auto-recall temporarily: `openclaw config set plugins.entries.memory-openviking.config.autoRecall false --json`, or apply the patch in #673
Memory shows `disabled` / `memory-core`	Plugin slot not configured	`openclaw config set plugins.slots.memory memory-openviking`
`memory_store failed: fetch failed`	OpenViking not running	Check `ov.conf` and Python path; verify service is up
`health check timeout`	Port held by stale process	`lsof -ti tcp:1933 \| xargs kill -9`, then restart
`extracted 0 memories`	Wrong API Key or model name	Check `api_key` and `model` in `ov.conf`
`port occupied`	Port used by another process	Change port: `openclaw config set plugins.entries.memory-openviking.config.port 1934`
Plugin not loaded	Env file not sourced	Run `source ~/.openclaw/openviking.env` before starting
`externally-managed-environment`	Python PEP 668 restriction	Use venv or the one-click installer
`TypeError: unsupported operand type(s) for \|`	Python < 3.10	Upgrade Python to 3.10+

Viewing Logs

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

Uninstallation

lsof -ti tcp:1933 tcp:1833 tcp:18789 | xargs kill -9
npm uninstall -g openclaw && rm -rf ~/.openclaw
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)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenClaw + OpenViking Memory Plugin

Table of Contents

One-Click Installation

Method A: npm Install (Recommended, Cross-platform)

Method B: curl One-Click (Linux / macOS)

Manual Setup

Prerequisites

Local Mode (Personal Use)

Step 1: Install OpenViking

Step 2: Run the Setup Helper

Step 3: Start

Step 4: Verify

Remote Mode (Team Sharing)

Step 1: Deploy the OpenViking Service

Step 2: Create Team & Users

Step 3: Configure the OpenClaw Plugin

Step 4: Start & Verify

Volcengine ECS Deployment

Starting & Verification

Local Mode

Remote Mode

Check Plugin Status

View Plugin Config

Configuration Reference

`~/.openviking/ov.conf` (Local Mode)

Plugin Config Options

`~/.openclaw/openviking.env`

Daily Usage

Web Console (Visualization)

Troubleshooting

Common Issues

Viewing Logs

Uninstallation

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

OpenClaw + OpenViking Memory Plugin

Table of Contents

One-Click Installation

Method A: npm Install (Recommended, Cross-platform)

Method B: curl One-Click (Linux / macOS)

Manual Setup

Prerequisites

Local Mode (Personal Use)

Step 1: Install OpenViking

Step 2: Run the Setup Helper

Step 3: Start

Step 4: Verify

Remote Mode (Team Sharing)

Step 1: Deploy the OpenViking Service

Step 2: Create Team & Users

Step 3: Configure the OpenClaw Plugin

Step 4: Start & Verify

Volcengine ECS Deployment

Starting & Verification

Local Mode

Remote Mode

Check Plugin Status

View Plugin Config

Configuration Reference

~/.openviking/ov.conf (Local Mode)

Plugin Config Options

~/.openclaw/openviking.env

Daily Usage

Web Console (Visualization)

Troubleshooting

Common Issues

Viewing Logs

Uninstallation

`~/.openviking/ov.conf` (Local Mode)

`~/.openclaw/openviking.env`