@openviking/openclaw-plugin 2026.5.8

package/INSTALL-AGENT.md

@@ -0,0 +1,355 @@
+# OpenViking Plugin Agent Install Guide
+
+This guide is for AI agents and operator automation. Prefer deterministic commands, parse JSON output, and ask the user only when a choice changes the outcome.
+
+User-facing docs:
+
+- [INSTALL.md](./INSTALL.md)
+- [INSTALL-ZH.md](./INSTALL-ZH.md)
+
+## Identity
+
+This package is the OpenClaw plugin `@openviking/openclaw-plugin`.
+
+| User intent | Command |
+| --- | --- |
+| Fresh install, latest | `openclaw plugins install @openviking/openclaw-plugin` |
+| Upgrade plugin to latest | `openclaw plugins install @openviking/openclaw-plugin` |
+| Install or upgrade a specific release | Use the published ClawHub package selector if available; otherwise ask before using backup `ov-install --plugin-version=<REF>` |
+| Upgrade only the plugin | `openclaw plugins install @openviking/openclaw-plugin` |
+| Show installed plugins | `openclaw plugins list` |
+| Backup install when ClawHub is unavailable | `npx -y openclaw-openviking-setup-helper@latest --base-url <URL> [--api-key <KEY>]` |
+| Operate on a specific OpenClaw instance | add `--workdir <path>` |
+| Start missing OpenViking server | `openviking-server init && openviking-server doctor && openviking-server` |
+
+Do not install it with:
+
+```bash
+clawhub install openviking
+```
+
+That installs an AgentSkill, not the plugin. The plugin install command is:
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+```
+
+## Required Inputs
+
+Before setup, determine:
+
+| Input | Required | How to get it |
+| --- | --- | --- |
+| OpenViking base URL | Yes | Ask user or read `OPENVIKING_BASE_URL` |
+| API key | Usually | Ask user or read `OPENVIKING_API_KEY` |
+| Account ID | Only for root API keys | Ask user if setup reports root-key tenant context is needed |
+| User ID | Only for root API keys | Ask user if setup reports root-key tenant context is needed |
+| Slot replacement approval | Only if another context engine owns the slot | Ask user before using `--force-slot` |
+
+Never silently replace another context engine.
+
+## Primary Workflow
+
+Use this workflow for normal installs and upgrades from published packages.
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+If the registry prefix is required:
+
+```bash
+openclaw plugins install clawhub:@openviking/openclaw-plugin
+```
+
+## Setup JSON Contract
+
+Run setup with `--json` whenever possible:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+```
+
+Branch on the result:
+
+| JSON result | Meaning | Agent action |
+| --- | --- | --- |
+| `success: true` | Setup completed | Restart gateway, then run status |
+| `success: false`, `action: "slot_blocked"` | Another plugin owns `plugins.slots.contextEngine` | Ask user before rerunning with `--force-slot` |
+| `success: false`, `action: "error"` | Validation failed | Report `error`; do not continue as success |
+| `health.ok: false` | Server unreachable | Check URL/service; use `--allow-offline` only with user approval |
+| `keyProbe.keyType: "root_key"` | Root key requires tenant fields | Rerun with `--account-id <ACCOUNT_ID> --user-id <USER_ID>` |
+| `health.compatibility: "server_too_old"` | Server may not support plugin features | Warn user and recommend server upgrade |
+| `health.compatibility: "server_too_new"` | Plugin may be too old | Warn user and recommend plugin upgrade |
+
+Root-key retry:
+
+```bash
+openclaw openviking setup \
+  --base-url <OPENVIKING_URL> \
+  --api-key <ROOT_API_KEY> \
+  --account-id <ACCOUNT_ID> \
+  --user-id <USER_ID> \
+  --json
+```
+
+Custom agent routing prefix (optional; only when the user explicitly requests a prefix):
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
+```
+
+Slot replacement retry, only after user approval:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
+```
+
+Offline config save, only after user approval:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json
+```
+
+## Status JSON Contract
+
+After restart, run:
+
+```bash
+openclaw openviking status --json
+```
+
+Ready state:
+
+```json
+{
+  "configured": true,
+  "slotActive": true
+}
+```
+
+Also inspect:
+
+| Field | Use |
+| --- | --- |
+| `health.ok` | Confirms server reachability |
+| `health.version` | Records server version |
+| `health.compatibility` | Determines whether to warn |
+| `config.hasApiKey` | Confirms whether an API key was saved |
+| `config.agent_prefix` | Confirms configured agent prefix when present |
+
+## Environment Detection
+
+Check tools:
+
+```bash
+node -v
+openclaw --version
+```
+
+Requirements:
+
+- Node.js >= 22
+- OpenClaw >= 2026.4.8
+
+Version boundaries:
+
+- `2026.4.8` is the minimum supported OpenClaw version for the current `@openviking/openclaw-plugin` plugin.
+- `2026.5.3` starts requiring compiled JavaScript runtime output during package install when a plugin package declares TypeScript entries.
+- `2026.5.4` and later no longer fall back to `.ts` source for installed/global plugin runtime loading when the compiled JavaScript output is missing; the plugin may be skipped.
+- Published ClawHub packages are built before release and include `dist/*.js`, so normal users do not need to build locally.
+- `ov-install` is the backup/source install path. Use it only after the OpenClaw plugin manager or ClawHub path is unavailable/rate-limited, or when the user explicitly asks to install a source ref. For OpenClaw `>= 2026.5.3`, it builds the plugin during installation.
+
+### 3. Detect or start OpenViking server
+
+The OpenClaw plugin only connects to an OpenViking HTTP server. It does not start the server.
+
+Check the default local server first:
+
+```bash
+curl -fsS http://127.0.0.1:1933/health
+```
+
+If no OpenViking server is running and the user wants a local server:
+
+```bash
+pip install openviking --upgrade --force-reinstall
+openviking-server init
+openviking-server doctor
+openviking-server
+```
+
+Keep `openviking-server` running while OpenClaw uses the plugin. Use `http://127.0.0.1:1933` as the plugin `baseUrl` for the default local setup.
+
+For a remote server, confirm the reachable URL with the user and use that URL as `baseUrl`.
+
+If OpenClaw is missing, tell the user to install and initialize OpenClaw:
+
+```bash
+npm install -g openclaw
+openclaw onboard
+```
+
+### 4. Detect existing install state
+
+If the user has multiple OpenClaw state directories, ask which one to operate on before changing config.
+
+## Existing State Detection
+
+Try status first:
+
+```bash
+openclaw openviking status --json
+```
+
+If the command is unavailable, install the plugin first. If it returns `configured: true` and `slotActive: true`, do not reinstall unless the user requested upgrade or reconfigure.
+
+Manual inspection:
+
+```bash
+openclaw config get plugins.entries.openviking.config
+openclaw config get plugins.slots.contextEngine
+openclaw plugins list
+```
+
+## Standard Operations
+
+Fresh install:
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Reconfigure:
+
+```bash
+openclaw openviking setup --reconfigure
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Upgrade:
+
+```bash
+openclaw plugins update openviking
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Uninstall:
+
+```bash
+openclaw plugins uninstall openviking
+openclaw config set plugins.slots.contextEngine legacy
+openclaw gateway restart
+```
+
+Native uninstall may not reset `plugins.slots.contextEngine`. Always run the explicit `config set` step after uninstall.
+
+## Config Fields
+
+Config path:
+
+```text
+plugins.entries.openviking.config
+```
+
+Core fields:
+
+| Field | Meaning |
+| --- | --- |
+| `mode` | Legacy compatibility field. Expected value: `remote`. |
+| `baseUrl` | OpenViking HTTP endpoint |
+| `apiKey` | OpenViking API key |
+| `agent_prefix` | Optional; prefix for OpenClaw agent IDs when set. Interactive setup accepts only letters, digits, `_`, and `-`. If unset, the plugin follows session agent IDs. |
+| `accountId` | Required for root API keys |
+| `userId` | Required for root API keys |
+
+## Verification
+
+Quick verification:
+
+```bash
+openclaw openviking status --json
+```
+
+Manual verification:
+
+```bash
+openclaw config get plugins.slots.contextEngine
+openclaw config get plugins.entries.openviking.config
+openclaw logs --follow
+```
+
+Expected log signal:
+
+```text
+openviking: registered context-engine
+```
+
+Optional end-to-end health check from a repository checkout:
+
+```bash
+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
+```
+
+## Migrate From ov-install
+
+If ov-install was previously used, clean up before switching to `openclaw plugins install`:
+
+Same plugin ID (openviking, >= 0.3.x):
+
+```bash
+rm -rf ~/.openclaw/extensions/openviking/
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --reconfigure
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Old plugin ID (memory-openviking, < 0.3.x):
+
+```bash
+openclaw plugins uninstall memory-openviking 2>/dev/null || true
+openclaw config set plugins.slots.memory none
+rm -rf ~/.openclaw/extensions/memory-openviking/
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Existing config fields are preserved during migration. The new plugin reads old field names at runtime.
+
+- `baseUrl`
+- `apiKey`
+- `agent_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`
+
+## Backup Path: ov-install
+
+`ov-install` is the backup path, not the primary user install path. Use it when `openclaw plugins install @openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when the user explicitly wants a source ref / Git branch install.
+
+Backup install:
+
+```bash
+npm install -g openclaw-openviking-setup-helper
+ov-install
+```
+
+Backup/source commands:
+
+| Intent | Command |
+| --- | --- |
+| Install from a source ref | `ov-install --plugin-version=<REF>` |
+| Non-interactive backup install | `ov-install --base-url <URL> --api-key <KEY>` |
+| Target a non-default OpenClaw state directory | `ov-install --workdir <PATH>` |
+| Show helper-tracked version | `ov-install --current-version` |
+| Update helper-managed install | `ov-install --update` |
+
+For user installs, always try `openclaw plugins install @openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.

package/INSTALL-ZH.md

@@ -0,0 +1,345 @@
+# 为 OpenClaw 安装 OpenViking
+
+OpenViking 通过 `@openviking/openclaw-plugin` 插件为 OpenClaw 提供长期记忆、知识库检索、语义搜索和 RAG 上下文能力。
+
+这份文档同时面向用户和自动化 agent：用户可以按步骤执行，agent 可以按命令和 JSON 结果判断下一步。
+
+## 不要把插件和 Skill 装混
+
+`@openviking/openclaw-plugin` 是 OpenClaw 插件。
+
+不要用下面这个命令安装本插件：
+
+```bash
+clawhub install openviking
+```
+
+这个命令安装的是名为 `openviking` 的 AgentSkill，不是 OpenClaw 插件。
+
+安装插件应使用：
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+```
+
+## 前置要求
+
+| 组件 | 要求 |
+| --- | --- |
+| Node.js | >= 22 |
+| OpenClaw | >= 2026.4.8 |
+
+插件以远程模式连接到已有的 OpenViking 服务。它不会帮你启动 OpenViking server。需要先启动 OpenViking，并保持服务运行，再把插件的 `baseUrl` 指向这个 HTTP 服务。默认本地地址是 `http://127.0.0.1:1933`。
+
+OpenClaw 插件包版本边界：
+
+- `2026.4.8` 是当前插件支持的最低 OpenClaw 版本。
+- `2026.5.3` 开始，OpenClaw 在安装包时会校验 TypeScript 插件入口是否有编译后的 JavaScript 产物。
+- `2026.5.4` 及之后，已安装/全局插件如果缺少编译后的 JavaScript，运行时不再回退加载 `.ts` 源码，插件可能被跳过。
+- 推荐的 `openclaw plugins install @openviking/openclaw-plugin` 会安装已经发布并包含 `dist/*.js` 的插件包，普通用户不需要本地编译。
+- `ov-install` 是备用/源码安装路径。当 ClawHub 或 OpenClaw 插件管理器路径不可用、被限流，或者明确需要测试源码 ref 时才使用。目标 OpenClaw `>= 2026.5.3` 时，它会在安装过程中编译插件。
+
+快速检查：
+
+```bash
+node -v
+openclaw --version
+```
+
+## 启动 OpenViking Server
+
+如果 OpenViking 和 OpenClaw 在同一台机器上，最短流程是：
+
+```bash
+pip install openviking --upgrade --force-reinstall
+openviking-server init
+openviking-server doctor
+openviking-server
+```
+
+`openviking-server init` 用来生成服务端配置，`openviking-server doctor` 用来检查本地模型和 provider 鉴权是否可用，`openviking-server` 才是真正启动 HTTP API 的命令。OpenClaw 使用插件期间，这个服务进程需要一直运行。
+
+后台启动可以用：
+
+```bash
+mkdir -p ~/.openviking/data/log
+nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &
+```
+
+如果 OpenViking 跑在另一台机器上，需要监听可访问的地址和端口，例如：
+
+```bash
+openviking-server --host 0.0.0.0 --port 1933
+```
+
+然后把 OpenClaw 插件的 `baseUrl` 配成对应地址，例如 `http://your-server:1933`。
+
+安装或重启插件前，先确认服务能访问：
+
+```bash
+curl http://127.0.0.1:1933/health
+```
+
+## 推荐安装方式
+
+普通用户、正式环境和 agent 自动安装都优先使用这条路径。
+
+### 1. 安装插件
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+```
+
+如果你的 OpenClaw 环境需要显式 registry 前缀，使用：
+
+```bash
+openclaw plugins install clawhub:@openviking/openclaw-plugin
+```
+
+### 2. 配置插件
+
+用户交互式配置：
+
+```bash
+openclaw openviking setup
+```
+
+Agent 非交互配置：
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+```
+
+示例：
+
+```bash
+openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json
+```
+
+`setup` 会写入 `plugins.entries.openviking.config`，并激活 `plugins.slots.contextEngine=openviking`。
+
+如果 OpenViking 服务暂时不可达，但你仍希望先保存配置：
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json
+```
+
+如果使用 root API key，可能还需要租户上下文：
+
+```bash
+openclaw openviking setup \
+  --base-url <OPENVIKING_URL> \
+  --api-key <ROOT_API_KEY> \
+  --account-id <ACCOUNT_ID> \
+  --user-id <USER_ID> \
+  --json
+```
+
+如果已有其他 context engine 占用 slot，setup 默认不会替换。确认要替换时再使用：
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
+```
+
+如需自定义 agent 路由前缀（可选；多数用户留空即可）：
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
+```
+
+### 3. 重启 OpenClaw Gateway
+
+```bash
+openclaw gateway restart
+```
+
+如果你的 OpenClaw 版本使用不同的重启命令，请使用对应的 gateway 重启方式。
+
+### 4. 验证
+
+```bash
+openclaw openviking status --json
+```
+
+期望结果：
+
+| JSON 字段 | 期望值 |
+| --- | --- |
+| `configured` | `true` |
+| `slotActive` | `true` |
+| `health.ok` | 服务可达时应为 `true` |
+
+也可以直接查看 OpenClaw 配置：
+
+```bash
+openclaw config get plugins.entries.openviking.config
+openclaw config get plugins.slots.contextEngine
+```
+
+`plugins.slots.contextEngine` 应输出 `openviking`。
+
+## Agent 判断规则
+
+Agent 应优先使用 `--json`，并根据这些字段判断下一步：
+
+| 结果 | 含义 | 建议动作 |
+| --- | --- | --- |
+| `success: true` | 配置已保存，setup 完成 | 重启 gateway，然后执行 status |
+| `success: false`, `action: "slot_blocked"` | 配置可能已保存，但其他插件占用 `contextEngine` | 询问用户后再用 `--force-slot` |
+| `success: false`, `action: "error"` | 校验失败 | 展示 `error`，不要宣称安装成功 |
+| `health.ok: false` | 服务不可达 | 检查 URL/服务状态；只有用户接受时才用 `--allow-offline` |
+| `keyProbe.keyType: "root_key"` | root key 需要租户上下文 | 追加 `--account-id` 和 `--user-id` |
+
+## 配置说明
+
+插件配置位于：
+
+```text
+plugins.entries.openviking.config
+```
+
+核心字段：
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `mode` | `remote` | 兼容旧配置的字段。当前只支持 remote。 |
+| `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP 地址 |
+| `apiKey` | 空 | OpenViking API key |
+| `agent_prefix` | 空 | OpenClaw agent ID 的可选前缀；若没有 agent ID，插件使用 `main`。交互式配置只接受字母、数字、`_` 和 `-`。 |
+| `accountId` | 空 | 使用 root API key 时需要 |
+| `userId` | 空 | 使用 root API key 时需要 |
+
+普通修改优先使用 setup：
+
+```bash
+openclaw openviking setup --reconfigure
+```
+
+查看当前配置：
+
+```bash
+openclaw config get plugins.entries.openviking.config
+```
+
+### 配置参数
+
+插件连接到已有的远端 OpenViking 服务。
+
+| 参数 | 默认值 | 含义 |
+| --- | --- | --- |
+| `baseUrl` | `http://127.0.0.1:1933` | 远端 OpenViking 服务地址 |
+| `apiKey` | 空 | 远端 OpenViking API Key；服务端未开启认证时可不填 |
+| `agent_prefix` | 空 | OpenClaw agent ID 的可选前缀；如果拿不到 agent ID，插件使用 `main`。交互式配置只接受字母、数字、`_` 和 `-` |
+
+常见设置：
+
+```bash
+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
+openclaw config set plugins.entries.openviking.config.apiKey your-api-key
+openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix
+```
+
+## 升级
+
+```bash
+openclaw plugins update openviking
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+确认 `configured` 和 `slotActive` 都是 `true`。
+
+## 卸载
+
+```bash
+openclaw plugins uninstall openviking
+openclaw config set plugins.slots.contextEngine legacy
+openclaw gateway restart
+```
+
+当前 OpenClaw 原生卸载不一定会把 `plugins.slots.contextEngine` 恢复为 `legacy`。显式执行 `config set` 可以避免 slot 继续指向已卸载插件。
+
+## 可选链路健康检查
+
+如果 status 已通过，还想验证 Gateway 到 OpenViking 的完整链路，可以在仓库 checkout 中运行：
+
+```bash
+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
+```
+
+该脚本会注入一次真实对话，并在 OpenViking 侧验证会话捕获、提交、归档和记忆提取。详见 [health_check_tools/HEALTHCHECK-ZH.md](./health_check_tools/HEALTHCHECK-ZH.md)。
+
+## 备用路径：ov-install
+
+`ov-install` 是备用路径，不是主安装方式。仅当 `openclaw plugins install @openviking/openclaw-plugin` 无法访问 ClawHub、被限流，或者你明确需要从 Git 分支/源码 ref 安装测试时使用。
+
+先尝试 OpenClaw 插件管理器。如果该路径不可用，再执行：
+
+```bash
+npm install -g openclaw-openviking-setup-helper
+ov-install
+```
+
+常用备用/源码参数：
+
+| 参数 | 含义 |
+| --- | --- |
+| `--workdir PATH` | 指定 OpenClaw state 目录 |
+| `--version REF` | 指定 Git ref、tag、branch 或发布版本 |
+| `--current-version` | 查看 helper 记录的当前版本 |
+| `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
+| `--api-key KEY` | OpenViking API key |
+| `--agent-prefix PREFIX` | Agent 路由前缀 |
+| `--update` | 更新 helper 管理的安装 |
+
+面向用户的安装，请先使用 `openclaw plugins install @openviking/openclaw-plugin`。只有作为备用路径时才选择 `ov-install`。
+
+## 从 ov-install 迁移到 openclaw plugin install
+
+如果之前通过 `ov-install` 安装了 OpenViking，切换到推荐的 `openclaw plugins install` 安装方式前需要清理。
+
+### 同一插件 ID（openviking，版本 >= 0.3.x）
+
+ov-install 的 context-engine 部署会将文件写入 `~/.openclaw/extensions/openviking/`。通过 npm 安装后，OpenClaw 可能仍从旧目录加载。清理步骤：
+
+```bash
+# 删除 ov-install 部署的文件
+rm -rf ~/.openclaw/extensions/openviking/
+
+# 通过 OpenClaw 插件管理器安装
+openclaw plugins install @openviking/openclaw-plugin
+
+# 重新配置（openclaw.json 中的已有配置会保留）
+openclaw openviking setup --reconfigure
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+已有的配置字段（`baseUrl`、`apiKey`、`agentId` 等）会保留。新版本在运行时兼容读取旧字段名，无需手动修改配置。
+
+### 旧插件 ID（memory-openviking，版本 < 0.3.x）
+
+旧版 memory 插件使用了不同的插件 ID 和 slot：
+
+```bash
+# 卸载旧插件
+openclaw plugins uninstall memory-openviking 2>/dev/null || true
+
+# 清理旧 slot 和文件
+openclaw config set plugins.slots.memory none
+rm -rf ~/.openclaw/extensions/memory-openviking/
+
+# 安装新插件
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+或使用清理脚本：
+
+```bash
+bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
+```
+
+另见：[INSTALL.md](./INSTALL.md) 和 [INSTALL-AGENT.md](./INSTALL-AGENT.md)。