ContextQMD
Back to Openviking

OpenClaw Plugin

docs/en/agent-integrations/03-openclaw.md

0.3.197.3 KB
Original Source

OpenClaw Plugin

Use OpenViking as the long-term memory backend for OpenClaw. After installation, OpenClaw will automatically remember important facts from conversations and recall relevant context before replying.

This plugin is registered as the openviking context engine — it owns long-term memory retrieval, session archiving, archive summaries, and memory extraction across the OpenClaw lifecycle.

Source: examples/openclaw-plugin

Prerequisites

ComponentRequired Version
Node.js>= 22
OpenClaw>= 2026.4.8

The plugin connects to an existing OpenViking server. Make sure you have one reachable over HTTP — see the Deployment Guide. Quick check:

bash
node -v
openclaw --version

Upgrading from the legacy memory-openviking plugin? It's not compatible with the new openviking plugin. Run the cleanup script first:

bash
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh
bash cleanup-memory-openviking.sh

Install

bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --json
openclaw gateway restart
openclaw openviking status --json

The setup wizard writes configuration to $OPENCLAW_STATE_DIR/openclaw.json (default: ~/.openclaw/openclaw.json) and activates the context-engine slot.

<details> <summary><b>Alternative: Install via <code>ov-install</code></b></summary>

If ClawHub is unavailable (rate-limited, offline, or auth issues), use the ov-install backup path:

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

Common variants:

bash
# Target a specific OpenClaw data directory
ov-install --workdir ~/.openclaw-second

# Pin to a specific plugin release
ov-install --base-url http://your-server:1933 --plugin-version=0.2.9

To upgrade later:

bash
npm install -g openclaw-openviking-setup-helper@latest && ov-install --base-url http://your-server:1933

ov-install parameters

ParameterMeaning
--workdir PATHTarget OpenClaw data directory (default ~/.openclaw)
--plugin-version=VERPlugin version: npm version (e.g. 2026.5.8), npm dist-tag (e.g. dev), or Git ref (e.g. v0.3.16, main). Default: npm latest
--plugin-source=npm|githubPlugin download source (default npm)
--plugin-package=NAMEnpm plugin package name (default @openviking/openclaw-plugin)
--github-repo owner/repoUse a different GitHub repo for plugin files (default volcengine/OpenViking)
--current-versionPrint the currently installed plugin version and exit
--updateUpgrade only the plugin to the requested --plugin-version
--rollbackRoll back the last plugin upgrade
--uninstallUninstall the plugin
--base-url URLOpenViking server URL
--api-key KEYOpenViking API key
--agent-prefix PREFIXAgent prefix for memory namespace isolation
--account-id IDMulti-tenant account ID (root-key deployments only)
--user-id IDMulti-tenant user ID (root-key deployments only)
--force-slotForce-replace the contextEngine slot if another plugin owns it
--allow-offlineSave config even if the OpenViking server is unreachable
</details>

Plugin configuration

The plugin configuration lives under plugins.entries.openviking.config. Setup usually writes this for you — manual edits are only needed if you change servers later.

bash
openclaw config get plugins.entries.openviking.config
ParameterDefaultMeaning
baseUrlhttp://127.0.0.1:1933Remote OpenViking HTTP endpoint
apiKeyemptyOptional OpenViking API key
agent_prefixdefaultAgent prefix used by this OpenClaw instance on the server

Common settings:

bash
openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
openclaw config set plugins.entries.openviking.config.apiKey your-api-key
openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix

Verify

For a one-shot health check covering plugin registration, server connectivity, and version compatibility, run:

bash
openclaw openviking status

For automation, append --json to openclaw openviking status to get a machine-readable result. openclaw openviking setup also supports --json when used with --base-url.

Or check the underlying signals manually. The plugin owns the contextEngine slot:

bash
openclaw config get plugins.slots.contextEngine

If the output is openviking, the plugin is active.

Follow OpenClaw logs for the registration message:

bash
openclaw logs --follow
# expect: openviking: registered context-engine

OpenViking server log (default location):

bash
cat ~/.openviking/data/log/openviking.log

Currently-installed plugin version:

bash
ov-install --current-version

Pipeline health check (optional)

For an end-to-end sanity check (Gateway → OpenViking pipeline), run:

bash
python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py

This script injects a real conversation through Gateway and verifies from the OpenViking side that the session was captured, committed, archived, and had memories extracted. See HEALTHCHECK.md for details.

Uninstall

bash
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/uninstall-openclaw-plugin.sh -o uninstall-openviking.sh
bash uninstall-openviking.sh

For a non-default OpenClaw state directory, append --workdir ~/.openclaw-second.

See also