{"id":"f0250a64-3e7b-4fe3-afb2-c55c968b9dee","entityType":"agent","slug":"clawhub-linqiang391-install-openviking-memory","name":"Install Openviking Memory","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linqiang391-install-openviking-memory","canonicalPath":"/agent/clawhub-linqiang391-install-openviking-memory","generatedAt":"2026-10-12T09:10:03.346Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T23:51:45.566Z","emptyReason":null},"description":"Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa... Skill: Install Openviking Memory Owner: linqiang391 Summary: Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa... Tags: install:2.0.0, latest:2.0.1, latest install setup memory openviking rag:2.0.1, memory:2.0.0, openviking:2.0.0, rag:2.0.0, setup:2.0.0 Version history: v2.0.1 | 2026-05-18T02:10:36.014Z | user","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 973 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1758ytwe8t73f6tf7cydrdcdn83zbs8:install-openviking-memory","sourceUrl":"https://clawhub.ai/linqiang391/install-openviking-memory","homepage":"https://clawhub.ai/linqiang391/skills/install-openviking-memory","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linqiang391/install-openviking-memory","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linqiang391/skills/install-openviking-memory","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:51:45.566Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:51:45.566Z","emptyReason":null},"stars":null,"forks":null,"downloads":973,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"2.0.1","tractionLabel":"973 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:51:45.502Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T23:51:45.566Z","lastCrawledAt":"2026-10-11T23:51:45.502Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T23:51:45.502Z","lastVerifiedAt":null,"highlights":[{"version":"2.0.1","createdAt":"2026-05-18T02:10:36.014Z","changelog":"Update OpenViking install instructions for the canonical @openviking/openclaw-plugin package and current ov-install npm fallback behavior.","fileCount":3,"zipByteSize":13563},{"version":"2.0.0","createdAt":"2026-05-05T17:32:50.864Z","changelog":"Initial publish: natural-language install walkthrough (STEP 0-10) + reference (tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery). Auto-fallback to ov-install when ClawHub is rate-limited. Server install is out of scope.","fileCount":2,"zipByteSize":11544}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1758ytwe8t73f6tf7cydrdcdn83zbs8:install-openviking-memory","setupComplexity":"medium","setupSteps":["Setup complexity is MEDIUM. Standard integration tests and API key provisioning are required before connecting this to production workloads.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T09:10:03.345Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linqiang391-install-openviking-memory/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T23:51:45.566Z","emptyReason":null},"readme":"Skill: Install Openviking Memory\n\nOwner: linqiang391\n\nSummary: Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa...\n\nTags: install:2.0.0, latest:2.0.1, latest install setup memory openviking rag:2.0.1, memory:2.0.0, openviking:2.0.0, rag:2.0.0, setup:2.0.0\n\nVersion history:\n\nv2.0.1 | 2026-05-18T02:10:36.014Z | user\n\nUpdate OpenViking install instructions for the canonical @openviking/openclaw-plugin package and current ov-install npm fallback behavior.\n\nv2.0.0 | 2026-05-05T17:32:50.864Z | user\n\nInitial publish: natural-language install walkthrough (STEP 0-10) + reference (tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery). Auto-fallback to ov-install when ClawHub is rate-limited. Server install is out of scope.\n\nArchive index:\n\nArchive v2.0.1: 3 files, 13563 bytes\n\nFiles: skill-card.md (2291b), SKILL.md (30773b), _meta.json (144b)\n\nFile v2.0.1:SKILL.md\n\n---\r\nname: install-openviking-memory\r\ndescription: >\r\n  Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation.\r\n  Once installed, the plugin automatically captures important facts from chats and recalls relevant\r\n  context before each reply (auto-capture + auto-recall, cross-session). Covers prerequisites check,\r\n  plugin install through OpenClaw's plugin manager first, with ov-install only as a backup path,\r\n  wizard-based configuration, slot activation,\r\n  gateway restart, verification, plus multi-tenant root-key support, multi-instance, and uninstall.\r\n  Trigger when the user says any of: \"install OpenViking\", \"set up memory\", \"configure memory plugin\",\r\n  \"add long-term memory\", \"connect to OpenViking server\", \"RAG\", \"semantic memory\",\r\n  \"帮我装 OpenViking\", \"配置记忆插件\", \"安装记忆功能\", \"接入 OpenViking\", \"我有一台 OpenViking 服务器\".\r\n  The user does NOT need to know any CLI commands — the agent runs everything and only asks for a few values.\r\n  This skill assumes the OpenViking server is already running. If the server is not ready, the skill\r\n  tells the user to contact their admin or set it up via the OpenViking docs — it does NOT install the server.\r\nversion: 2.0.1\nmetadata:\r\n  openclaw:\r\n    requires:\r\n      bins:\r\n        - node\r\n        - openclaw\r\n  emoji: \"🦣\"\r\n  homepage: \"https://github.com/volcengine/OpenViking\"\r\ntags:\r\n  - install\r\n  - setup\r\n  - memory\r\n  - openviking\r\n  - rag\r\n  - long-term-memory\r\n---\r\n\r\n# Install OpenViking Memory — Agent Installation & Reference Skill\r\n\r\nYou are about to help a user install and configure the OpenViking memory plugin for OpenClaw.\r\nThe 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.\r\n\r\n**Read this entire document before starting. Follow every step in order. Do NOT skip steps.**\r\n\r\nThis skill is split into two halves:\r\n\r\n- **Part 1 (STEP 0–10): Natural-language installation walkthrough.** Use this on first install or reconfigure.\r\n- **Part 2: Reference.** Tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery. Read on demand.\r\n\r\n> **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.\r\n\r\n---\r\n\r\n# Part 1 — Natural-Language Installation Walkthrough\r\n\r\n## STEP 0: Detect Language\r\n\r\nIf the user's first message contains Chinese characters, respond in **Chinese** throughout.\r\nOtherwise respond in **English**.\r\nAll user-facing messages below have (CN)/(EN) variants — use the matching one.\r\n\r\nDo NOT show this step to the user.\r\n\r\n---\r\n\r\n## STEP 1: Detect Operating System (silently)\r\n\r\nRun this command and remember the result. Do NOT show it to the user.\r\n\r\n```bash\r\nuname -s 2>/dev/null || echo WINDOWS\r\n```\r\n\r\n- Output contains `Darwin` → `OS=mac`\r\n- Output contains `Linux` → `OS=linux`\r\n- Output is `WINDOWS` or the command fails → `OS=windows`\r\n\r\n---\r\n\r\n## STEP 2: Check Prerequisites (silently)\r\n\r\nRun silently:\r\n\r\n```bash\r\nnode -v\r\nopenclaw --version\r\n```\r\n\r\n**If `node` is missing:**\r\n\r\n> (CN) 你的系统没有安装 Node.js。OpenClaw 和 OpenViking 插件需要 Node.js >= 22。请先安装 Node.js，然后再回来找我。\r\n> (EN) Node.js is not installed. OpenClaw and the OpenViking plugin require Node.js >= 22. Please install Node.js first, then come back.\r\n\r\n**Stop. Do NOT continue.**\r\n\r\n**If `openclaw` is missing:**\r\n\r\n> (CN) 你的系统没有安装 OpenClaw。请先安装 OpenClaw（>= 2026.4.8），然后再回来找我。\r\n> (EN) OpenClaw is not installed. Please install OpenClaw (>= 2026.4.8) first, then come back.\r\n\r\n**Stop. Do NOT continue.**\r\n\r\nIf both exist, proceed to STEP 3 silently.\r\n\r\n---\r\n\r\n## STEP 3: Greet and Ask for 3 Values\r\n\r\nSend this message:\r\n\r\n> (CN) 好，我来帮你接入 OpenViking 长期记忆。装好之后，我会自动记住对话里的重要信息，下次聊也能回忆起来。\r\n>\r\n> 我需要 3 条信息，不知道的可以问你的管理员：\r\n> 1. **OpenViking 服务地址** —— 例如 `https://ov.example.com` 或 `http://192.168.1.100:1933`，本机服务可以直接说\"本机\"\r\n> 2. **API Key** —— 用来鉴权；服务没开认证可以说\"没有\"\r\n> 3. **Agent 标识前缀**（可选） —— 用于区分多个 agent 的记忆命名空间，留空就用默认\r\n>\r\n> 先告诉我服务地址吧？\r\n\r\n> (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.\r\n>\r\n> I need 3 things (ask your admin if unsure):\r\n> 1. **OpenViking server URL** — e.g. `https://ov.example.com` or `http://192.168.1.100:1933`. For a local server, just say \"local\".\r\n> 2. **API Key** — for auth. Say \"none\" if the server has no auth.\r\n> 3. **Agent prefix** (optional) — used to namespace memories across agents. Leave blank for default.\r\n>\r\n> What's the server URL?\r\n\r\n---\r\n\r\n## STEP 4: Collect Values\r\n\r\nCollect 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.\r\n\r\n### 4a. `BASE_URL` (REQUIRED)\r\n\r\n- \"local\" / \"本机\" / \"localhost\" → use `http://127.0.0.1:1933`.\r\n- `ov.example.com` without protocol → prepend `https://`.\r\n- Strip trailing `/`, `/health`, or `/api`.\r\n- After normalization must start with `http://` or `https://`.\r\n- 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.**\r\n\r\n### 4b. `API_KEY` (OPTIONAL)\r\n\r\n> (CN) API Key 是什么？服务没开认证就直接说\"没有\"。\r\n> (EN) What's the API Key? Say \"none\" if the server has no auth.\r\n\r\n- \"no\" / \"none\" / \"没有\" / \"空\" / empty → `API_KEY=\"\"` (you will skip the flag later).\r\n- Otherwise store as-is.\r\n\r\n### 4c. `AGENT_PREFIX` (OPTIONAL)\r\n\r\n> (CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、`_`、`-`。\r\n> (EN) Want to set an agent prefix? Leave blank for the default. Letters, digits, `_`, `-` only.\r\n\r\n- Empty / \"default\" / \"默认\" → leave unset (plugin defaults to `\"\"`).\r\n- Otherwise validate against `/^[A-Za-z0-9_-]+$/`. If invalid, ask again.\r\n\r\n### 4d. (Conditional) Multi-Tenant Root-Key Fields\r\n\r\nOnly ask for these if STEP 7 detects a root key (`Root API key detected. Missing: --account-id, --user-id`). Don't ask up front.\r\n\r\n- `ACCOUNT_ID`\r\n- `USER_ID`\r\n\r\nSee **Reference: Multi-Tenant** for what these mean.\r\n\r\n---\r\n\r\n## STEP 5: Pre-flight Connectivity Check (silently)\r\n\r\nTell the user briefly:\r\n\r\n> (CN) 我先测一下能不能连上服务……\r\n> (EN) Let me test the connection to your server...\r\n\r\nRun:\r\n\r\n**If OS=windows:**\r\n\r\n```powershell\r\ntry { (Invoke-WebRequest -Uri \"BASE_URL/health\" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop).StatusCode } catch { $_.Exception.Response.StatusCode.value__ }\r\n```\r\n\r\n**If OS=mac or OS=linux:**\r\n\r\n```bash\r\ncurl -sS -o /dev/null -w \"%{http_code}\" --connect-timeout 10 \"BASE_URL/health\"\r\n```\r\n\r\nReplace `BASE_URL` with the actual value.\r\n\r\n| Status | Meaning | Action |\r\n|---|---|---|\r\n| `200` | Server reachable, no auth on `/health` | Proceed to STEP 6. |\r\n| `401` / `403` | Server reachable but `/health` requires auth | Proceed to STEP 6 — the wizard's key probe will sort it out. |\r\n| `000` / timeout / connection refused | Server unreachable | **Server-not-ready handling** below. |\r\n| Anything else | Unexpected | Show status code to the user, go back to STEP 4a. |\r\n\r\n### Server-not-ready handling\r\n\r\nThis skill **does not install or operate the OpenViking server**. If the user's server is unreachable, present the situation honestly and offer two paths:\r\n\r\n> (CN) ❌ 我连不上 `BASE_URL`。可能是：\r\n> 1) 服务还没启动 —— 请联系你的 OpenViking 服务管理员把它起起来；如果是你自己负责，请参考 OpenViking 官方文档（`https://github.com/volcengine/OpenViking`）的 server 启动指引。\r\n> 2) 地址不对 —— 你可以重新告诉我正确的地址。\r\n> 3) 网络不通（防火墙 / VPN / 内网）—— 你确认一下网络。\r\n>\r\n> 也可以选择\"先把配置写下来\"，等服务起来就自动生效，要这么办吗？\r\n\r\n> (EN) ❌ Cannot reach `BASE_URL`. Likely cause:\r\n> 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.**\r\n> 2) **Wrong URL** — give me the correct URL.\r\n> 3) **Network blocked** (firewall / VPN / private network) — please verify connectivity.\r\n>\r\n> Or I can save the config now (`--allow-offline`) so it will activate automatically once the server is up. Want me to do that?\r\n\r\nIf the user fixes the URL → back to STEP 4a.\r\nIf the user wants `--allow-offline` → remember `ALLOW_OFFLINE=true` and continue to STEP 6.\r\nIf the user gives up / cannot fix → stop here. Do NOT continue with a broken state.\r\n\r\n---\r\n\r\n## STEP 6: Install the Plugin\r\n\r\nThe 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.\r\n\r\n### Path A — Primary: `openclaw plugins install` (uses ClawHub)\r\n\r\nTell the user:\r\n\r\n> (CN) 现在开始装插件……\r\n> (EN) Installing the plugin now...\r\n\r\nRun:\r\n\r\n```bash\r\nopenclaw plugins install @openviking/openclaw-plugin\r\n```\r\n\r\nTrigger fallback to Path B only if the output contains any of these strings:\r\n\r\n- `429`\r\n- `rate limit` / `rate-limited` / `Too Many Requests`\r\n- `not logged in` / `please log in` / `please login` / `unauthorized` / `401` / `403` together with `clawhub`\r\n- `ETIMEDOUT` / `ECONNRESET` on a `clawhub`-related host\r\n- generic message indicating the registry refused an anonymous client\r\n\r\nBefore falling back, also try the explicit registry prefix once:\r\n\r\n```bash\r\nopenclaw plugins install clawhub:@openviking/openclaw-plugin\r\n```\r\n\r\nIf the install **succeeds**, jump to STEP 7.\r\n\r\nIf 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.\r\n\r\n### Path B — Backup: `ov-install` (bypasses ClawHub)\r\n\r\nTell the user:\r\n\r\n> (CN) ClawHub 现在好像被限流、不可用，或者当前账号不能安装。我改用备用路径，通过 npm 下载并部署插件包。\n> (EN) ClawHub looks rate-limited, unavailable, or blocked for this account. I'll use the backup path and install the plugin package from npm.\n\r\nRun the installer with `npx` (no global install needed):\r\n\r\n```bash\r\nnpx -y openclaw-openviking-setup-helper@latest --base-url BASE_URL [--api-key API_KEY] [--agent-prefix AGENT_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID]\r\n```\r\n\r\nBuild the flag list according to what the user gave you:\r\n\r\n- Always pass `--base-url BASE_URL`.\r\n- Pass `--api-key API_KEY` only if `API_KEY` is non-empty.\r\n- Pass `--agent-prefix AGENT_PREFIX` only if the user gave one.\r\n- `--account-id` / `--user-id` only if the root-key path requires them.\r\n\r\n`ov-install` will, in one shot:\n1. Download the `@openviking/openclaw-plugin` package from npm into a temporary staging dir.\n2. Copy the package into the OpenClaw `extensions/` dir and install plugin dependencies.\n3. Register the plugin in `openclaw.json` (via `openclaw plugins enable` or direct write).\n4. Run `openclaw openviking setup --json --base-url … [--api-key …]` for the user.\n5. Return a non-zero exit if setup needs explicit `--allow-offline` or `--force-slot` consent.\n\r\nThis 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).\r\n\r\nIf `ov-install` exits non-zero, capture the last 30 lines of its output, show them to the user, and stop. Don't retry blindly.\r\n\r\n---\r\n\r\n## STEP 7: Configure (only on Path A — Path B did this for you)\r\n\r\nRun the setup wizard non-interactively. Build flags from collected values:\r\n\r\n```bash\r\nopenclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--agent-prefix AGENT_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot]\r\n```\r\n\r\nRules:\r\n\r\n- `--base-url BASE_URL` is **required** under `--json`. Without it, the wizard prints `--json requires --base-url for non-interactive mode`.\r\n- `--api-key` only if `API_KEY` is non-empty.\r\n- `--agent-prefix` only if the user gave one. Use **`--agent-prefix`**, not `--agent-id` (deprecated and removed).\r\n- `--account-id` / `--user-id` only after STEP 7 root-key detection (see below).\r\n- `--allow-offline` only if the user explicitly approved it in STEP 5.\r\n- `--force-slot` **never** in the first attempt. Add only after the user confirms (see slot_blocked handling below).\r\n\r\n### Parse the JSON output\r\n\r\nThe wizard prints a single JSON object:\r\n\r\n```json\r\n{\r\n  \"success\": true | false,\r\n  \"action\": \"configured\" | \"existing\" | \"error\" | \"slot_blocked\",\r\n  \"config\": { \"mode\": \"remote\", \"baseUrl\": \"...\", \"apiKey\": \"...\", \"agent_prefix\": \"...\", \"accountId\": \"...\", \"userId\": \"...\" },\r\n  \"health\": { \"ok\": true, \"status\": 200 },\r\n  \"keyProbe\": { \"keyType\": \"user_key\" | \"root_key\" | \"none\", \"ok\": true },\r\n  \"slot\": { \"ok\": true, \"owner\": \"openviking\" },\r\n  \"error\": \"...\"\r\n}\r\n```\r\n\r\n### Decision matrix\r\n\r\n| Condition | Action |\r\n|---|---|\r\n| `success: true` and `action: \"configured\"` or `\"existing\"` | Done. Proceed to STEP 9. |\r\n| `success: false` and `action: \"slot_blocked\"` | **Slot conflict — see below.** |\r\n| `success: false` and `error` contains `\"Server unreachable\"` | Connectivity broke between STEP 5 and STEP 7. Offer `--allow-offline`; if accepted, retry. Otherwise back to STEP 4a. |\r\n| `success: false` and `error` contains `\"Root API key detected\"` and `\"Missing: --account-id, --user-id\"` | **Root-key path — see below.** |\r\n| `success: false` and `error` contains `\"Invalid API key\"` / `keyProbe.keyType: \"none\"` with `ok: false` | API key wrong. Back to STEP 4b. |\r\n| `success: false` and any other `action: \"error\"` | Show `error` to the user, stop. Do NOT pretend success. |\r\n\r\n### Slot conflict (`slot_blocked`)\r\n\r\nThe error text looks like:\r\n\r\n> `contextEngine slot is owned by \"<other-plugin>\". Config was saved but slot was NOT changed. Use --force-slot to replace.`\r\n\r\n**Do NOT silently use `--force-slot`.** Ask the user:\r\n\r\n> (CN) 你的 OpenClaw 当前 contextEngine 槽被 `<other-plugin>` 占着。如果用 OpenViking 替换它，`<other-plugin>` 就不再生效。要替换吗？\r\n> (EN) Your `contextEngine` slot is currently owned by `<other-plugin>`. Activating OpenViking will disable it. Replace?\r\n\r\nIf the user agrees, retry the same setup command with `--force-slot` appended. If they decline, tell them config has been saved but the slot is unchanged, and stop.\r\n\r\n### Root-key path\r\n\r\nThe error text looks like:\r\n\r\n> `Root API key detected. Missing: --account-id, --user-id. Provide both to enable multi-tenant scoping.`\r\n\r\nAsk the user:\r\n\r\n> (CN) 你给的是 root 级 API Key，需要再补两个值才能用：账户 ID（accountId）和用户 ID（userId）。这两个一般是 OpenViking 服务管理员配的，不知道就问他们。\r\n> (EN) Your API key is a root key, which needs two more values: `accountId` and `userId`. Both come from your OpenViking server admin — ask them if unsure.\r\n\r\nAfter collecting, retry the setup command with `--account-id` and `--user-id` appended.\r\n\r\n---\r\n\r\n## STEP 8: (Reserved — done inside STEP 7 or by `ov-install`)\r\n\r\nThe setup wizard already wrote `plugins.entries.openviking.config.*` and (if successful) set `plugins.slots.contextEngine = \"openviking\"`. There is no separate STEP 8 — go to STEP 9.\r\n\r\n---\r\n\r\n## STEP 9: Restart the Gateway\r\n\r\n```bash\r\nopenclaw gateway restart\r\n```\r\n\r\nIf it fails, try once more with:\r\n\r\n```bash\r\nopenclaw gateway --force\r\n```\r\n\r\nIf both fail:\r\n\r\n> (CN) Gateway 没能自动重启。请你手动跑一下 `openclaw gateway restart`。重启完告诉我，我来验证。\r\n> (EN) Gateway didn't restart cleanly. Please run `openclaw gateway restart` manually, then tell me when it's done so I can verify.\r\n\r\nWait ~3 seconds before STEP 10.\r\n\r\n---\r\n\r\n## STEP 10: Verify\r\n\r\n```bash\r\nopenclaw openviking status --json\r\n```\r\n\r\nExpected output:\r\n\r\n```json\r\n{\r\n  \"configured\": true,\r\n  \"slotActive\": true,\r\n  \"health\": { \"ok\": true },\r\n  \"config\": { \"baseUrl\": \"...\", \"agent_prefix\": \"...\" }\r\n}\r\n```\r\n\r\n### Decision\r\n\r\n- `configured: true` **and** `slotActive: true` **and** `health.ok: true` → **success.** Send the success message below.\r\n- `configured: true` but `slotActive: false` → if you previously skipped `--force-slot`, ask the user about replacing now and retry STEP 7 with `--force-slot`. Otherwise it's a gateway restart issue — back to STEP 9.\r\n- `configured: true` but `health.ok: false` → server became unreachable. Tell the user; the config will start working as soon as the server is back.\r\n- `configured: false` → setup didn't actually persist. Show full status JSON to the user and stop.\r\n\r\n### Success message\r\n\r\n> (CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。\r\n>\r\n> 工作方式：\r\n> - **每一轮**：你的对话会被自动归档到 OpenViking session 里\r\n> - **`/compact` 时**：归档消息会被抽取成长期记忆，写到 `~/.openviking/data/` 下\r\n> - **后续会话**：每次回复前我都会自动搜一下相关记忆并带进上下文\r\n>\r\n> 想验证一下吗？跟我聊几句包含可记忆事实的话（例如\"我的邮箱是 test@example.com\"），然后调一下 `/compact`，再开新对话问\"我的邮箱是？\"，应该就能召回了。\r\n\r\n> (EN) 🎉 All set! OpenViking long-term memory is connected.\r\n>\r\n> How it works:\r\n> - **Every turn**: our messages are auto-archived into an OpenViking session\r\n> - **On `/compact`**: archived messages are extracted into long-term memories under `~/.openviking/data/`\r\n> - **Future sessions**: relevant memories are auto-retrieved and injected before my replies\r\n>\r\n> Want to verify? Tell me a few facts (e.g. \"my email is test@example.com\"), run `/compact`, then start a new chat and ask \"what's my email?\" — it should recall.\r\n\r\n---\r\n\r\n# Part 2 — Reference\r\n\r\n## How It Works\r\n\r\nThe context-engine pipeline has three distinct stages — keep them apart, especially when telling users when memories actually appear in `~/.openviking/data/`:\r\n\r\n- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin commits user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **archive only** — no memory extraction yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.\r\n- **Memory extraction (on `/compact`)**: memory extraction runs when the user invokes OpenClaw's `/compact` command. The server-side extraction pipeline reads the archived session and writes new memories. The plugin's `after_compaction` hook is currently reserved; the extraction itself is driven by the server. **No `/compact`, no new memory files.**\r\n  - `captureMode: \"semantic\"` (default): server extraction pipeline filters all qualifying text.\r\n  - `captureMode: \"keyword\"`: only text matching trigger words (e.g. \"remember\", \"preference\") is considered.\r\n- **Auto-Recall (context-engine `assemble()`)**: before prompt context is assembled, the plugin queries OpenViking for relevant memories and injects them into context. Recall works even when there are no extracted memories yet — you just won't see anything come back.\r\n\r\n**Practical implication for testing**: if you write down a fact and immediately try to recall it without `/compact`, the plugin will only retrieve it as recent session context (archived messages), not as a long-term memory. To verify long-term memory cross-session, you must run `/compact` first.\r\n\r\n## Available Tools\r\n\r\nThese are the plugin tools the agent can call once installed.\r\n\r\n### `memory_recall` — Search Memories\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `query` | Yes | Search query text |\r\n| `limit` | No | Maximum number of results (defaults to plugin config) |\r\n| `scoreThreshold` | No | Minimum relevance score 0–1 (defaults to plugin config) |\r\n| `targetUri` | No | Search scope URI (defaults to plugin config) |\r\n\r\nExample: user asks \"What programming language did I say I like?\"\r\n\r\n### `memory_store` — Manual Store\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `text` | Yes | Information text to store |\r\n| `role` | No | Session role (default `user`) |\r\n| `sessionId` | No | Existing OpenViking session ID |\r\n\r\nExample: user says \"Remember my email is xxx@example.com\".\r\n\r\n### `memory_forget` — Delete Memories\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `uri` | No | Exact memory URI (direct delete) |\r\n| `query` | No | Search query (find then delete) |\r\n| `targetUri` | No | Search scope URI |\r\n| `limit` | No | Search limit (default 5) |\r\n| `scoreThreshold` | No | Minimum relevance score |\r\n\r\nExample: user says \"Forget my phone number\".\r\n\r\n## Configuration Schema\r\n\r\nThese are the keys under `plugins.entries.openviking.config` in `openclaw.json`. The setup wizard / `ov-install` sets the first few; the rest are tunables.\r\n\r\n| Field | Default | Description |\r\n|---|---|---|\r\n| `mode` | `\"remote\"` (forced by plugin) | Always remote in this skill. Don't set manually. |\r\n| `baseUrl` | `http://127.0.0.1:1933` | OpenViking server URL. |\r\n| `apiKey` | — | API key. Optional if server has no auth. |\r\n| `agent_prefix` | `\"\"` | Prefix for routing memories per agent. Letters / digits / `_` / `-`. |\r\n| `accountId` | — | Required when `apiKey` is a root key. |\r\n| `userId` | — | Required when `apiKey` is a root key. |\r\n| `targetUri` | `viking://user/memories` | Default search scope URI. |\r\n| `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |\r\n| `autoCapture` | `true` | Auto-archive turn messages to OpenViking session at `afterTurn` (extraction itself runs on `/compact`, not here). |\r\n| `captureMode` | `\"semantic\"` | Filter mode used by the server-side extraction pipeline: `semantic` or `keyword`. |\r\n| `captureMaxLength` | `24000` | Max text length per archived turn. |\r\n| `autoRecall` | `true` | Auto-recall and inject memories before reply. |\r\n| `recallLimit` | `6` | Max memories injected per recall. |\r\n| `recallScoreThreshold` | `0.15` | Min relevance score to inject. |\r\n| `recallMaxInjectedChars` | (plugin default) | Hard cap on injected character count. |\r\n| `recallPreferAbstract` | (plugin default) | Prefer abstract memories over raw. |\r\n| `recallTokenBudget` | (plugin default) | Token budget for injected memories. |\r\n| `isolateUserScopeByAgent` | (plugin default) | Multi-tenant scoping toggle. |\r\n| `isolateAgentScopeByUser` | (plugin default) | Multi-tenant scoping toggle. |\r\n| `agentScopeMode` | (plugin default) | Agent scope strategy. |\r\n| `bypassSessionPatterns` | — | Glob patterns for sessions skipped by capture. |\r\n| `ingestReplyAssist` | (plugin default) | Reply-assist ingestion toggle. |\r\n| `emitStandardDiagnostics` | (plugin default) | Verbose diagnostic logs. |\r\n| `logFindRequests` | (plugin default) | Log retrieval requests. |\r\n\r\nTo change a value:\r\n\r\n```bash\r\nopenclaw config set plugins.entries.openviking.config.<field> <value>\r\nopenclaw gateway restart\r\n```\r\n\r\n## Multi-Tenant (Root API Keys)\r\n\r\nSome OpenViking deployments use a single **root** API key shared across tenants. In that case the plugin needs both `accountId` and `userId` so it can scope memories correctly. The setup wizard detects this automatically and returns:\r\n\r\n```\r\nRoot API key detected. Missing: --account-id, --user-id\r\n```\r\n\r\nWhen you see this:\r\n\r\n1. Ask the user for both values (they come from the OpenViking admin).\r\n2. Retry STEP 7 with both flags:\r\n\r\n```bash\r\nopenclaw openviking setup --base-url BASE_URL --api-key API_KEY --account-id ACCOUNT_ID --user-id USER_ID --json\r\n```\r\n\r\nA **user key** (issued per tenant) does not need these flags.\r\n\r\n## Multi-Instance (`--workdir` / `OPENCLAW_STATE_DIR`)\r\n\r\nIf the user runs multiple OpenClaw instances (e.g. testing several agents in parallel), each has its own state dir.\r\n\r\nTo target a non-default instance:\r\n\r\n```bash\r\nnpx -y openclaw-openviking-setup-helper@latest --workdir ~/.openclaw-second --base-url ... --api-key ...\r\n```\r\n\r\n`ov-install` writes a helper env file when the state dir is non-default:\r\n\r\n- Unix: `~/.openclaw/openviking.env` containing `export OPENCLAW_STATE_DIR='...'`\r\n- Windows: `~/.openclaw/openviking.env.bat` and `.ps1` setting the same variable\r\n\r\nSource it before running `openclaw` commands so they hit the correct state:\r\n\r\n**Unix:**\r\n```bash\r\nsource ~/.openclaw/openviking.env\r\nopenclaw status\r\n```\r\n\r\n**Windows (PowerShell):**\r\n```powershell\r\n. \"$HOME/.openclaw/openviking.env.ps1\"\r\nopenclaw status\r\n```\r\n\r\nOr pass `--workdir` directly to each `openclaw` invocation (note: not all `openclaw` subcommands honor `--workdir` consistently — when in doubt, prefer the env var).\r\n\r\n## Daily Operations\r\n\r\n```bash\r\n# Start or restart OpenClaw gateway after config changes\r\nopenclaw gateway restart\r\n\r\n# Check overall status\r\nopenclaw status\r\nopenclaw openviking status --json\r\n\r\n# Read current OpenViking slot\r\nopenclaw config get plugins.slots.contextEngine\r\n\r\n# Disable OpenViking memory (keep config, deactivate slot)\r\nopenclaw config set plugins.slots.contextEngine legacy\r\nopenclaw gateway restart\r\n\r\n# Re-enable\r\nopenclaw config set plugins.slots.contextEngine openviking\r\nopenclaw gateway restart\r\n```\r\n\r\n## Uninstall\r\n\r\n### Preferred: via OpenClaw plugin manager\r\n\r\n```bash\r\nopenclaw plugins uninstall openviking\r\nopenclaw config set plugins.slots.contextEngine legacy\r\nopenclaw gateway restart\r\n```\r\n\r\n### If installed through backup `ov-install`\r\n\r\n```bash\r\nnpx -y openclaw-openviking-setup-helper@latest --uninstall\r\n```\r\n\r\nThis will:\r\n\r\n1. Stop the OpenClaw gateway.\r\n2. Back up `openclaw.json`.\r\n3. Remove all OpenViking plugin config from `openclaw.json` (`plugins.entries.openviking`, `plugins.allow`, `plugins.installs.openviking`, `plugins.slots.contextEngine`).\r\n4. Move the plugin directory to `disabled-extensions/` as backup.\r\n5. Remove the helper env files (`openviking.env`, `.bat`, `.ps1`).\r\n\r\nAdd `--base-url dummy` for fully non-interactive mode (skips the confirmation prompt).\r\n\r\n### Manual\r\n\r\n```bash\r\nopenclaw gateway stop\r\nopenclaw config set plugins.slots.contextEngine legacy\r\n# Then edit ~/.openclaw/openclaw.json and remove openviking from\r\n#   plugins.entries\r\n#   plugins.allow\r\n#   plugins.installs\r\nopenclaw gateway restart\r\n```\r\n\r\n## Error Recovery Reference\r\n\r\nMatch against actual stderr / JSON `error` strings.\r\n\r\n| Symptom (exact string) | Likely cause | Fix |\r\n|---|---|---|\r\n| `command not found: openclaw` | OpenClaw not installed | Stop. Ask user to install OpenClaw >= 2026.4.8. |\r\n| `command not found: node` / `'node' is not recognized` | Node missing | Stop. Ask user to install Node.js >= 22. |\r\n| `429` / `rate limit` / `Too Many Requests` from `plugins install` | ClawHub throttle | Switch to backup Path B (`ov-install`). |\r\n| `not logged in` / `please log in` from `plugins install` | Anonymous user hit limit | Switch to backup Path B (`ov-install`). |\r\n| `ECONNREFUSED` / `connection refused` on `BASE_URL/health` | Server not running | Server-not-ready handling in STEP 5. |\r\n| `ETIMEDOUT` on `BASE_URL/health` | Network blocked | Ask about firewall / VPN / proxy. |\r\n| `--json requires --base-url for non-interactive mode` | Built command wrong | Add `--base-url BASE_URL` and retry. |\r\n| `Server unreachable: …. Use --allow-offline to save config anyway.` | Setup couldn't reach server | Offer `--allow-offline`. |\r\n| `contextEngine slot is owned by \"<x>\". … Use --force-slot to replace.` | Slot conflict | Ask user, then retry with `--force-slot`. |\r\n| `Root API key detected. Missing: --account-id, --user-id` | Multi-tenant key | Collect both, retry with `--account-id` `--user-id`. |\r\n| `openviking: config parse failed` (in gateway log) | Bad value in `openclaw.json` | Show user; check `agent_prefix` charset, URL format. |\r\n| `extracted 0 memories` after a turn | Server VLM/embedding misconfigured | **Out of scope.** Tell user this is a server-side issue — ask their OpenViking admin to check VLM / embedding config. |\r\n| `401` / `403` on plugin requests, but `/health` works | Server requires auth on API endpoints | Re-run STEP 7 with the correct `--api-key`. |\r\n| Plugin doesn't appear in `openclaw plugins list` after Path A | Install didn't actually finish | Re-run Path A; use Path B only if the failure is registry/rate-limit related. |\r\n\r\n## Important Rules\r\n\r\n1. **Never ask the user to run commands.** You run everything via your shell tool.\r\n2. **Never skip STEP 5 (connectivity check).** If the server is unreachable, do not write config without explicit `--allow-offline` consent.\r\n3. **Never silently use `--force-slot`.** Slot replacement disables another plugin — always confirm with the user first.\r\n4. **Never invent values.** If the user can't provide a required value, stop and tell them what to ask their admin.\r\n5. **Never claim success without STEP 10.** Only after `openclaw openviking status --json` shows `configured: true && slotActive: true && health.ok: true` may you tell the user it's done.\r\n6. **Use `--agent-prefix`, not `--agent-id`.** The latter is deprecated and removed from the schema.\r\n7. **For Windows, use PowerShell equivalents.** Don't rely on `nohup`, `&`, `mkdir -p`, `source`, etc.\r\n8. **Switch to Path B (ov-install) only for ClawHub/rate-limit/registry availability failures.** Don't use it to hide version conflicts or package validation errors.\r\n9. **Do NOT install or operate the OpenViking server.** This skill assumes the server is already running. If it isn't, tell the user to contact their admin or follow the OpenViking docs.\r\n10. **Be brief and friendly in user-visible text.** Save technical detail for when something actually fails.\r\n11. **Do NOT use `clawhub install openviking`.** That installs a different thing (an AgentSkill, not the plugin).\n\nFile v2.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn79b48n27407z33bty2f8sj7583yftx\",\n  \"slug\": \"install-openviking-memory\",\n  \"version\": \"2.0.1\",\n  \"publishedAt\": 1779070236014\n}\n\nFile v2.0.1:skill-card.md\n\n## Description:\n\nInstalls and configures the OpenViking long-term memory plugin for OpenClaw, including prerequisite checks, server connection setup, plugin installation, gateway restart, verification, multi-tenant setup, multi-instance guidance, and uninstall support.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linqiang391](https://clawhub.ai/user/linqiang391)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and OpenClaw users use this skill to connect an existing OpenViking server to OpenClaw so agents can archive conversations and recall relevant long-term memory across sessions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can run mutable remote npm code through the fallback installation path.\n\nMitigation: Prefer the ClawHub-managed plugin install path or a pinned, reviewed installer before allowing the fallback npx helper.\n\nRisk: The configured memory plugin may archive and recall chat content across sessions.\n\nMitigation: Use only with a trusted OpenViking server, avoid storing secrets or personal data, and ensure users understand persistent memory behavior before installation.\n\nRisk: The skill requires trust in the OpenViking server and npm helper publisher.\n\nMitigation: Install only after confirming the server operator and helper package publisher are trusted for the deployment.\n\n## Reference(s):\n\n- [OpenViking](https://github.com/volcengine/OpenViking)\n- [ClawHub Skill Page](https://clawhub.ai/linqiang391/skills/install-openviking-memory)\n\n## Skill Output:\n\n**Output Type(s):** [Shell commands, Configuration, Guidance, Markdown]\n\n**Output Format:** [Markdown with shell commands and configuration guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May run OpenClaw and npm installation commands, write OpenClaw plugin configuration, restart the OpenClaw gateway, and verify status with JSON output.]\n\n## Skill Version(s):\n\n2.0.1 (source: frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.0.0: 2 files, 11544 bytes\n\nFiles: SKILL.md (28507b), _meta.json (144b)\n\nFile v2.0.0:SKILL.md\n\n---\r\nname: install-openviking-memory\r\ndescription: >\r\n  Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation.\r\n  Once installed, the plugin automatically captures important facts from chats and recalls relevant\r\n  context before each reply (auto-capture + auto-recall, cross-session). Covers prerequisites check,\r\n  plugin install (with clawhub-fallback to ov-install), wizard-based configuration, slot activation,\r\n  gateway restart, verification, plus multi-tenant root-key support, multi-instance, and uninstall.\r\n  Trigger when the user says any of: \"install OpenViking\", \"set up memory\", \"configure memory plugin\",\r\n  \"add long-term memory\", \"connect to OpenViking server\", \"RAG\", \"semantic memory\",\r\n  \"帮我装 OpenViking\", \"配置记忆插件\", \"安装记忆功能\", \"接入 OpenViking\", \"我有一台 OpenViking 服务器\".\r\n  The user does NOT need to know any CLI commands — the agent runs everything and only asks for a few values.\r\n  This skill assumes the OpenViking server is already running. If the server is not ready, the skill\r\n  tells the user to contact their admin or set it up via the OpenViking docs — it does NOT install the server.\r\nversion: 2.0.0\r\nmetadata:\r\n  openclaw:\r\n    requires:\r\n      bins:\r\n        - node\r\n        - openclaw\r\n  emoji: \"🦣\"\r\n  homepage: \"https://github.com/volcengine/OpenViking\"\r\ntags:\r\n  - install\r\n  - setup\r\n  - memory\r\n  - openviking\r\n  - rag\r\n  - long-term-memory\r\n---\r\n\r\n# Install OpenViking Memory — Agent Installation & Reference Skill\r\n\r\nYou are about to help a user install and configure the OpenViking memory plugin for OpenClaw.\r\nThe 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.\r\n\r\n**Read this entire document before starting. Follow every step in order. Do NOT skip steps.**\r\n\r\nThis skill is split into two halves:\r\n\r\n- **Part 1 (STEP 0–10): Natural-language installation walkthrough.** Use this on first install or reconfigure.\r\n- **Part 2: Reference.** Tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery. Read on demand.\r\n\r\n> **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.\r\n\r\n---\r\n\r\n# Part 1 — Natural-Language Installation Walkthrough\r\n\r\n## STEP 0: Detect Language\r\n\r\nIf the user's first message contains Chinese characters, respond in **Chinese** throughout.\r\nOtherwise respond in **English**.\r\nAll user-facing messages below have (CN)/(EN) variants — use the matching one.\r\n\r\nDo NOT show this step to the user.\r\n\r\n---\r\n\r\n## STEP 1: Detect Operating System (silently)\r\n\r\nRun this command and remember the result. Do NOT show it to the user.\r\n\r\n```bash\r\nuname -s 2>/dev/null || echo WINDOWS\r\n```\r\n\r\n- Output contains `Darwin` → `OS=mac`\r\n- Output contains `Linux` → `OS=linux`\r\n- Output is `WINDOWS` or the command fails → `OS=windows`\r\n\r\n---\r\n\r\n## STEP 2: Check Prerequisites (silently)\r\n\r\nRun silently:\r\n\r\n```bash\r\nnode -v\r\nopenclaw --version\r\n```\r\n\r\n**If `node` is missing:**\r\n\r\n> (CN) 你的系统没有安装 Node.js。OpenClaw 和 OpenViking 插件需要 Node.js >= 22。请先安装 Node.js，然后再回来找我。\r\n> (EN) Node.js is not installed. OpenClaw and the OpenViking plugin require Node.js >= 22. Please install Node.js first, then come back.\r\n\r\n**Stop. Do NOT continue.**\r\n\r\n**If `openclaw` is missing:**\r\n\r\n> (CN) 你的系统没有安装 OpenClaw。请先安装 OpenClaw（>= 2026.3.7），然后再回来找我。\r\n> (EN) OpenClaw is not installed. Please install OpenClaw (>= 2026.3.7) first, then come back.\r\n\r\n**Stop. Do NOT continue.**\r\n\r\nIf both exist, proceed to STEP 3 silently.\r\n\r\n---\r\n\r\n## STEP 3: Greet and Ask for 3 Values\r\n\r\nSend this message:\r\n\r\n> (CN) 好，我来帮你接入 OpenViking 长期记忆。装好之后，我会自动记住对话里的重要信息，下次聊也能回忆起来。\r\n>\r\n> 我需要 3 条信息，不知道的可以问你的管理员：\r\n> 1. **OpenViking 服务地址** —— 例如 `https://ov.example.com` 或 `http://192.168.1.100:1933`，本机服务可以直接说\"本机\"\r\n> 2. **API Key** —— 用来鉴权；服务没开认证可以说\"没有\"\r\n> 3. **Agent 标识前缀**（可选） —— 用于区分多个 agent 的记忆命名空间，留空就用默认\r\n>\r\n> 先告诉我服务地址吧？\r\n\r\n> (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.\r\n>\r\n> I need 3 things (ask your admin if unsure):\r\n> 1. **OpenViking server URL** — e.g. `https://ov.example.com` or `http://192.168.1.100:1933`. For a local server, just say \"local\".\r\n> 2. **API Key** — for auth. Say \"none\" if the server has no auth.\r\n> 3. **Agent prefix** (optional) — used to namespace memories across agents. Leave blank for default.\r\n>\r\n> What's the server URL?\r\n\r\n---\r\n\r\n## STEP 4: Collect Values\r\n\r\nCollect 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.\r\n\r\n### 4a. `BASE_URL` (REQUIRED)\r\n\r\n- \"local\" / \"本机\" / \"localhost\" → use `http://127.0.0.1:1933`.\r\n- `ov.example.com` without protocol → prepend `https://`.\r\n- Strip trailing `/`, `/health`, or `/api`.\r\n- After normalization must start with `http://` or `https://`.\r\n- 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.**\r\n\r\n### 4b. `API_KEY` (OPTIONAL)\r\n\r\n> (CN) API Key 是什么？服务没开认证就直接说\"没有\"。\r\n> (EN) What's the API Key? Say \"none\" if the server has no auth.\r\n\r\n- \"no\" / \"none\" / \"没有\" / \"空\" / empty → `API_KEY=\"\"` (you will skip the flag later).\r\n- Otherwise store as-is.\r\n\r\n### 4c. `AGENT_PREFIX` (OPTIONAL)\r\n\r\n> (CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、`_`、`-`。\r\n> (EN) Want to set an agent prefix? Leave blank for the default. Letters, digits, `_`, `-` only.\r\n\r\n- Empty / \"default\" / \"默认\" → leave unset (plugin defaults to `\"\"`).\r\n- Otherwise validate against `/^[A-Za-z0-9_-]+$/`. If invalid, ask again.\r\n\r\n### 4d. (Conditional) Multi-Tenant Root-Key Fields\r\n\r\nOnly ask for these if STEP 7 detects a root key (`Root API key detected. Missing: --account-id, --user-id`). Don't ask up front.\r\n\r\n- `ACCOUNT_ID`\r\n- `USER_ID`\r\n\r\nSee **Reference: Multi-Tenant** for what these mean.\r\n\r\n---\r\n\r\n## STEP 5: Pre-flight Connectivity Check (silently)\r\n\r\nTell the user briefly:\r\n\r\n> (CN) 我先测一下能不能连上服务……\r\n> (EN) Let me test the connection to your server...\r\n\r\nRun:\r\n\r\n**If OS=windows:**\r\n\r\n```powershell\r\ntry { (Invoke-WebRequest -Uri \"BASE_URL/health\" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop).StatusCode } catch { $_.Exception.Response.StatusCode.value__ }\r\n```\r\n\r\n**If OS=mac or OS=linux:**\r\n\r\n```bash\r\ncurl -sS -o /dev/null -w \"%{http_code}\" --connect-timeout 10 \"BASE_URL/health\"\r\n```\r\n\r\nReplace `BASE_URL` with the actual value.\r\n\r\n| Status | Meaning | Action |\r\n|---|---|---|\r\n| `200` | Server reachable, no auth on `/health` | Proceed to STEP 6. |\r\n| `401` / `403` | Server reachable but `/health` requires auth | Proceed to STEP 6 — the wizard's key probe will sort it out. |\r\n| `000` / timeout / connection refused | Server unreachable | **Server-not-ready handling** below. |\r\n| Anything else | Unexpected | Show status code to the user, go back to STEP 4a. |\r\n\r\n### Server-not-ready handling\r\n\r\nThis skill **does not install or operate the OpenViking server**. If the user's server is unreachable, present the situation honestly and offer two paths:\r\n\r\n> (CN) ❌ 我连不上 `BASE_URL`。可能是：\r\n> 1) 服务还没启动 —— 请联系你的 OpenViking 服务管理员把它起起来；如果是你自己负责，请参考 OpenViking 官方文档（`https://github.com/volcengine/OpenViking`）的 server 启动指引。\r\n> 2) 地址不对 —— 你可以重新告诉我正确的地址。\r\n> 3) 网络不通（防火墙 / VPN / 内网）—— 你确认一下网络。\r\n>\r\n> 也可以选择\"先把配置写下来\"，等服务起来就自动生效，要这么办吗？\r\n\r\n> (EN) ❌ Cannot reach `BASE_URL`. Likely cause:\r\n> 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.**\r\n> 2) **Wrong URL** — give me the correct URL.\r\n> 3) **Network blocked** (firewall / VPN / private network) — please verify connectivity.\r\n>\r\n> Or I can save the config now (`--allow-offline`) so it will activate automatically once the server is up. Want me to do that?\r\n\r\nIf the user fixes the URL → back to STEP 4a.\r\nIf the user wants `--allow-offline` → remember `ALLOW_OFFLINE=true` and continue to STEP 6.\r\nIf the user gives up / cannot fix → stop here. Do NOT continue with a broken state.\r\n\r\n---\r\n\r\n## STEP 6: Install the Plugin\r\n\r\nThe plugin can be installed two ways. **Always try Path A first.** If it fails — especially due to ClawHub rate limiting / login required — fall back to Path B.\r\n\r\n### Path A — Primary: `openclaw plugins install` (uses ClawHub)\r\n\r\nTell the user:\r\n\r\n> (CN) 现在开始装插件……\r\n> (EN) Installing the plugin now...\r\n\r\nRun:\r\n\r\n```bash\r\nopenclaw plugins install @openclaw/openviking\r\n```\r\n\r\nTrigger fallback to Path B if the output contains any of these strings:\r\n\r\n- `429`\r\n- `rate limit` / `rate-limited` / `Too Many Requests`\r\n- `not logged in` / `please log in` / `please login` / `unauthorized` / `401` / `403` together with `clawhub`\r\n- `ETIMEDOUT` / `ECONNRESET` on a `clawhub`-related host\r\n- generic message indicating the registry refused an anonymous client\r\n\r\nBefore falling back, also try the explicit registry prefix once:\r\n\r\n```bash\r\nopenclaw plugins install clawhub:@openclaw/openviking\r\n```\r\n\r\nIf the install **succeeds**, jump to STEP 7.\r\n\r\nIf both attempts fail — even with non-rate-limit errors (version conflict, missing dep, etc.) — go to Path B. `ov-install` deploys the plugin from GitHub raw and bypasses ClawHub entirely, so it usually still works.\r\n\r\n### Path B — Fallback: `ov-install` (bypasses ClawHub)\r\n\r\nTell the user:\r\n\r\n> (CN) ClawHub 现在好像被限流或者你没登录账号，我换一种方式装，直接从 GitHub 下载，应该会更稳。\r\n> (EN) ClawHub looks rate-limited or unavailable. Let me install via the direct-from-GitHub path instead — it's more reliable.\r\n\r\nRun the installer with `npx` (no global install needed):\r\n\r\n```bash\r\nnpx -y openclaw-openviking-setup-helper@latest --base-url BASE_URL [--api-key API_KEY] [--agent-prefix AGENT_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID]\r\n```\r\n\r\nBuild the flag list according to what the user gave you:\r\n\r\n- Always pass `--base-url BASE_URL`.\r\n- Pass `--api-key API_KEY` only if `API_KEY` is non-empty.\r\n- Pass `--agent-prefix AGENT_PREFIX` only if the user gave one.\r\n- `--account-id` / `--user-id` only if the root-key path requires them.\r\n\r\n`ov-install` will, in one shot:\r\n1. Download plugin sources from `raw.githubusercontent.com` into the OpenClaw `extensions/` dir.\r\n2. Run `npm install --omit=dev` inside the staging dir.\r\n3. Register the plugin in `openclaw.json` (via `openclaw plugins enable` or direct write).\r\n4. Run `openclaw openviking setup --json --base-url … [--api-key …] --force-slot` for the user.\r\n5. Fall back to direct config write if `setup --json` fails.\r\n\r\nThis 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).\r\n\r\nIf `ov-install` exits non-zero, capture the last 30 lines of its output, show them to the user, and stop. Don't retry blindly.\r\n\r\n---\r\n\r\n## STEP 7: Configure (only on Path A — Path B did this for you)\r\n\r\nRun the setup wizard non-interactively. Build flags from collected values:\r\n\r\n```bash\r\nopenclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--agent-prefix AGENT_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot]\r\n```\r\n\r\nRules:\r\n\r\n- `--base-url BASE_URL` is **required** under `--json`. Without it, the wizard prints `--json requires --base-url for non-interactive mode`.\r\n- `--api-key` only if `API_KEY` is non-empty.\r\n- `--agent-prefix` only if the user gave one. Use **`--agent-prefix`**, not `--agent-id` (deprecated and removed).\r\n- `--account-id` / `--user-id` only after STEP 7 root-key detection (see below).\r\n- `--allow-offline` only if the user explicitly approved it in STEP 5.\r\n- `--force-slot` **never** in the first attempt. Add only after the user confirms (see slot_blocked handling below).\r\n\r\n### Parse the JSON output\r\n\r\nThe wizard prints a single JSON object:\r\n\r\n```json\r\n{\r\n  \"success\": true | false,\r\n  \"action\": \"configured\" | \"existing\" | \"error\" | \"slot_blocked\",\r\n  \"config\": { \"mode\": \"remote\", \"baseUrl\": \"...\", \"apiKey\": \"...\", \"agent_prefix\": \"...\", \"accountId\": \"...\", \"userId\": \"...\" },\r\n  \"health\": { \"ok\": true, \"status\": 200 },\r\n  \"keyProbe\": { \"keyType\": \"user_key\" | \"root_key\" | \"none\", \"ok\": true },\r\n  \"slot\": { \"ok\": true, \"owner\": \"openviking\" },\r\n  \"error\": \"...\"\r\n}\r\n```\r\n\r\n### Decision matrix\r\n\r\n| Condition | Action |\r\n|---|---|\r\n| `success: true` and `action: \"configured\"` or `\"existing\"` | Done. Proceed to STEP 9. |\r\n| `success: false` and `action: \"slot_blocked\"` | **Slot conflict — see below.** |\r\n| `success: false` and `error` contains `\"Server unreachable\"` | Connectivity broke between STEP 5 and STEP 7. Offer `--allow-offline`; if accepted, retry. Otherwise back to STEP 4a. |\r\n| `success: false` and `error` contains `\"Root API key detected\"` and `\"Missing: --account-id, --user-id\"` | **Root-key path — see below.** |\r\n| `success: false` and `error` contains `\"Invalid API key\"` / `keyProbe.keyType: \"none\"` with `ok: false` | API key wrong. Back to STEP 4b. |\r\n| `success: false` and any other `action: \"error\"` | Show `error` to the user, stop. Do NOT pretend success. |\r\n\r\n### Slot conflict (`slot_blocked`)\r\n\r\nThe error text looks like:\r\n\r\n> `contextEngine slot is owned by \"<other-plugin>\". Config was saved but slot was NOT changed. Use --force-slot to replace.`\r\n\r\n**Do NOT silently use `--force-slot`.** Ask the user:\r\n\r\n> (CN) 你的 OpenClaw 当前 contextEngine 槽被 `<other-plugin>` 占着。如果用 OpenViking 替换它，`<other-plugin>` 就不再生效。要替换吗？\r\n> (EN) Your `contextEngine` slot is currently owned by `<other-plugin>`. Activating OpenViking will disable it. Replace?\r\n\r\nIf the user agrees, retry the same setup command with `--force-slot` appended. If they decline, tell them config has been saved but the slot is unchanged, and stop.\r\n\r\n### Root-key path\r\n\r\nThe error text looks like:\r\n\r\n> `Root API key detected. Missing: --account-id, --user-id. Provide both to enable multi-tenant scoping.`\r\n\r\nAsk the user:\r\n\r\n> (CN) 你给的是 root 级 API Key，需要再补两个值才能用：账户 ID（accountId）和用户 ID（userId）。这两个一般是 OpenViking 服务管理员配的，不知道就问他们。\r\n> (EN) Your API key is a root key, which needs two more values: `accountId` and `userId`. Both come from your OpenViking server admin — ask them if unsure.\r\n\r\nAfter collecting, retry the setup command with `--account-id` and `--user-id` appended.\r\n\r\n---\r\n\r\n## STEP 8: (Reserved — done inside STEP 7 or by `ov-install`)\r\n\r\nThe setup wizard already wrote `plugins.entries.openviking.config.*` and (if successful) set `plugins.slots.contextEngine = \"openviking\"`. There is no separate STEP 8 — go to STEP 9.\r\n\r\n---\r\n\r\n## STEP 9: Restart the Gateway\r\n\r\n```bash\r\nopenclaw gateway restart\r\n```\r\n\r\nIf it fails, try once more with:\r\n\r\n```bash\r\nopenclaw gateway --force\r\n```\r\n\r\nIf both fail:\r\n\r\n> (CN) Gateway 没能自动重启。请你手动跑一下 `openclaw gateway restart`。重启完告诉我，我来验证。\r\n> (EN) Gateway didn't restart cleanly. Please run `openclaw gateway restart` manually, then tell me when it's done so I can verify.\r\n\r\nWait ~3 seconds before STEP 10.\r\n\r\n---\r\n\r\n## STEP 10: Verify\r\n\r\n```bash\r\nopenclaw openviking status --json\r\n```\r\n\r\nExpected output:\r\n\r\n```json\r\n{\r\n  \"configured\": true,\r\n  \"slotActive\": true,\r\n  \"health\": { \"ok\": true },\r\n  \"config\": { \"baseUrl\": \"...\", \"agent_prefix\": \"...\" }\r\n}\r\n```\r\n\r\n### Decision\r\n\r\n- `configured: true` **and** `slotActive: true` **and** `health.ok: true` → **success.** Send the success message below.\r\n- `configured: true` but `slotActive: false` → if you previously skipped `--force-slot`, ask the user about replacing now and retry STEP 7 with `--force-slot`. Otherwise it's a gateway restart issue — back to STEP 9.\r\n- `configured: true` but `health.ok: false` → server became unreachable. Tell the user; the config will start working as soon as the server is back.\r\n- `configured: false` → setup didn't actually persist. Show full status JSON to the user and stop.\r\n\r\n### Success message\r\n\r\n> (CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。\r\n>\r\n> 从现在起：\r\n> - **自动记忆**：对话里的重要信息会被自动抽取并保存\r\n> - **自动回忆**：我每轮回复前会先搜一下相关记忆并带进上下文\r\n> - **跨会话**：下次开新对话也能记得之前讲过的事\r\n>\r\n> 你可以试试说\"记住我的邮箱是 xxx@example.com\"来验证。\r\n\r\n> (EN) 🎉 All set! OpenViking long-term memory is connected.\r\n>\r\n> From now on:\r\n> - **Auto-capture**: important info from our chats is extracted and stored\r\n> - **Auto-recall**: relevant memories are searched and injected before each of my replies\r\n> - **Cross-session**: I'll remember things from earlier conversations\r\n>\r\n> Try saying \"Remember my email is xxx@example.com\" to test it.\r\n\r\n---\r\n\r\n# Part 2 — Reference\r\n\r\n## How It Works\r\n\r\n- **Auto-Capture**: at the end of each user turn, the plugin extracts memories from user/assistant messages.\r\n  - `semantic` mode (default): captures all qualifying user text, relying on OpenViking's extraction pipeline to filter.\r\n  - `keyword` mode: only captures text matching trigger words (e.g. \"remember\", \"preference\", etc.).\r\n- **Auto-Recall**: before each prompt build, the plugin searches relevant memories and injects them into context.\r\n\r\n## Available Tools\r\n\r\nThese are the plugin tools the agent can call once installed.\r\n\r\n### `memory_recall` — Search Memories\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `query` | Yes | Search query text |\r\n| `limit` | No | Maximum number of results (defaults to plugin config) |\r\n| `scoreThreshold` | No | Minimum relevance score 0–1 (defaults to plugin config) |\r\n| `targetUri` | No | Search scope URI (defaults to plugin config) |\r\n\r\nExample: user asks \"What programming language did I say I like?\"\r\n\r\n### `memory_store` — Manual Store\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `text` | Yes | Information text to store |\r\n| `role` | No | Session role (default `user`) |\r\n| `sessionId` | No | Existing OpenViking session ID |\r\n\r\nExample: user says \"Remember my email is xxx@example.com\".\r\n\r\n### `memory_forget` — Delete Memories\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `uri` | No | Exact memory URI (direct delete) |\r\n| `query` | No | Search query (find then delete) |\r\n| `targetUri` | No | Search scope URI |\r\n| `limit` | No | Search limit (default 5) |\r\n| `scoreThreshold` | No | Minimum relevance score |\r\n\r\nExample: user says \"Forget my phone number\".\r\n\r\n## Configuration Schema\r\n\r\nThese are the keys under `plugins.entries.openviking.config` in `openclaw.json`. The setup wizard / `ov-install` sets the first few; the rest are tunables.\r\n\r\n| Field | Default | Description |\r\n|---|---|---|\r\n| `mode` | `\"remote\"` (forced by plugin) | Always remote in this skill. Don't set manually. |\r\n| `baseUrl` | `http://127.0.0.1:1933` | OpenViking server URL. |\r\n| `apiKey` | — | API key. Optional if server has no auth. |\r\n| `agent_prefix` | `\"\"` | Prefix for routing memories per agent. Letters / digits / `_` / `-`. |\r\n| `accountId` | — | Required when `apiKey` is a root key. |\r\n| `userId` | — | Required when `apiKey` is a root key. |\r\n| `targetUri` | `viking://user/memories` | Default search scope URI. |\r\n| `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |\r\n| `autoCapture` | `true` | Auto-capture memories at end of turn. |\r\n| `captureMode` | `\"semantic\"` | `semantic` or `keyword`. |\r\n| `captureMaxLength` | `24000` | Max text length captured per turn. |\r\n| `autoRecall` | `true` | Auto-recall and inject memories before reply. |\r\n| `recallLimit` | `6` | Max memories injected per recall. |\r\n| `recallScoreThreshold` | `0.15` | Min relevance score to inject. |\r\n| `recallMaxInjectedChars` | (plugin default) | Hard cap on injected character count. |\r\n| `recallPreferAbstract` | (plugin default) | Prefer abstract memories over raw. |\r\n| `recallTokenBudget` | (plugin default) | Token budget for injected memories. |\r\n| `isolateUserScopeByAgent` | (plugin default) | Multi-tenant scoping toggle. |\r\n| `isolateAgentScopeByUser` | (plugin default) | Multi-tenant scoping toggle. |\r\n| `agentScopeMode` | (plugin default) | Agent scope strategy. |\r\n| `bypassSessionPatterns` | — | Glob patterns for sessions skipped by capture. |\r\n| `ingestReplyAssist` | (plugin default) | Reply-assist ingestion toggle. |\r\n| `emitStandardDiagnostics` | (plugin default) | Verbose diagnostic logs. |\r\n| `logFindRequests` | (plugin default) | Log retrieval requests. |\r\n\r\nTo change a value:\r\n\r\n```bash\r\nopenclaw config set plugins.entries.openviking.config.<field> <value>\r\nopenclaw gateway restart\r\n```\r\n\r\n## Multi-Tenant (Root API Keys)\r\n\r\nSome OpenViking deployments use a single **root** API key shared across tenants. In that case the plugin needs both `accountId` and `userId` so it can scope memories correctly. The setup wizard detects this automatically and returns:\r\n\r\n```\r\nRoot API key detected. Missing: --account-id, --user-id\r\n```\r\n\r\nWhen you see this:\r\n\r\n1. Ask the user for both values (they come from the OpenViking admin).\r\n2. Retry STEP 7 with both flags:\r\n\r\n```bash\r\nopenclaw openviking setup --base-url BASE_URL --api-key API_KEY --account-id ACCOUNT_ID --user-id USER_ID --json\r\n```\r\n\r\nA **user key** (issued per tenant) does not need these flags.\r\n\r\n## Multi-Instance (`--workdir` / `OPENCLAW_STATE_DIR`)\r\n\r\nIf the user runs multiple OpenClaw instances (e.g. testing several agents in parallel), each has its own state dir.\r\n\r\nTo target a non-default instance:\r\n\r\n```bash\r\nnpx -y openclaw-openviking-setup-helper@latest --workdir ~/.openclaw-second --base-url ... --api-key ...\r\n```\r\n\r\n`ov-install` writes a helper env file when the state dir is non-default:\r\n\r\n- Unix: `~/.openclaw/openviking.env` containing `export OPENCLAW_STATE_DIR='...'`\r\n- Windows: `~/.openclaw/openviking.env.bat` and `.ps1` setting the same variable\r\n\r\nSource it before running `openclaw` commands so they hit the correct state:\r\n\r\n**Unix:**\r\n```bash\r\nsource ~/.openclaw/openviking.env\r\nopenclaw status\r\n```\r\n\r\n**Windows (PowerShell):**\r\n```powershell\r\n. \"$HOME/.openclaw/openviking.env.ps1\"\r\nopenclaw status\r\n```\r\n\r\nOr pass `--workdir` directly to each `openclaw` invocation (note: not all `openclaw` subcommands honor `--workdir` consistently — when in doubt, prefer the env var).\r\n\r\n## Daily Operations\r\n\r\n```bash\r\n# Start or restart OpenClaw gateway after config changes\r\nopenclaw gateway restart\r\n\r\n# Check overall status\r\nopenclaw status\r\nopenclaw openviking status --json\r\n\r\n# Read current OpenViking slot\r\nopenclaw config get plugins.slots.contextEngine\r\n\r\n# Disable OpenViking memory (keep config, deactivate slot)\r\nopenclaw config set plugins.slots.contextEngine legacy\r\nopenclaw gateway restart\r\n\r\n# Re-enable\r\nopenclaw config set plugins.slots.contextEngine openviking\r\nopenclaw gateway restart\r\n```\r\n\r\n## Uninstall\r\n\r\n### Preferred: via `ov-install`\r\n\r\n```bash\r\nnpx -y openclaw-openviking-setup-helper@latest --uninstall\r\n```\r\n\r\nThis will:\r\n\r\n1. Stop the OpenClaw gateway.\r\n2. Back up `openclaw.json`.\r\n3. Remove all OpenViking plugin config from `openclaw.json` (`plugins.entries.openviking`, `plugins.allow`, `plugins.installs.openviking`, `plugins.slots.contextEngine`).\r\n4. Move the plugin directory to `disabled-extensions/` as backup.\r\n5. Remove the helper env files (`openviking.env`, `.bat`, `.ps1`).\r\n\r\nAdd `--base-url dummy` for fully non-interactive mode (skips the confirmation prompt).\r\n\r\n### Manual\r\n\r\n```bash\r\nopenclaw gateway stop\r\nopenclaw config set plugins.slots.contextEngine legacy\r\n# Then edit ~/.openclaw/openclaw.json and remove openviking from\r\n#   plugins.entries\r\n#   plugins.allow\r\n#   plugins.installs\r\nopenclaw gateway restart\r\n```\r\n\r\n## Error Recovery Reference\r\n\r\nMatch against actual stderr / JSON `error` strings.\r\n\r\n| Symptom (exact string) | Likely cause | Fix |\r\n|---|---|---|\r\n| `command not found: openclaw` | OpenClaw not installed | Stop. Ask user to install OpenClaw >= 2026.3.7. |\r\n| `command not found: node` / `'node' is not recognized` | Node missing | Stop. Ask user to install Node.js >= 22. |\r\n| `429` / `rate limit` / `Too Many Requests` from `plugins install` | ClawHub throttle | Switch to Path B (`ov-install`). |\r\n| `not logged in` / `please log in` from `plugins install` | Anonymous user hit limit | Switch to Path B (`ov-install`). |\r\n| `ECONNREFUSED` / `connection refused` on `BASE_URL/health` | Server not running | Server-not-ready handling in STEP 5. |\r\n| `ETIMEDOUT` on `BASE_URL/health` | Network blocked | Ask about firewall / VPN / proxy. |\r\n| `--json requires --base-url for non-interactive mode` | Built command wrong | Add `--base-url BASE_URL` and retry. |\r\n| `Server unreachable: …. Use --allow-offline to save config anyway.` | Setup couldn't reach server | Offer `--allow-offline`. |\r\n| `contextEngine slot is owned by \"<x>\". … Use --force-slot to replace.` | Slot conflict | Ask user, then retry with `--force-slot`. |\r\n| `Root API key detected. Missing: --account-id, --user-id` | Multi-tenant key | Collect both, retry with `--account-id` `--user-id`. |\r\n| `openviking: config parse failed` (in gateway log) | Bad value in `openclaw.json` | Show user; check `agent_prefix` charset, URL format. |\r\n| `extracted 0 memories` after a turn | Server VLM/embedding misconfigured | **Out of scope.** Tell user this is a server-side issue — ask their OpenViking admin to check VLM / embedding config. |\r\n| `401` / `403` on plugin requests, but `/health` works | Server requires auth on API endpoints | Re-run STEP 7 with the correct `--api-key`. |\r\n| Plugin doesn't appear in `openclaw plugins list` after Path A | Install didn't actually finish | Re-run Path A or fall through to Path B. |\r\n\r\n## Important Rules\r\n\r\n1. **Never ask the user to run commands.** You run everything via your shell tool.\r\n2. **Never skip STEP 5 (connectivity check).** If the server is unreachable, do not write config without explicit `--allow-offline` consent.\r\n3. **Never silently use `--force-slot`.** Slot replacement disables another plugin — always confirm with the user first.\r\n4. **Never invent values.** If the user can't provide a required value, stop and tell them what to ask their admin.\r\n5. **Never claim success without STEP 10.** Only after `openclaw openviking status --json` shows `configured: true && slotActive: true && health.ok: true` may you tell the user it's done.\r\n6. **Use `--agent-prefix`, not `--agent-id`.** The latter is deprecated and removed from the schema.\r\n7. **For Windows, use PowerShell equivalents.** Don't rely on `nohup`, `&`, `mkdir -p`, `source`, etc.\r\n8. **Switch to Path B (ov-install) on the first sign of rate limiting.** Don't retry Path A repeatedly — `ov-install` bypasses ClawHub.\r\n9. **Do NOT install or operate the OpenViking server.** This skill assumes the server is already running. If it isn't, tell the user to contact their admin or follow the OpenViking docs.\r\n10. **Be brief and friendly in user-visible text.** Save technical detail for when something actually fails.\r\n11. **Do NOT use `clawhub install openviking`.** That installs a different thing (an AgentSkill, not the plugin).\n\nFile v2.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn79b48n27407z33bty2f8sj7583yftx\",\n  \"slug\": \"install-openviking-memory\",\n  \"version\": \"2.0.0\",\n  \"publishedAt\": 1778002370864\n}","readmeExcerpt":"Skill: Install Openviking Memory Owner: linqiang391 Summary: Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa... Tags: install:2.0.0, latest:2.0.1, latest install setup memory openviking rag:2.0.1, memory:2.0.0, openviking:2.0.0, rag:2.0.0, setup:2.0.0 Version history: v2.0.1 | 2026-05-18T02:10:36.014Z | user ","codeSnippets":[],"executableExamples":[],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: install-openviking-memory\r\ndescription: >\r\n  Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation.\r\n  Once installed, the plugin automatically captures important facts from chats and recalls relevant\r\n  context before each reply (auto-capture + auto-recall, cross-session). Covers prerequisites check,\r\n  plugin install through OpenClaw's plugin manager first, with ov-install only as a backup path,\r\n  wizard-based configuration, slot activation,\r\n  gateway restart, verification, plus multi-tenant root-key support, multi-instance, and uninstall.\r\n  Trigger when the user says any of: \"install OpenViking\", \"set up memory\", \"configure memory plugin\",\r\n  \"add long-term memory\", \"connect to OpenViking server\", \"RAG\", \"semantic memory\",\r\n  \"帮我装 OpenViking\", \"配置记忆插件\", \"安装记忆功能\", \"接入 OpenViking\", \"我有一台 OpenViking 服务器\".\r\n  The user does NOT need to know any CLI commands — the agent runs everything and only asks for a few values.\r\n  This skill assumes the OpenViking server is already running. If the server is not ready, the skill\r\n  tells the user to contact their admin or set it up via the OpenViking docs — it does NOT install the server.\r\nversion: 2.0.1\nmetadata:\r\n  openclaw:\r\n    requires:\r\n      bins:\r\n        - node\r\n        - openclaw\r\n  emoji: \"🦣\"\r\n  homepage: \"https://github.com/volcengine/OpenViking\"\r\ntags:\r\n  - install\r\n  - setup\r\n  - memory\r\n  - openviking\r\n  - rag\r\n  - long-term-memory\r\n---\r\n\r\n# Install OpenViking Memory — Agent Installation & Reference Skill\r\n\r\nYou are about to help a user install and configure the OpenViking memory plugin for OpenClaw.\r\nThe 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.\r\n\r\n**Read this entire document before starting. Follow every step in order. Do NOT skip steps.**\r\n\r\nThis skill is split into two halves:\r\n\r\n- **Part 1 (STEP 0–10): Natural-language installation walkthrough.** Use this on first install or reconfigure.\r\n- **Part 2: Reference.** Tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery. Read on demand.\r\n\r\n> **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.\r\n\r\n---\r\n\r\n# Part 1 — Natural-Language Installation Walkthrough\r\n\r\n## STEP 0: Detect Language\r\n\r\nIf the user's first message contains Chinese characters, respond in **Chinese** throughout.\r\nOtherwise respond in **English**.\r\nAll user-facing messages below have (CN)/(EN) variants — use the matching one.\r\n\r\nDo NOT show this step to the user.\r\n\r\n---\r\n\r\n## STEP 1: Detect Operating System (silently)\r\n\r\nRun this command and remember the result. Do NOT show it to the user.\r\n\r\n```bash\r\nuname -s 2>/dev/null || echo WINDOWS\r\n```\r\n\r\n- Output contains `Darwin` → `OS=mac`\r\n- "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn79b48n27407z33bty2f8sj7583yftx\",\n  \"slug\": \"install-openviking-memory\",\n  \"version\": \"2.0.1\",\n  \"publishedAt\": 1779070236014\n}"},{"path":"skill-card.md","content":"## Description:\n\nInstalls and configures the OpenViking long-term memory plugin for OpenClaw, including prerequisite checks, server connection setup, plugin installation, gateway restart, verification, multi-tenant setup, multi-instance guidance, and uninstall support.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linqiang391](https://clawhub.ai/user/linqiang391)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and OpenClaw users use this skill to connect an existing OpenViking server to OpenClaw so agents can archive conversations and recall relevant long-term memory across sessions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can run mutable remote npm code through the fallback installation path.\n\nMitigation: Prefer the ClawHub-managed plugin install path or a pinned, reviewed installer before allowing the fallback npx helper.\n\nRisk: The configured memory plugin may archive and recall chat content across sessions.\n\nMitigation: Use only with a trusted OpenViking server, avoid storing secrets or personal data, and ensure users understand persistent memory behavior before installation.\n\nRisk: The skill requires trust in the OpenViking server and npm helper publisher.\n\nMitigation: Install only after confirming the server operator and helper package publisher are trusted for the deployment.\n\n## Reference(s):\n\n- [OpenViking](https://github.com/volcengine/OpenViking)\n- [ClawHub Skill Page](https://clawhub.ai/linqiang391/skills/install-openviking-memory)\n\n## Skill Output:\n\n**Output Type(s):** [Shell commands, Configuration, Guidance, Markdown]\n\n**Output Format:** [Markdown with shell commands and configuration guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May run OpenClaw and npm installation commands, write OpenClaw plugin configuration, restart the OpenClaw gateway, and verify status with JSON output.]\n\n## Skill Version(s):\n\n2.0.1 (source: frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa... Skill: Install Openviking Memory Owner: linqiang391 Summary: Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures importa... Tags: install:2.0.0, latest:2.0.1, latest install setup memory openviking rag:2.0.1, memory:2.0.0, openviking:2.0.0, rag:2.0.0, setup:2.0.0 Version history: v2.0.1 | 2026-05-18T02:10:36.014Z | user","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1126,"uniquenessScore":49,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:51:45.566Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:51:45.566Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T09:10:03.346Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}