OpenViking/examples/openclaw-plugin/INSTALL-AGENT.md

OpenViking Plugin Agent Install Guide

This guide is for AI agents and operator automation. Prefer deterministic commands, parse JSON output, and ask the user only when a choice changes the outcome.

User-facing docs:

• INSTALL.md
• INSTALL-ZH.md

Identity

This package is the OpenClaw plugin @openviking/openclaw-plugin.

User intent	Command
Fresh install, latest	openclaw plugins install clawhub:@openviking/openclaw-plugin
Upgrade plugin to latest	openclaw plugins install clawhub:@openviking/openclaw-plugin
Install or upgrade a specific release	Use the published ClawHub package selector if available; otherwise ask before using backup ov-install --plugin-version=<REF>
Upgrade only the plugin	openclaw plugins install clawhub:@openviking/openclaw-plugin
Show installed plugins	openclaw plugins list
Backup install when ClawHub is unavailable	npx -y openclaw-openviking-setup-helper@latest --base-url <URL> [--api-key <KEY>]
Operate on a specific OpenClaw instance	add --workdir <path>
Start missing OpenViking server	openviking-server init && openviking-server doctor && openviking-server

Do not install it with:

clawhub install openviking

That installs an AgentSkill, not the plugin. The plugin install command is:

openclaw plugins install clawhub:@openviking/openclaw-plugin

Required Inputs

Before setup, determine:

Input	Required	How to get it
OpenViking base URL	Yes	Ask user or read OPENVIKING_BASE_URL
API key	Usually	Ask user or read OPENVIKING_API_KEY
Account ID	Only for root API keys	Ask user if setup reports root-key tenant context is needed
User ID	Only for root API keys	Ask user if setup reports root-key tenant context is needed
Slot replacement approval	Only if another context engine owns the slot	Ask user before using --force-slot

Never silently replace another context engine.

Primary Workflow

Use this workflow for normal installs and upgrades from published packages.

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

If the registry prefix is required:

openclaw plugins install clawhub:@openviking/openclaw-plugin

Setup JSON Contract

Run setup with --json whenever possible:

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

Branch on the result:

JSON result	Meaning	Agent action
success: true	Setup completed	Restart gateway, then run status
success: false, action: "slot_blocked"	Another plugin owns plugins.slots.contextEngine	Ask user before rerunning with --force-slot
success: false, action: "error"	Validation failed	Report error; do not continue as success
health.ok: false	Server unreachable	Check URL/service; use --allow-offline only with user approval
keyProbe.keyType: "root_key"	Root key requires tenant fields	Rerun with --account-id <ACCOUNT_ID> --user-id <USER_ID>
health.compatibility: "server_too_old"	Server may not support plugin features	Warn user and recommend server upgrade
health.compatibility: "server_too_new"	Plugin may be too old	Warn user and recommend plugin upgrade

Root-key retry:

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

Custom agent routing prefix (optional; only when the user explicitly requests a prefix):

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

Slot replacement retry, only after user approval:

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

Offline config save, only after user approval:

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

Status JSON Contract

After restart, run:

openclaw openviking status --json

Ready state:

{
  "configured": true,
  "slotActive": true
}

Also inspect:

Field	Use
health.ok	Confirms server reachability
health.version	Records server version
health.compatibility	Determines whether to warn
config.hasApiKey	Confirms whether an API key was saved
config.peer_prefix	Confirms configured peer prefix when present

Environment Detection

Check tools:

node -v
openclaw --version

Requirements:

• Node.js >= 22
• OpenClaw >= 2026.5.27

Version boundaries:

• 2026.5.27 is the minimum supported OpenClaw version for the current @openviking/openclaw-plugin plugin.
• 2026.5.3 starts requiring compiled JavaScript runtime output during package install when a plugin package declares TypeScript entries.
• 2026.5.4 and later no longer fall back to .ts source for installed/global plugin runtime loading when the compiled JavaScript output is missing; the plugin may be skipped.
• Published ClawHub packages are built before release and include dist/*.js, so normal users do not need to build locally.
• ov-install is the backup/source install path. Use it only after the OpenClaw plugin manager or ClawHub path is unavailable/rate-limited, or when the user explicitly asks to install a source ref. For OpenClaw >= 2026.5.3, it builds the plugin during installation.

3. Detect or start OpenViking server

The OpenClaw plugin only connects to an OpenViking HTTP server. It does not start the server.

Check the default local server first:

curl -fsS http://127.0.0.1:1933/health

If no OpenViking server is running and the user wants a local server:

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

Keep openviking-server running while OpenClaw uses the plugin. Use http://127.0.0.1:1933 as the plugin baseUrl for the default local setup.

For a remote server, confirm the reachable URL with the user and use that URL as baseUrl.

If OpenClaw is missing, tell the user to install and initialize OpenClaw:

npm install -g openclaw
openclaw onboard

4. Detect existing install state

If the user has multiple OpenClaw state directories, ask which one to operate on before changing config.

Existing State Detection

Try status first:

openclaw openviking status --json

If the command is unavailable, install the plugin first. If it returns configured: true and slotActive: true, do not reinstall unless the user requested upgrade or reconfigure.

Manual inspection:

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

Standard Operations

Fresh install:

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

Reconfigure:

openclaw openviking setup --reconfigure
openclaw gateway restart
openclaw openviking status --json

Upgrade:

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

Uninstall:

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

Native uninstall may not reset plugins.slots.contextEngine. Always run the explicit config set step after uninstall.

Config Fields

Config path:

plugins.entries.openviking.config

Core fields:

Field	Meaning
mode	Legacy compatibility field. Expected value: remote.
baseUrl	OpenViking HTTP endpoint
apiKey	OpenViking API key
peer_prefix	Optional; prefix for OpenClaw agent IDs when set. Interactive setup accepts only letters, digits, _, and -. If unset, the plugin follows session agent IDs.
accountId	Required for root API keys
userId	Required for root API keys

Verification

Quick verification:

openclaw openviking status --json

Manual verification:

openclaw config get plugins.slots.contextEngine
openclaw config get plugins.entries.openviking.config
openclaw logs --follow

Expected log signal:

openviking: registered context-engine

Optional end-to-end health check from a repository checkout:

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

Migrate From ov-install

If ov-install was previously used, clean up before switching to openclaw plugins install:

Same plugin ID (openviking, >= 0.3.x):

rm -rf ~/.openclaw/extensions/openviking/
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --reconfigure
openclaw gateway restart
openclaw openviking status --json

Old plugin ID (memory-openviking, < 0.3.x):

openclaw plugins uninstall memory-openviking 2>/dev/null || true
openclaw config set plugins.slots.memory none
rm -rf ~/.openclaw/extensions/memory-openviking/
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

Existing config fields are preserved during migration. The new plugin reads old field names at runtime.

• baseUrl
• apiKey
• peer_prefix: optional; interactive setup accepts only letters, digits, _, and -

Backup Path: ov-install

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

Backup install:

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

Backup/source commands:

Intent	Command
Install from a source ref	ov-install --plugin-version=<REF>
Non-interactive backup install	ov-install --base-url <URL> --api-key <KEY>
Target a non-default OpenClaw state directory	ov-install --workdir <PATH>
Show helper-tracked version	ov-install --current-version
Update helper-managed install	ov-install --update

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