volcengine/openviking/install-openviking-memory

Install OpenViking Memory — Agent Installation & Reference Skill

You are about to help a user install and configure the OpenViking memory plugin for OpenClaw. The user does NOT know how to use a terminal. You will collect a few values through natural conversation, then run all commands yourself using your shell tool.

Read this entire document before starting. Follow every step in order. Do NOT skip steps.

This skill is split into two halves:

• Part 1 (STEP 0–10): Natural-language installation walkthrough. Use this on first install or reconfigure.
• Part 2: Reference. Tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery. Read on demand.

Server scope. This skill does not install the OpenViking server itself. It assumes the server is already running locally on 127.0.0.1:1933 or on another machine. If the user has no server, see "Server not ready" handling in STEP 5.

Part 1 — Natural-Language Installation Walkthrough

STEP 0: Detect Language

If the user's first message contains Chinese characters, respond in Chinese throughout. Otherwise respond in English. All user-facing messages below have (CN)/(EN) variants — use the matching one.

Do NOT show this step to the user.

STEP 1: Detect Operating System (silently)

Run this command and remember the result. Do NOT show it to the user.

uname -s 2>/dev/null || echo WINDOWS

• Output contains Darwin → OS=mac
• Output contains Linux → OS=linux
• Output is WINDOWS or the command fails → OS=windows

STEP 2: Check Prerequisites (silently)

Run silently:

node -v
openclaw --version

If `node` is missing:

(CN) 你的系统没有安装 Node.js。OpenClaw 和 OpenViking 插件需要 Node.js >= 22。请先安装 Node.js，然后再回来找我。

(EN) Node.js is not installed. OpenClaw and the OpenViking plugin require Node.js >= 22. Please install Node.js first, then come back.

Stop. Do NOT continue.

If `openclaw` is missing:

(CN) 你的系统没有安装 OpenClaw。请先安装 OpenClaw（>= 2026.5.27），然后再回来找我。

(EN) OpenClaw is not installed. Please install OpenClaw (>= 2026.5.27) first, then come back.

Stop. Do NOT continue.

If both exist, proceed to STEP 3 silently.

STEP 3: Greet and Ask for 3 Values

Send this message:

(CN) 好，我来帮你接入 OpenViking 长期记忆。装好之后，我会自动记住对话里的重要信息，下次聊也能回忆起来。

我需要 3 条信息，不知道的可以问你的管理员：

1. OpenViking 服务地址 —— 例如 https://ov.example.com 或 http://192.168.1.100:1933，本机服务可以直接说"本机"

2. API Key —— 用来鉴权；服务没开认证可以说"没有"

3. 记忆归属（可选） —— 所有对话共用 user 记忆（默认），还是在 peers/<assistant_id> 或 peers/<sender_id> 下分开存放

先告诉我服务地址吧？

(EN) I'll set up OpenViking long-term memory for you. Once configured, I'll automatically remember important info from our chats and recall it later.

I need 3 things (ask your admin if unsure):

1. OpenViking server URL — e.g. https://ov.example.com or http://192.168.1.100:1933. For a local server, just say "local".

2. API Key — for auth. Say "none" if the server has no auth.

3. Memory scope (optional) — shared user memory (default), or peer memory under peers/<assistant_id> / peers/<sender_id>.

What's the server URL?

STEP 4: Collect Values

Collect 3 values through natural conversation. Be flexible: if the user gives several at once, parse them all. If they correct something, accept the new value.

4a. BASE_URL (REQUIRED)

• "local" / "本机" / "localhost" → use http://127.0.0.1:1933.
• ov.example.com without protocol → prepend https://.
• Strip trailing /, /health, or /api.
• After normalization must start with http:// or https://.
• If the user says they don't know, ask them to check with the admin or look at how the server was started. Do NOT make up a URL.

4b. API_KEY (OPTIONAL)

(CN) API Key 是什么？服务没开认证就直接说"没有"。

(EN) What's the API Key? Say "none" if the server has no auth.

• "no" / "none" / "没有" / "空" / empty → API_KEY="" (you will skip the flag later).
• Otherwise store as-is.

4c. PEER_ROLE (OPTIONAL)

(CN) 记忆要存在哪一层？默认共享在 viking://user/<user_id>/memories（none）。也可以按 OpenClaw 助手存到 .../peers/<assistant_id>/memories（assistant），或按发送者存到 .../peers/<sender_id>/memories（sender）。

(EN) Where should memory live? The default is shared viking://user/<user_id>/memories (none). You can instead use .../peers/<assistant_id>/memories (assistant) or .../peers/<sender_id>/memories (sender).

Default to none. Never silently pick another value — the three options mean different storage layouts and are awkward to change later:

person is a legacy alias for sender. Accept it from an existing config or explicit user input, but normalize/write new setup values as sender.

OpenViking initializes the managed peers/ container for every user. Do not tell the user that none removes that container: it only avoids a concrete peer memory subtree. With assistant or sender, actor-peer recall includes shared user memory plus the current peer memory; it hides other peer subtrees. Changing this setting does not move existing memories.

