OpenViking/examples/openclaw-plugin/INSTALL.md

Install OpenViking for OpenClaw

OpenViking provides long-term memory, knowledge base search, semantic retrieval, and RAG-style context for OpenClaw through the @openviking/openclaw-plugin plugin.

This guide describes the current plugin install flow. It is written for both people and automation agents.

Do Not Install The Skill By Mistake

@openviking/openclaw-plugin is an OpenClaw plugin.

Do not use this command for plugin installation:

clawhub install openviking

That command installs an AgentSkill named openviking, not the OpenClaw plugin.

Use this plugin command instead:

openclaw plugins install clawhub:@openviking/openclaw-plugin

Requirements

Component	Required
Node.js	>= 22
OpenClaw	>= 2026.5.27

The plugin connects to an existing OpenViking server. It does not start the OpenViking server for you. Start OpenViking first, keep it running, then point the plugin baseUrl at that HTTP service. The default local URL is http://127.0.0.1:1933.

OpenClaw plugin package boundaries:

• 2026.5.27 is the minimum supported OpenClaw version for the current plugin. This floor includes the July 2, 2026 OpenClaw advisory batch fixes, including GHSA-8wg3-5mcm-fjq8 and GHSA-83w9-h5wv-j9xm.
• 2026.5.3 starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
• 2026.5.4 and later stop falling back to .ts source for installed/global plugin runtime loading when compiled JavaScript is missing.
• The recommended openclaw plugins install clawhub:@openviking/openclaw-plugin path installs a published package that already includes dist/*.js.
• ov-install is the backup/source install path. Use it when ClawHub or the OpenClaw plugin manager path is unavailable/rate-limited, or when explicitly testing a source ref. For OpenClaw >= 2026.5.3, it builds the plugin during installation.

Quick check:

node -v
openclaw --version

Start OpenViking Server

For a local OpenViking server on the same machine as OpenClaw:

pip install openviking --upgrade --force-reinstall
openviking-server init
openviking-server doctor
openviking-server

openviking-server init writes the server configuration, openviking-server doctor validates local model/provider auth, and openviking-server starts the HTTP API. Keep this process running while OpenClaw uses the plugin.

To run the server in the background:

mkdir -p ~/.openviking/data/log
nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &

If OpenViking runs on another machine, start it on a reachable host/port, for example:

openviking-server --host 0.0.0.0 --port 1933

Then configure the OpenClaw plugin baseUrl to that address, such as http://your-server:1933.

Verify the server before installing or restarting the plugin:

curl http://127.0.0.1:1933/health

Recommended Install Path

Use this path for normal users, production installs, and agent-assisted installs.

1. Install The Plugin

openclaw plugins install clawhub:@openviking/openclaw-plugin

If your OpenClaw installation requires an explicit registry prefix, use:

openclaw plugins install clawhub:@openviking/openclaw-plugin

2. Configure The Plugin

For interactive human setup:

openclaw openviking setup

For non-interactive agent setup:

openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json

Example:

openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json

The setup command writes plugins.entries.openviking.config and activates plugins.slots.contextEngine=openviking.

If the OpenViking server is temporarily unreachable but you still want to save the config:

openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json

If your API key is a root key, setup may require tenant context:

openclaw openviking setup \
  --base-url <OPENVIKING_URL> \
  --api-key <ROOT_API_KEY> \
  --account-id <ACCOUNT_ID> \
  --user-id <USER_ID> \
  --json

If another context engine already owns the slot, setup will not replace it by default. To intentionally replace the current owner:

openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json

If you want assistant messages to carry a prefixed peer_id and data-plane recall/search requests to use the matching actor peer view, pass a prefix explicitly:

openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json

Configure The File Directly When The CLI Is Unavailable

If the openclaw CLI cannot run inside the container, merge the following fields into the config file that OpenClaw actually reads. Use OPENCLAW_CONFIG_PATH when it is set; otherwise the file is usually $OPENCLAW_STATE_DIR/openclaw.json (default: ~/.openclaw/openclaw.json).

{
  "plugins": {
    "entries": {
      "openviking": {
        "enabled": true,
        "config": {
          "mode": "remote",
          "baseUrl": "http://openviking:1933",
          "apiKey": "<API_KEY>",
          "peer_role": "assistant"
        }
      }
    },
    "slots": {
      "contextEngine": "openviking"
    }
  }
}

• The plugin must already be installed. Back up the file and merge these fields into the existing plugins config.

• If plugins.allow already exists, append openviking; otherwise, do not create an allowlist only for this plugin.

• contextEngine is an exclusive slot. If another context engine is configured, change it only after confirming the replacement. Root API keys also require accountId and userId in config.

• When connecting to another service from a container, use a baseUrl that is reachable from the container rather than 127.0.0.1.

• Prefer a SecretRef for apiKey instead of a plaintext string so the key is never stored inside openclaw.json. Supported shapes match OpenClaw's standard SecretRef used by LLM/TTS/MCP provider configs:

  Shape	Example	Notes
  env	{ "source": "env", "id": "OPENVIKING_API_KEY" }	Reads the named env var at plugin load time.
  file	{ "source": "file", "id": "/etc/secrets/openviking.key" }	Reads UTF-8, trims whitespace. ~ is expanded; ideal for Kubernetes secretKeyRef volumes and 0600-managed files.
  exec	not supported in the packaged plugin (marketplace install scanners block subprocess execution)	Wrap the CLI instead: OPENVIKING_API_KEY=$(op read op://vault/openviking/credential) and use env.

  A plain string (including ${ENV_VAR} interpolation) is still accepted, but only as a backward-compatibility path; in that case, restrict file permissions or provide the file through a managed Secret volume, then restart the Gateway, container, or Pod.

3. Restart OpenClaw Gateway

openclaw gateway restart

If your OpenClaw version uses a different restart command, use the equivalent gateway restart for your environment.

4. Verify

openclaw openviking status --json

Expected result:

JSON field	Expected value
configured	true
slotActive	true
health.ok	true when the server is reachable

You can also inspect the raw OpenClaw config:

openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine

plugins.slots.contextEngine should be openviking.

Agent Result Handling

Automation should prefer --json and branch on these fields:

Result	Meaning	Recommended action
success: true	Config saved and setup completed	Restart gateway, then run status
success: false, action: "slot_blocked"	Config may be saved, but another plugin owns contextEngine	Ask before rerunning with --force-slot
success: false, action: "error"	Validation failed	Show error; do not claim install succeeded
health.ok: false	Server unreachable	Check URL/server, or rerun with --allow-offline only if the user accepts
keyProbe.keyType: "root_key"	Root key needs tenant context	Rerun with --account-id and --user-id

Configuration Reference

The plugin config lives at:

plugins.entries.openviking.config

Core fields:

Field	Default	Description
mode	remote	Legacy compatibility field. Only remote mode is supported.
baseUrl	http://127.0.0.1:1933	OpenViking HTTP endpoint
apiKey	empty	OpenViking API key
peer_role	assistant	Peer identity mode: none, assistant, or person. Session messages use body peer_id; data-plane recall/search uses X-OpenViking-Actor-Peer.
peer_prefix	empty	Optional prefix for assistant peer_id / actor peer values when peer_role=assistant.
accountId	empty	Required when using a root API key
userId	empty	Required when using a root API key

Use setup for normal changes when possible:

openclaw openviking setup --reconfigure

Manual config inspection:

openclaw config get plugins.entries.openviking.config

Upgrade

openclaw plugins update openviking
openclaw gateway restart
openclaw openviking status --json

Confirm that configured and slotActive are both true.

Uninstall

openclaw plugins uninstall openviking
openclaw config set plugins.slots.contextEngine legacy
openclaw gateway restart

Current OpenClaw native uninstall does not always reset plugins.slots.contextEngine. The explicit config set step avoids leaving the slot pointed at an uninstalled plugin.

Optional Pipeline Health Check

After status passes, you can run the bundled end-to-end health check from a repository checkout:

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

This checks the Gateway to OpenViking path by injecting a real conversation and verifying capture, commit, archive, and memory extraction. See health_check_tools/HEALTHCHECK.md.

Backup Path: ov-install

ov-install is the backup path, not the primary install path. Use it when openclaw plugins install clawhub:@openviking/openclaw-plugin cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.

Try the OpenClaw plugin manager first. If that path is unavailable, run:

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

Useful backup/source flags:

Flag	Meaning
--workdir PATH	Target OpenClaw state directory
--plugin-version=REF	Plugin version: npm version, npm dist-tag, or Git ref to install
--current-version	Print the version tracked by the helper
--base-url URL	OpenViking server URL (enables non-interactive mode)
--api-key KEY	OpenViking API key
--peer-role ROLE	Peer role: none, assistant, or person
--peer-prefix PREFIX	Prefix for assistant peer_id / actor peer values
--update	Update an existing helper-managed install

For user-facing installs, use openclaw plugins install clawhub:@openviking/openclaw-plugin first. Choose ov-install only as the backup path.

Migrate From ov-install To openclaw plugin install

If you previously installed OpenViking with ov-install, follow these steps before switching to the recommended openclaw plugins install path.

Same Plugin ID (openviking, version >= 0.3.x)

The ov-install context-engine deployment writes files to ~/.openclaw/extensions/openviking/. After installing via npm, OpenClaw may still load from the old directory. Clean it up:

# Remove ov-install deployed files
rm -rf ~/.openclaw/extensions/openviking/

# Install via the OpenClaw plugin manager
openclaw plugins install clawhub:@openviking/openclaw-plugin

# Reconfigure (your existing config in openclaw.json is preserved)
openclaw openviking setup --reconfigure
openclaw gateway restart
openclaw openviking status --json

Your existing config fields such as baseUrl, apiKey, peer_role, and peer_prefix are preserved.

The plugin configuration lives under plugins.entries.openviking.config.

Get the current full plugin configuration:

openclaw config get plugins.entries.openviking.config

Configuration Parameters

The plugin connects to an existing remote OpenViking server.

Parameter	Default	Meaning
baseUrl	http://127.0.0.1:1933	Remote OpenViking HTTP endpoint
apiKey	empty	Optional OpenViking API key
peer_role	assistant	Peer identity mode: none, assistant, or person; session messages use body peer_id, while data-plane recall/search uses X-OpenViking-Actor-Peer
peer_prefix	empty	Optional prefix for assistant peer_id / actor peer values when peer_role=assistant

Common settings:

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.peer_role assistant
openclaw config set plugins.entries.openviking.config.peer_prefix your-prefix

Start

After installation (if you skipped reconfigure above):

openclaw gateway restart
openclaw openviking status --json

Old Plugin ID (memory-openviking, version < 0.3.x)

The old memory plugin used a different plugin ID and slot:

# Uninstall old plugin
openclaw plugins uninstall memory-openviking 2>/dev/null || true

# Clean up old slot and files
openclaw config set plugins.slots.memory none
rm -rf ~/.openclaw/extensions/memory-openviking/

# Install new plugin
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
openclaw gateway restart
openclaw openviking status --json

Or use the cleanup script:

bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh

See also: INSTALL-ZH.md, INSTALL-AGENT.md, and docs/openviking-tos-install-guide.md.