examples/openclaw-plugin/INSTALL-ZH.md
OpenViking 通过 @openviking/openclaw-plugin 插件为 OpenClaw 提供长期记忆、知识库检索、语义搜索和 RAG 上下文能力。
这份文档同时面向用户和自动化 agent：用户可以按步骤执行，agent 可以按命令和 JSON 结果判断下一步。
@openviking/openclaw-plugin 是 OpenClaw 插件。
不要用下面这个命令安装本插件：
clawhub install openviking
这个命令安装的是名为 openviking 的 AgentSkill，不是 OpenClaw 插件。
安装插件应使用：
openclaw plugins install clawhub:@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 clawhub:@openviking/openclaw-plugin 会安装已经发布并包含 dist/*.js 的插件包，普通用户不需要本地编译。ov-install 是备用/源码安装路径。当 ClawHub 或 OpenClaw 插件管理器路径不可用、被限流，或者明确需要测试源码 ref 时才使用。目标 OpenClaw >= 2026.5.3 时，它会在安装过程中编译插件。快速检查：
node -v
openclaw --version
如果你使用的是火山控制台创建的 OpenViking Service 库，不需要启动本地 openviking-server。从控制台复制 OpenViking Service 的 server url、API Key，并按需配置 peer 标识：
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup \
--base-url "https://api.vikingdb.cn-beijing.volces.com/openviking" \
--api-key "<your-openviking-service-api-key>" \
--json
openclaw gateway restart
openclaw openviking status --json
这条命令会完成：
openclaw openviking setup --base-url ... --api-key ... 写入插件配置。openclaw gateway。openclaw openviking status --json 和 openclaw config get plugins.slots.contextEngine 验证。如果需要把 OpenClaw assistant 说话人写成独立 peer_id，并让数据面 recall/search 使用对应 actor peer 视图，可以额外传：
openclaw openviking setup \
--base-url "https://api.vikingdb.cn-beijing.volces.com/openviking" \
--api-key "<your-openviking-service-api-key>" \
--peer-role assistant \
--peer-prefix "openclaw-prod" \
--json
如果使用 root key 或可信服务身份，补充租户信息：
openclaw openviking setup \
--base-url "https://api.vikingdb.cn-beijing.volces.com/openviking" \
--api-key "<root-key>" \
--account-id "<account-id>" \
--user-id "<user-id>" \
--json
本地源码验证：
npm install
npm run typecheck
npm test
npm run build
接入后，在火山 OpenViking Service 控制台检查：
Session 下出现原始会话。/compact 或等待 commit 后，User/memories 出现长期记忆。peer_role=assistant，数据面 recall/search 会携带对应 X-OpenViking-Actor-Peer，session message 仍用 body peer_id 做消息归因。/add-resource 导入文档、URL 或目录后，Resources 下出现对应知识，并可做目录递归检索。Agent 可见的 add_resource 工具默认禁用，只有显式设置 enableAddResourceTool=true 后才暴露。如果 OpenViking 和 OpenClaw 在同一台机器上，最短流程是：
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 使用插件期间，这个服务进程需要一直运行。
后台启动可以用：
mkdir -p ~/.openviking/data/log
nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &
如果 OpenViking 跑在另一台机器上，需要监听可访问的地址和端口，例如：
openviking-server --host 0.0.0.0 --port 1933
然后把 OpenClaw 插件的 baseUrl 配成对应地址，例如 http://your-server:1933。
安装或重启插件前，先确认服务能访问：
curl http://127.0.0.1:1933/health
普通用户、正式环境和 agent 自动安装都优先使用这条路径。
openclaw plugins install clawhub:@openviking/openclaw-plugin
如果你的 OpenClaw 环境需要显式 registry 前缀，使用：
openclaw plugins install clawhub:@openviking/openclaw-plugin
用户交互式配置：
openclaw openviking setup
Agent 非交互配置：
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
示例：
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 服务暂时不可达，但你仍希望先保存配置：
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json
如果使用 root API key，可能还需要租户上下文：
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 默认不会替换。确认要替换时再使用：
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
如需给默认 assistant peer 路由增加前缀，可以额外传：
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
openclaw gateway restart
如果你的 OpenClaw 版本使用不同的重启命令，请使用对应的 gateway 重启方式。
openclaw openviking status --json
期望结果：
| JSON 字段 | 期望值 |
|---|---|
configured | true |
slotActive | true |
health.ok | 服务可达时应为 true |
也可以直接查看 OpenClaw 配置：
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine
plugins.slots.contextEngine 应输出 openviking。
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 |
插件配置位于：
plugins.entries.openviking.config
核心字段：
| 字段 | 默认值 | 说明 |
|---|---|---|
mode | remote | 兼容旧配置的字段。当前只支持 remote。 |
baseUrl | http://127.0.0.1:1933 | OpenViking HTTP 地址 |
apiKey | 空 | OpenViking API key |
peer_role | assistant | Peer 身份模式：none、assistant 或 person。Session message 使用 body peer_id；数据面 recall/search 使用 X-OpenViking-Actor-Peer。 |
peer_prefix | 空 | peer_role=assistant 时 assistant peer_id / actor peer 值的可选前缀。 |
accountId | 空 | 使用 root API key 时需要 |
userId | 空 | 使用 root API key 时需要 |
普通修改优先使用 setup：
openclaw openviking setup --reconfigure
查看当前配置：
openclaw config get plugins.entries.openviking.config
插件连接到已有的远端 OpenViking 服务。
| 参数 | 默认值 | 含义 |
|---|---|---|
baseUrl | http://127.0.0.1:1933 | 远端 OpenViking 服务地址 |
apiKey | 空 | 远端 OpenViking API Key；服务端未开启认证时可不填 |
peer_role | assistant | Peer 身份模式：none、assistant 或 person；session message 使用 body peer_id，数据面 recall/search 使用 X-OpenViking-Actor-Peer |
peer_prefix | 空 | peer_role=assistant 时 assistant peer_id / actor peer 值的可选前缀 |
常见设置：
openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
openclaw config set plugins.entries.openviking.config.apiKey your-api-key
openclaw config set plugins.entries.openviking.config.peer_role assistant
openclaw config set plugins.entries.openviking.config.peer_prefix your-prefix
openclaw plugins update openviking
openclaw gateway restart
openclaw openviking status --json
确认 configured 和 slotActive 都是 true。
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 中运行：
python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
该脚本会注入一次真实对话，并在 OpenViking 侧验证会话捕获、提交、归档和记忆提取。详见 health_check_tools/HEALTHCHECK-ZH.md。
ov-install 是备用路径，不是主安装方式。仅当 openclaw plugins install clawhub:@openviking/openclaw-plugin 无法访问 ClawHub、被限流，或者你明确需要从 Git 分支/源码 ref 安装测试时使用。
先尝试 OpenClaw 插件管理器。如果该路径不可用，再执行：
npm install -g openclaw-openviking-setup-helper
ov-install
常用备用/源码参数：
| 参数 | 含义 |
|---|---|
--workdir PATH | 指定 OpenClaw state 目录 |
--plugin-version=REF | 指定插件版本：npm 版本、npm dist-tag 或 Git ref |
--current-version | 查看 helper 记录的当前版本 |
--base-url URL | OpenViking 服务器地址（启用非交互模式） |
--api-key KEY | OpenViking API key |
--peer-role ROLE | Peer role：none、assistant 或 person |
--peer-prefix PREFIX | assistant peer_id / actor peer 值的前缀 |
--update | 更新 helper 管理的安装 |
面向用户的安装，请先使用 openclaw plugins install clawhub:@openviking/openclaw-plugin。只有作为备用路径时才选择 ov-install。
如果之前通过 ov-install 安装了 OpenViking，切换到推荐的 openclaw plugins install 安装方式前需要清理。
ov-install 的 context-engine 部署会将文件写入 ~/.openclaw/extensions/openviking/。通过 npm 安装后，OpenClaw 可能仍从旧目录加载。清理步骤：
# 删除 ov-install 部署的文件
rm -rf ~/.openclaw/extensions/openviking/
# 通过 OpenClaw 插件管理器安装
openclaw plugins install clawhub:@openviking/openclaw-plugin
# 重新配置（openclaw.json 中的已有配置会保留）
openclaw openviking setup --reconfigure
openclaw gateway restart
openclaw openviking status --json
已有的配置字段（baseUrl、apiKey、peer_role、peer_prefix 等）会保留。
旧版 memory 插件使用了不同的插件 ID 和 slot：
# 卸载旧插件
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 clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
openclaw gateway restart
openclaw openviking status --json
或使用清理脚本：
bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
另见：INSTALL.md 和 INSTALL-AGENT.md。