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. ```bash 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: ```bash 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: | Value | Concrete layout | Choose it when | |---|---|---| | `none` (default) | Shared memory under `viking://user/<user_id>/memories/...`; no concrete `peers/<peer_id>/memories` subtree is used. | General case. All conversations for this OpenViking user share user-level memory. | | `assistant` | Assistant-attributed peer memory under `viking://user/<user_id>/peers/<assistant_id>/memories/...`, keyed by the resolved OpenClaw agent id (fallback `main`; optional prefix supported). | **Human as OpenViking user**: one human uses multiple assistants and wants their peer memories separated. Example: Alice's `main` and `research` assistants use `.../peers/main/...` and `.../peers/research/...`. | | `sender` | Sender-attributed peer memory under `viking://user/<user_id>/peers/<sender_id>/memories/...`, keyed by the sender identity supplied by OpenClaw. | **Agent as OpenViking user**: one agent talks to multiple humans and wants their peer memories separated. Example: `support-agent` stores `customer-42` and `customer-99` under different peer subtrees. | `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:** ```powershell try { (Invoke-WebRequest -Uri "BASE_URL/health" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop).StatusCode } catch { $_.Exception.Response.StatusCode.value__ } ``` **If OS=mac or OS=linux:** ```bash curl -sS -o /dev/null -w "%{http_code}" --connect-timeout 10 "BASE_URL/health" ``` Replace `BASE_URL` with the actual value. | Status | Meaning | Action | |---|---|---| | `200` | Server reachable, no auth on `/health` | Proceed to STEP 6. | | `401` / `403` | Server reachable but `/health` requires auth | Proceed to STEP 6 — the wizard's key probe will sort it out. | | `000` / timeout / connection refused | Server unreachable | **Server-not-ready handling** below. | | Anything else | Unexpected | Show status code to the user, go back to STEP 4a. | ### 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: ```bash 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: ```bash 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): ```bash 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. `ov-install` will, in one shot: 1. Download the `@openviking/openclaw-plugin` package from npm into a temporary staging dir. 2. Copy the package into the OpenClaw `extensions/` dir and install plugin dependencies. 3. Register the plugin in `openclaw.json` (via `openclaw plugins enable` or direct write). 4. Run `openclaw openviking setup --json --base-url … [--api-key …]` for the user. 5. Return a non-zero exit if setup needs explicit `--allow-offline` or `--force-slot` consent. This means **STEP 7 is effectively done by `ov-install`**. After `ov-install` exits 0, jump straight to **STEP 9** (gateway restart) and **STEP 10** (verify). If `ov-install` exits non-zero, capture the last 30 lines of its output, show them to the user, and stop. Don't retry blindly. --- ## STEP 7: Configure (only on Path A — Path B did this for you) Run the setup wizard non-interactively. Build flags from collected values: ```bash openclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--peer-role PEER_ROLE] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot] ``` Rules: - `--base-url BASE_URL` is **required** under `--json`. Without it, the wizard prints `--json requires --base-url for non-interactive mode`. - `--api-key` only if `API_KEY` is non-empty. - `--peer-role` only if the user chose `assistant` or `sender`; omit it for the `none` default. Normalize legacy `person` to `sender` first. - `--peer-prefix` only if the user gave one and `--peer-role assistant` is in play. Use **`--peer-prefix`** for assistant peer prefixes; the old ID-style setup flag is no longer supported.