• Empty / "default" / "默认" / "共用" → leave unset (plugin defaults to none).
• Otherwise pass --peer-role none|assistant|sender. Treat explicit legacy person as sender. Any other value → ask again.

4d. PEER_PREFIX (OPTIONAL, only when PEER_ROLE=assistant)

(CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、_、-。

(EN) Want to set an peer prefix? Leave blank for the default. Letters, digits, _, - only.

• Only meaningful when PEER_ROLE=assistant; skip the question otherwise.
• Empty / "default" / "默认" → leave unset (plugin defaults to "").
• Otherwise validate against /^[A-Za-z0-9_-]+$/. If invalid, ask again.

4e. (Conditional) Multi-Tenant Root-Key Fields

Only ask for these if STEP 7 detects a root key (Root API key detected. Missing: --account-id, --user-id). Don't ask up front.

• ACCOUNT_ID
• USER_ID

See Reference: Multi-Tenant for what these mean.

STEP 5: Pre-flight Connectivity Check (silently)

Tell the user briefly:

(CN) 我先测一下能不能连上服务……

(EN) Let me test the connection to your server...

Run:

If OS=windows:

try { (Invoke-WebRequest -Uri "BASE_URL/health" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop).StatusCode } catch { $_.Exception.Response.StatusCode.value__ }

If OS=mac or OS=linux:

curl -sS -o /dev/null -w "%{http_code}" --connect-timeout 10 "BASE_URL/health"

Replace BASE_URL with the actual value.

Server-not-ready handling

This skill does not install or operate the OpenViking server. If the user's server is unreachable, present the situation honestly and offer two paths:

(CN) ❌ 我连不上 BASE_URL。可能是：

1) 服务还没启动 —— 请联系你的 OpenViking 服务管理员把它起起来；如果是你自己负责，请参考 OpenViking 官方文档（https://github.com/volcengine/OpenViking）的 server 启动指引。

2) 地址不对 —— 你可以重新告诉我正确的地址。

3) 网络不通（防火墙 / VPN / 内网）—— 你确认一下网络。

也可以选择"先把配置写下来"，等服务起来就自动生效，要这么办吗？

(EN) ❌ Cannot reach BASE_URL. Likely cause:

1) Server isn't running — please ask your OpenViking admin to start it. If you own the server, follow the OpenViking official docs (https://github.com/volcengine/OpenViking) to start it. This skill does not install or run the server.

2) Wrong URL — give me the correct URL.

3) Network blocked (firewall / VPN / private network) — please verify connectivity.

Or I can save the config now (--allow-offline) so it will activate automatically once the server is up. Want me to do that?

If the user fixes the URL → back to STEP 4a. If the user wants --allow-offline → remember ALLOW_OFFLINE=true and continue to STEP 6. If the user gives up / cannot fix → stop here. Do NOT continue with a broken state.

STEP 6: Install the Plugin

The plugin can be installed two ways. Always try Path A first. Use Path B only as a backup when Path A fails because ClawHub is unavailable, rate-limited, or authentication blocks anonymous install. For version conflicts, dependency errors, or other non-registry failures, stop and show the user the error instead of switching paths silently.

Path A — Primary: openclaw plugins install (uses ClawHub)

Tell the user:

(CN) 现在开始装插件……

(EN) Installing the plugin now...

Run:

openclaw plugins install clawhub:@openviking/openclaw-plugin

Trigger fallback to Path B only if the output contains any of these strings:

• 429
• rate limit / rate-limited / Too Many Requests
• not logged in / please log in / please login / unauthorized / 401 / 403 together with clawhub
• ETIMEDOUT / ECONNRESET on a clawhub-related host
• generic message indicating the registry refused an anonymous client

Before falling back, also try the explicit registry prefix once:

openclaw plugins install clawhub:@openviking/openclaw-plugin

If the install succeeds, jump to STEP 7.

If both attempts fail with one of the fallback-eligible errors above, go to Path B. If the failure is a version conflict, missing dependency, package validation error, or another non-registry error, stop and show the last 30 lines to the user.

Path B — Backup: ov-install (bypasses ClawHub)

Tell the user:

(CN) ClawHub 现在好像被限流、不可用，或者当前账号不能安装。我改用备用路径，通过 npm 下载并部署插件包。

(EN) ClawHub looks rate-limited, unavailable, or blocked for this account. I'll use the backup path and install the plugin package from npm.

Run the installer with npx (no global install needed):

npx -y openclaw-openviking-setup-helper@latest --base-url BASE_URL [--api-key API_KEY] [--peer-role PEER_ROLE] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID]

Build the flag list according to what the user gave you:

• Always pass --base-url BASE_URL.
• Pass --api-key API_KEY only if API_KEY is non-empty.
• Pass --peer-role PEER_ROLE only if the user chose assistant or sender; omit it for the none default. Normalize legacy person to sender first.
• Pass --peer-prefix PEER_PREFIX only if the user gave one and PEER_ROLE=assistant.
• --account-id / --user-id only if the root-key path requires them.