OpenViking Plugin Agent Install Guide
September 4, 2026 ยท View on GitHub
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:
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 |
| Memory scope | Optional; default none | Ask whether memory is shared, separated by assistant, or separated by sender. Use sender; accept legacy person as an alias. |
| 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
Choose memory scope before building that command:
| Value | Concrete layout | Use when |
|---|---|---|
none (default; omit the flag) | Shared viking://user/<user_id>/memories/...; no concrete peer memory subtree | General case |
assistant | Assistant-attributed peer memory under .../peers/<assistant_id>/memories/... | A human is the OpenViking user and uses multiple OpenClaw assistants |
sender | Sender-attributed peer memory under .../peers/<sender_id>/memories/... | An agent is the OpenViking user and receives messages from multiple humans |
person is a legacy alias for sender. Accept it from existing config or user input, but write sender in new setup commands. OpenViking initializes the managed peers/ container for every user; none only means that no concrete peers/<peer_id>/memories subtree is used. Actor-peer recall includes shared user memory plus the current peer memory, and changing the scope does not move existing memories.
Examples:
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --json
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --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 assistant routing prefix (optional; only with peer_role=assistant and when the user explicitly requests a prefix):
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --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_role | Confirms none, assistant, or canonical sender scope |
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.27is the minimum supported OpenClaw version for the current@openviking/openclaw-pluginplugin.2026.5.3starts requiring compiled JavaScript runtime output during package install when a plugin package declares TypeScript entries.2026.5.4and later no longer fall back to.tssource 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-installis 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_role | none (shared user memory), assistant (peers/<assistant_id>), or sender (peers/<sender_id>). Legacy person is accepted as sender. |
peer_prefix | Optional only with peer_role=assistant; prefix for OpenClaw agent IDs. 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.
baseUrlapiKeypeer_role: optional;none,assistant, orsender; legacypersonis accepted assenderpeer_prefix: optional only withpeer_role=assistant; 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.