# 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:

```bash
clawhub install openviking
```

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

Use this plugin command instead:

```bash
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:

```bash
node -v
openclaw --version
```

## Start OpenViking Server

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

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
```

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

```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
```

### 2. Configure The Plugin

For interactive human setup:

```bash
openclaw openviking setup
```

For non-interactive agent setup:

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

Example:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`).

```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

```bash
openclaw gateway restart
```

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

### 4. Verify

```bash
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:

```bash
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:

```text
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:

```bash
openclaw openviking setup --reconfigure
```

Manual config inspection:

```bash
openclaw config get plugins.entries.openviking.config
```

## Upgrade

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

Confirm that `configured` and `slotActive` are both `true`.

## Uninstall

```bash
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:

```bash
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](./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:

```bash
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:

```bash
# 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:

```bash
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:

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

## Start

After installation (if you skipped reconfigure above):

```bash
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:

```bash
# 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
bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
```

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