install-openviking-memory

安装 OpenViking Memory —— Agent 安装与参考技能

你即将帮助用户安装并配置 OpenClaw 的 OpenViking 记忆插件。 用户不知道如何使用终端。你将通过自然对话收集几个值，然后使用你的 shell 工具自行运行所有命令。

开始前请阅读整份文档。按顺序执行每一步。不要跳过任何步骤。

本技能分为两部分：

• 第 1 部分（STEP 0–10）：自然语言安装引导。 首次安装或重新配置时使用。
• 第 2 部分：参考。 工具、配置 schema、多租户、多实例、日常运维、卸载、错误恢复。按需阅读。

服务范围。 本技能不安装 OpenViking 服务本身。它假设服务已在本地 127.0.0.1:1933 或另一台机器上运行。如果用户没有服务，请参见 STEP 5 中的“服务未就绪”处理。

---

第 1 部分 —— 自然语言安装引导

STEP 0：检测语言

如果用户的第一条消息包含中文字符，则全程用中文回复。 否则用英文回复。 下面所有面向用户的消息都有 (CN)/(EN) 两个版本 —— 使用匹配的那一个。

不要向用户展示这一步。

---

STEP 1：检测操作系统（静默进行）

运行此命令并记住结果。不要向用户展示。

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

• 输出包含 Darwin → OS=mac
• 输出包含 Linux → OS=linux
• 输出为 WINDOWS 或命令失败 → OS=windows

---

STEP 2：检查前置条件（静默进行）

静默运行：

node -v
openclaw --version

如果缺少 node：

(CN) 你的系统没有安装 Node.js。OpenClaw 和 OpenViking 插件需要 Node.js >= 22。请先安装 Node.js，然后再回来找我。 (EN) Node.js is not installed. OpenClaw and the OpenViking plugin require Node.js >= 22. Please install Node.js first, then come back.

停止。不要继续。

如果缺少 openclaw：

(CN) 你的系统没有安装 OpenClaw。请先安装 OpenClaw（>= 2026.5.27），然后再回来找我。 (EN) OpenClaw is not installed. Please install OpenClaw (>= 2026.5.27) first, then come back.

停止。不要继续。

如果两者都存在，静默进入 STEP 3。

---

STEP 3：问候并询问 3 个值

发送这条消息：

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

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

1. OpenViking 服务地址 —— 例如 https://ov.example.com 或 http://192.168.1.100:1933，本机服务可以直接说"本机"
2. API Key —— 用来鉴权；服务没开认证可以说"没有"
3. 记忆归属（可选） —— 所有对话共用 user 记忆（默认），还是在 peers/<assistant_id> 或 peers/<sender_id> 下分开存放

先告诉我服务地址吧？

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

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

1. OpenViking server URL — e.g. https://ov.example.com or http://192.168.1.100:1933. For a local server, just say "local".
2. API Key — for auth. Say "none" if the server has no auth.
3. Memory scope (optional) — shared user memory (default), or peer memory under peers/<assistant_id> / peers/<sender_id>.

What's the server URL?

---

STEP 4：收集值

通过自然对话收集 3 个值。保持灵活：如果用户一次给出多个值，就全部解析。如果他们更正了某个值，接受新值。

4a. BASE_URL（必填）

• “local” / “本机” / “localhost” → 使用 http://127.0.0.1:1933。
• ov.example.com 不带协议 → 在前面加上 https://。
• 去除末尾的 /、/health 或 /api。
• 规范化后必须以 http:// 或 https:// 开头。
• 如果用户说不知道，请让他们向管理员确认，或查看服务是如何启动的。不要编造 URL。

4b. API_KEY（可选）

(CN) API Key 是什么？服务没开认证就直接说"没有"。 (EN) What's the API Key? Say "none" if the server has no auth.

• “no” / “none” / “没有” / “空” / 空 → API_KEY=""（稍后跳过该 flag）。
• 否则按原样存储。

4c. PEER_ROLE（可选）

(CN) 记忆要存在哪一层？默认共享在 viking://user/<user_id>/memories（none）。也可以按 OpenClaw 助手存到 .../peers/<assistant_id>/memories（assistant），或按发送者存到 .../peers/<sender_id>/memories（sender）。 (EN) Where should memory live? The default is shared viking://user/<user_id>/memories (none). You can instead use .../peers/<assistant_id>/memories (assistant) or .../peers/<sender_id>/memories (sender).

默认为 none。切勿静默选择其他值——这三个选项意味着不同的存储布局，且日后很难更改：

值	具体布局	选择它的场景
none（默认）	共享记忆位于 viking://user/<user_id>/memories/...；不使用具体的 peers/<peer_id>/memories 子树。	通用场景。该 OpenViking 用户的所有对话共享用户级记忆。
assistant	归属于助手的 peer 记忆位于 viking://user/<user_id>/peers/<assistant_id>/memories/...，以解析出的 OpenClaw Agent ID 为键（回退为 main；支持可选前缀）。	人类作为 OpenViking 用户：一个人使用多个助手，并希望其 peer 记忆相互隔离。例如：Alice 的 main 和 research 助手分别使用 .../peers/main/... 和 .../peers/research/...。
sender	归属于发送者的 peer 记忆位于 viking://user/<user_id>/peers/<sender_id>/memories/...，以 OpenClaw 提供的发送者身份为键。	Agent 作为 OpenViking 用户：一个 Agent 与多个人对话，并希望其 peer 记忆相互隔离。例如：support-agent 将 customer-42 和 customer-99 存储在不同的 peer 子树下。

person 是 sender 的旧版别名。可从现有配置或用户显式输入中接受它，但应将新的设置值规范化/写入为 sender。

OpenViking 会为每个用户初始化托管的 peers/ 容器。不要告诉用户 none 会移除该容器：它只是避免使用具体的 peer 记忆子树。使用 assistant 或 sender 时，actor-peer 召回包含共享用户记忆加上当前 peer 记忆；它会隐藏其他 peer 子树。更改此设置不会移动已有的记忆。

• 空 / "default" / "默认" / "共用" → 不设置（插件默认为 none）。
• 否则传入 --peer-role none|assistant|sender。将显式的旧版 person 视为 sender。任何其他值 → 重新询问。

4d. PEER_PREFIX（可选，仅当 PEER_ROLE=assistant 时）

(CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、_、-。 (EN) Want to set an peer prefix? Leave blank for the default. Letters, digits, _, - only.

• 仅当 PEER_ROLE=assistant 时才有意义；否则跳过该问题。
• 空 / "default" / "默认" → 不设置（插件默认为 ""）。
• 否则按 /^[A-Za-z0-9_-]+$/ 校验。如果无效，重新询问。

4e.（视情况而定）多租户 Root-Key 字段

仅当 STEP 7 检测到 root key（Root API key detected. Missing: --account-id, --user-id）时才询问这些字段。不要提前询问。

• ACCOUNT_ID
• USER_ID

有关这些字段的含义，请参阅 Reference: Multi-Tenant。

---

STEP 5：飞行前连通性检查（静默进行）

简要告知用户：

(CN) 我先测一下能不能连上服务…… (EN) Let me test the connection to your server...

运行：

如果 OS=windows:

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

如果 OS=mac 或 OS=linux:

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

将 BASE_URL 替换为实际值。

状态	含义	操作
200	服务可达，/health 无需认证	继续执行 STEP 6。
401 / 403	服务可达，但 /health 需要认证	继续执行 STEP 6——向导的密钥探测会解决这个问题。
000 / 超时 / 连接被拒绝	服务不可达	见下方的 服务未就绪处理。
其他任何情况	意外情况	向用户显示状态码，回到 STEP 4a。

服务未就绪的处理

本技能不安装也不运行 OpenViking 服务。如果用户的服务无法访问，请如实说明情况并提供两条路径：

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

1. 服务还没启动 —— 请联系你的 OpenViking 服务管理员把它起起来；如果是你自己负责，请参考 OpenViking 官方文档（https://github.com/volcengine/OpenViking）的 server 启动指引。
2. 地址不对 —— 你可以重新告诉我正确的地址。
3. 网络不通（防火墙 / VPN / 内网）—— 你确认一下网络。

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

(EN) ❌ Cannot reach BASE_URL. Likely cause:

1. Server isn't running — please ask your OpenViking admin to start it. If you own the server, follow the OpenViking official docs (https://github.com/volcengine/OpenViking) to start it. This skill does not install or run the server.
2. Wrong URL — give me the correct URL.
3. Network blocked (firewall / VPN / private network) — please verify connectivity.

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

如果用户修正了 URL → 返回 STEP 4a。 如果用户想要 --allow-offline → 记住 ALLOW_OFFLINE=true 并继续到 STEP 6。 如果用户放弃 / 无法修正 → 就此停止。不要在故障状态下继续。

---

STEP 6：安装插件

插件可以通过两种方式安装。始终先尝试路径 A。 只有当路径 A 因 ClawHub 不可用、被限流或身份验证阻止匿名安装而失败时，才将路径 B 作为备用方案。对于版本冲突、依赖错误或其他非注册表类失败，请停止并向用户展示错误，而不是默默切换路径。

路径 A — 首选：openclaw plugins install（使用 ClawHub）

告诉用户：

(CN) 现在开始装插件…… (EN) Installing the plugin now...

运行：

openclaw plugins install clawhub:@openviking/openclaw-plugin

仅当输出包含以下任一字符串时，才触发回退到路径 B：

• 429
• rate limit / rate-limited / Too Many Requests
• not logged in / please log in / please login / unauthorized / 401 / 403 与 clawhub 同时出现
• 在 clawhub 相关主机上出现 ETIMEDOUT / ECONNRESET
• 表明注册表拒绝了匿名客户端的通用消息

在回退之前，还应再尝试一次显式指定注册表前缀：

openclaw plugins install clawhub:@openviking/openclaw-plugin

如果安装成功，跳转到 STEP 7。

如果两次尝试都因上述符合回退条件的错误而失败，转到路径 B。如果失败属于版本冲突、缺少依赖、包校验错误或其他非注册表错误，请停止并向用户展示最后 30 行输出。

路径 B — 备用方案：ov-install（绕过 ClawHub）

告诉用户：

(CN) ClawHub 现在好像被限流、不可用，或者当前账号不能安装。我改用备用路径，通过 npm 下载并部署插件包。 (EN) ClawHub looks rate-limited, unavailable, or blocked for this account. I'll use the backup path and install the plugin package from npm.

使用 npx 运行安装器（无需全局安装）：

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

根据用户提供的内容构建参数列表：

• 始终传入 --base-url BASE_URL。
• 仅当 API_KEY 非空时传入 --api-key API_KEY。
• 仅当用户选择了 assistant 或 sender 时传入 --peer-role PEER_ROLE；对于默认值 none 则省略。先将旧版 person 规范化为 sender。
• 仅当用户提供了该值且 PEER_ROLE=assistant 时传入 --peer-prefix PEER_PREFIX。
• --account-id / --user-id 仅在 root-key 路径需要它们时传入。

ov-install 会一次性完成以下操作：

1. 从 npm 下载 @openviking/openclaw-plugin 包到临时暂存目录。
2. 将包复制到 OpenClaw 的 extensions/ 目录并安装插件依赖。
3. 在 openclaw.json 中注册插件（通过 openclaw plugins enable 或直接写入）。
4. 为用户运行 openclaw openviking setup --json --base-url … [--api-key …]。
5. 如果 setup 需要显式的 --allow-offline 或 --force-slot 同意，则返回非零退出码。

这意味着 STEP 7 实际上由 ov-install 完成。在 ov-install 以 0 退出后，直接跳到 STEP 9（网关重启）和 STEP 10（验证）。

如果 ov-install 以非零退出，捕获其输出的最后 30 行，展示给用户，然后停止。不要盲目重试。

---

STEP 7：配置（仅限路径 A — 路径 B 已为你完成）

以非交互方式运行 setup 向导。根据收集到的值构建参数：

openclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--peer-role PEER_ROLE] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot]

规则：

• 在 --json 下，--base-url BASE_URL 是必需的。没有它，向导会输出 --json requires --base-url for non-interactive mode。
• 仅当 API_KEY 非空时使用 --api-key。
• 仅当用户选择了 assistant 或 sender 时使用 --peer-role；对于默认值 none 则省略。先将旧版 person 规范化为 sender。
• 仅当用户提供了该值且 --peer-role assistant 生效时使用 --peer-prefix。助手对等前缀请使用 --peer-prefix；旧的 ID 风格 setup 参数已不再支持。
• --account-id / --user-id 仅在 STEP 7 root-key 检测（见下文）之后使用。
• 仅当用户在 STEP 5 中明确批准时使用 --allow-offline。
• 首次尝试绝不使用 --force-slot。仅在用户确认后添加（见下文 slot_blocked 处理）。

解析 JSON 输出

向导会输出一个 JSON 对象：

{
  "success": true | false,
  "action": "configured" | "existing" | "error" | "slot_blocked",
  "config": { "mode": "remote", "baseUrl": "...", "apiKey": "...", "peer_prefix": "...", "accountId": "...", "userId": "..." },
  "health": { "ok": true, "version": "...", "compatibility": "compatible" | "server_too_old" | "server_too_new" | "unknown" },
  "keyProbe": { "keyType": "user_key" | "root_key" | "no_key" | "unknown", "needsAccountId": false, "needsUserId": false, "detail": "..." },
  "slot": { "activated": true, "replaced": false, "previousOwner": "openviking" },
  "error": "..."
}

决策矩阵

条件	操作
success: true 且 action: "configured" 或 "existing"	完成。继续执行 STEP 9。
success: false 且 action: "slot_blocked"	槽位冲突 — 见下文。
success: false 且 error 包含 "Server unreachable"	STEP 5 到 STEP 7 之间连接中断。提供 --allow-offline；如果用户接受，则重试。否则返回 STEP 4a。
success: false 且 error 包含 "Root API key detected" 和 "Missing: --account-id, --user-id"	Root-key 路径 — 见下文。
success: false 且 error 包含 "Invalid API key" / 在认证失败详情后出现 keyProbe.keyType: "unknown"	API key 错误。返回 STEP 4b。
success: false 且任何其他 action: "error"	向用户展示 error，停止。绝不要假装成功。

槽位冲突（slot_blocked）

错误文本如下：

contextEngine slot is owned by "<other-plugin>". Config was saved but slot was NOT changed. Use --force-slot to replace.

不要默默地使用 --force-slot。询问用户：

(CN) 你的 OpenClaw 当前 contextEngine 槽被 <other-plugin> 占着。如果用 OpenViking 替换它，<other-plugin> 就不再生效。要替换吗？ (EN) Your contextEngine slot is currently owned by <other-plugin>. Activating OpenViking will disable it. Replace?

如果用户同意，就重试同一条 setup 命令，并在末尾加上 --force-slot。如果用户拒绝，就告诉他们配置已保存但槽位未改变，然后停止。

Root 密钥路径

错误文本如下：

Root API key detected. Missing: --account-id, --user-id. Provide both to enable multi-tenant scoping.

询问用户：

(CN) 你给的是 root 级 API Key，需要再补两个值才能用：账户 ID（accountId）和用户 ID（userId）。这两个一般是 OpenViking 服务管理员配的，不知道就问他们。 (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.

收集完成后，重试 setup 命令，并在末尾加上 --account-id 和 --user-id。

---

STEP 8: （保留 — 在 STEP 7 内完成或由 ov-install 完成）

setup 向导已经写入了 plugins.entries.openviking.config.*，并且（如果成功）设置了 plugins.slots.contextEngine = "openviking"。没有单独的 STEP 8 — 直接进入 STEP 9。

---

STEP 9: 重启 Gateway

openclaw gateway restart

如果失败，用以下命令再试一次：

openclaw gateway --force

如果两次都失败：

(CN) Gateway 没能自动重启。请你手动跑一下 openclaw gateway restart。重启完告诉我，我来验证。 (EN) Gateway didn't restart cleanly. Please run openclaw gateway restart manually, then tell me when it's done so I can verify.

在 STEP 10 之前等待约 3 秒。

---

STEP 10: 验证

openclaw openviking status --json

预期输出：

{
  "configured": true,
  "slotActive": true,
  "health": { "ok": true },
  "config": { "baseUrl": "...", "peer_prefix": "..." }
}

决策

• configured: true 且 slotActive: true 且 health.ok: true → 成功。 发送下面的成功消息。
• configured: true 但 slotActive: false → 如果你之前跳过了 --force-slot，现在就询问用户是否替换，并用 --force-slot 重试 STEP 7。否则，这是 gateway 重启的问题 — 回到 STEP 9。
• configured: true 但 health.ok: false → 服务变得不可达。告诉用户；服务器一恢复，配置就会开始工作。
• configured: false → setup 实际上没有持久化。向用户展示完整的 status JSON 并停止。

成功消息

(CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。

工作方式：

• 每一轮：你的对话会被自动追加到 OpenViking session 里；自动抽取依赖阈值 commit 或 /compact
• 明确要记住时：如果你说“记住/保存/存一下”某个长期事实，我会用 memory_store 立即提交到记忆管线
• /compact 时：待提交的 session 消息会在 OpenViking 服务端被抽取成长期记忆
• 后续会话：每次回复前我都会自动搜一下相关记忆并带进上下文

想验证一下吗？可以直接说“记住我的邮箱是 [email protected]”，让我通过 memory_store 立即提交；或者先聊几句包含可记忆事实的话，再调一下 /compact。之后开新对话问“我的邮箱是？”，应该就能召回了。

(EN) 🎉 All set! OpenViking long-term memory is connected.

How it works:

• Every turn: our messages are appended to an OpenViking session; automatic extraction depends on a threshold commit or /compact
• Explicit remember requests: if you ask me to remember/save/store a long-term fact, I can use memory_store to commit it immediately
• On /compact: pending session messages are extracted into long-term memories on the OpenViking server
• Future sessions: relevant memories are auto-retrieved and injected before my replies

Want to verify? Say "remember my email is [email protected]" so I can commit it via memory_store, or tell me a few memory-worthy facts and run /compact. Then start a new chat and ask "what's my email?" — it should recall.

---

Part 2 — Reference

工作原理

context-engine 流水线包含三个不同的阶段，外加一条显式写入路径——请将它们区分开，尤其是在向用户说明记忆何时会成为 OpenViking 服务上可长期检索的记忆时：

• 归档 / 捕获（context-engine afterTurn）：在一轮用户对话结束时，插件通过 POST /api/v1/sessions/.../messages 将用户/助手消息追加到 OpenViking 会话。这仅是会话捕获，除非 pending_tokens 超过 commitTokenThreshold；低于该阈值时，尚不会运行记忆提取。你会在服务上看到会话消息数量增长，但 viking://user/.../memories/ 下不会出现新文件。
• 记忆提取（阈值提交或 /compact）：记忆提取在会话提交后运行。提交可以在 afterTurn 超过 commitTokenThreshold 时异步触发，在用户调用 OpenClaw 的 /compact 命令时同步触发，或通过 memory_store 显式触发。服务端提取流水线会读取已归档的会话并写入新记忆。
  • captureMode: "semantic"（默认）：服务端提取流水线会筛选所有符合条件的文本。
  • captureMode: "keyword"：仅考虑匹配触发词（例如 "remember"、"preference"）的文本。
• 自动召回（context-engine assemble()）：在组装提示词上下文之前，插件会向 OpenViking 查询相关记忆并将其注入上下文。即使尚无已提取的记忆，召回也能正常工作——只是不会看到任何返回结果。

对测试的实际影响：如果你写下一个简短的事实，并立即尝试在未进行阈值提交、/compact 或 memory_store 的情况下召回它，插件可能只会将其作为最近的会话上下文检索到，而不是长期记忆。要确定性地验证跨会话的长期记忆，请运行 /compact 或对被测事实使用 memory_store。

显式长期记忆写入

自动捕获是尽力而为且依赖提交的。当用户明确要求记住、保存或存储重要的长期事实、偏好、项目或决策时，Agent 应调用 memory_store，而不是等待普通的自动捕获。

将 memory_store 作为集成侧处理持久记忆意图的可靠路径：

• 它将提供的文本写入 OpenViking 会话，并调用 commit(wait=true)。
• 它补充自动捕获，但不替代正常的会话捕获。
• 如果它提交了但提取到 0 条记忆，说明显式路径已履行其职责。应将其视为服务端提取/模型/配置问题，并检查 OpenViking 日志。

可用工具

以下是安装后 Agent 可以调用的插件工具。

memory_recall — 搜索记忆

参数	必填	描述
query	是	搜索查询文本
limit	否	最大结果数（默认为插件配置）
scoreThreshold	否	最低相关性分数 0–1（默认为插件配置）
targetUri	否	精确的搜索范围 URI。如果提供，则仅搜索该 URI。
resourceTypes	否	省略 targetUri 时使用的目标类型数组：resource、user、agent。默认为插件 recallTargetTypes。

示例：用户问"我说过我喜欢哪种编程语言？"

memory_store — 手动存储

参数	必填	描述
text	是	要存储的信息文本
role	否	会话角色（默认 user）
sessionId	否	现有 OpenViking 会话 ID

当用户明确要求记住/保存/存储长期事实、偏好、项目或决策时使用此工具。

示例：用户说"记住我的邮箱是 [email protected]"。

memory_forget — 删除记忆

参数	必填	描述
uri	否	精确的记忆 URI（直接删除）
query	否	搜索查询（查找后删除）
targetUri	否	搜索范围 URI
limit	否	搜索上限（默认值为 5）
scoreThreshold	否	最低相关性分数

示例：用户说“忘掉我的电话号码”。

ov_archive_search — 搜索已归档的原始消息

参数	必填	描述
query	是	单个关键词或简短短语。优先使用具体名称、日期、命令、路径或独特名词。
archiveId	否	可选的归档 ID，例如 archive_002。

当 [Session History Summary] 过于粗略时使用。得出细节不可用的结论前，至少尝试两个关键词变体。

ov_archive_expand — 展开归档

参数	必填	描述
archiveId	是	来自 [Archive Index] 的归档 ID，例如 archive_002。

add_resource — 导入资源

默认情况下，Agent 可见的 add_resource 工具处于禁用状态（enableAddResourceTool=false）。除非明确选择启用，否则请使用手动 /add-resource 导入资源。即使已启用，也绝不要在搜索、检索、读取 URI 或优化搜索结果时使用 add_resource；这些流程请使用 ov_search 和 ov_read。

参数	必填	描述
source	是	本地路径、OpenClaw 媒体附件路径、目录路径、公开 URL 或 Git URL。
to	否	viking://resources 下的精确目标 URI；不能与 parent 同时使用。
parent	否	viking://resources 下的父级 URI；不能与 to 同时使用。
reason	否	导入原因或备注。
instruction	否	用于语义提取的处理指令。
wait	否	等待处理完成。

Agent Skill 最佳实践：确认 frontmatter 包含精确的 name、以触发条件为导向的 description、实用的 tags、明确的范围边界和具体的执行步骤。不要在 skill 内容中包含机密信息。

ov_search — 搜索资源和技能

参数	必填	描述
query	是	搜索查询。
uri	否	可选的搜索 URI。默认搜索资源和 Agent 技能。
limit	否	每个搜索范围的最大结果数。默认值：10。

重要：ov_search 返回的 URI 是 OpenViking 虚拟 URI，不是本地文件路径。如果需要完整内容，请使用搜索或追踪结果返回的精确 viking://... URI 调用 ov_read；不要使用文件系统读取工具。

ov_read — 读取 OpenViking 内容

参数	必填	描述
uri	是	ov_search 或召回追踪结果返回的精确 viking://... URI。不接受本地文件路径和 openviking://... 显示别名。

ov_recall_trace — 查询召回追踪

参数	必填	描述
turn	否	latest 或 all；默认值为 latest。
traceId	否	精确的追踪 ID。
sessionId / sessionKey / ovSessionId	否	会话筛选条件。
source	否	auto_recall、memory_recall、ov_search 或 ov_archive_search。
resourceTypes	否	目标类型筛选条件：resource、user、agent。
since / until	否	Unix 时间戳边界，单位为毫秒。
includeContent	否	按需读取所选／显示的 URI 内容预览。
limit	否	返回的最大追踪数。默认值：20。

需要 traceRecall=true；持久化查询还需要 traceRecallPersist=true。

外部化工具结果工具

当预览中包含 viking://user/{user_id}/sessions/<session_id>/tool-results/<tool_result_id> 引用时，请使用这些工具。

工具	参数
openviking_tool_result_list	tool_name?、limit?（默认值为 50）
openviking_tool_result_search	tool_output_ref、query、limit?（默认值为 20）、context_chars?（默认值为 300）
openviking_tool_result_read	tool_output_ref、offset?（默认值为 0）、limit?（默认值为 20000）

配置架构

这些是 openclaw.json 中 plugins.entries.openviking.config 下的键。设置向导 / ov-install 会设置前几个键，其余键可调整。

字段	默认值	说明
mode	"remote"（由插件强制设置）	在此技能中始终使用远程模式。请勿手动设置。
baseUrl	http://127.0.0.1:1933	OpenViking 服务 URL。
apiKey	—	API 密钥。如果服务未启用身份验证，则为可选项。
peer_role	none	记忆范围：none（共享的 viking://user/<user_id>/memories）、assistant（.../peers/<assistant_id>/memories）或 sender（.../peers/<sender_id>/memories）。旧版 person 会被视为 sender。会话消息使用正文中的 peer_id；数据平面召回 / 搜索使用 X-OpenViking-Actor-Peer。
peer_prefix	""	可选的前缀，用于助手的 peer_id / actor peer 值。仅在 peer_role=assistant 时使用。可使用字母 / 数字 / _ / -。
accountId	—	当 apiKey 是根密钥时为必填项。
userId	—	当 apiKey 是根密钥时为必填项。
targetUri	viking://~/memories	默认搜索范围 URI。
timeoutMs	（插件默认值）	OpenViking 调用的 HTTP 超时时间。
autoCapture	true	在 afterTurn 时自动将轮次消息追加到 OpenViking 会话；仅在达到阈值并提交、执行 /compact 或显式调用 memory_store 后才会运行提取。
captureMode	"semantic"	服务端提取管道使用的筛选模式：semantic 或 keyword。
captureMaxLength	24000	每轮归档文本的最大长度。
autoRecall	true	在回复前自动召回并注入记忆。
recallTargetTypes	user,agent	未指定 targetUri 时的默认目标类型。允许的值：resource、user、agent。
recallResources	false	兼容性快捷选项；当未设置 recallTargetTypes 时，会将 resource 添加到默认召回目标中。
recallLimit	6	每次召回最多注入的记忆数。
recallScoreThreshold	0.15	注入记忆的最低相关性分数。
recallMaxInjectedChars	4000	注入字符数上限。无法完整放入的记忆会被跳过，而不会截断。
recallPreferAbstract	（插件默认值）	优先使用抽象记忆，而非原始记忆。
recallTokenBudget	已弃用	recallMaxInjectedChars 的兼容别名。
commitTokenThresholdRatio	0.5	异步提交阈值，占模型上下文窗口的比例（0-1）（例如，0.5 = 50%）；0 表示每轮都提交。
commitKeepRecentCount	10	afterTurn 提交后保留为实时消息的最近消息数。Compact 始终使用 0。
bypassSessionPatterns	—	要跳过捕获的会话 Glob 模式。
ingestReplyAssist	（插件默认值）	回复辅助摄取开关。
emitStandardDiagnostics	false	输出结构化的 openviking: diag {...} 行。
logFindRequests	false	记录 find / 会话写入的路由日志。也可通过 OPENVIKING_LOG_ROUTING=1 或 OPENVIKING_DEBUG=1 启用。
traceRecall	false	在内存中记录召回跟踪信息。
traceRecallPersist	false	将召回跟踪信息持久化到 JSONL 文件。
traceRecallDir	~/.openclaw/openviking/recall-traces	召回跟踪信息目录。

要更改某个值：

openclaw config set plugins.entries.openviking.config.<field> <value>
openclaw gateway restart

多租户（根 API 密钥）

某些 OpenViking 部署会在多个租户间共用一个根 API 密钥。这种情况下，插件需要同时提供 accountId 和 userId，才能正确限定记忆的作用范围。设置向导会自动检测到这一点，并返回：

Root API key detected. Missing: --account-id, --user-id

出现这种情况时：

1. 向用户索取这两个值（由 OpenViking 管理员提供）。
2. 使用这两个标志重试 STEP 7：

openclaw openviking setup --base-url BASE_URL --api-key API_KEY --account-id ACCOUNT_ID --user-id USER_ID --json

用户密钥（按租户单独签发）不需要这些标志。

多实例（--workdir / OPENCLAW_STATE_DIR）

如果用户运行多个 OpenClaw 实例（例如并行测试多个 Agent），每个实例都有自己的状态目录。

若要指定非默认实例：

npx -y openclaw-openviking-setup-helper@latest --workdir ~/.openclaw-second --base-url ... --api-key ...

当状态目录不是默认目录时，ov-install 会写入一个辅助环境文件：

• Unix：~/.openclaw/openviking.env，其中包含 export OPENCLAW_STATE_DIR='...'
• Windows：~/.openclaw/openviking.env.bat 和 .ps1，用于设置同一个变量

运行 openclaw 命令前，先加载该文件，使命令使用正确的状态目录：

Unix：

source ~/.openclaw/openviking.env
openclaw status

Windows（PowerShell）：

. "$HOME/.openclaw/openviking.env.ps1"
openclaw status

或者在每次调用 openclaw 时直接传入 --workdir（注意：并非所有 openclaw 子命令都能一致地识别 --workdir——如有疑问，建议优先使用环境变量）。

日常操作

# Start or restart OpenClaw gateway after config changes
openclaw gateway restart

# Check overall status
openclaw status
openclaw openviking status --json

# Read current OpenViking slot
openclaw config get plugins.slots.contextEngine

# Disable OpenViking memory (keep config, deactivate slot)
openclaw config set plugins.slots.contextEngine legacy
openclaw gateway restart

# Re-enable
openclaw config set plugins.slots.contextEngine openviking
openclaw gateway restart

卸载

首选：通过 OpenClaw 插件管理器卸载

openclaw plugins uninstall openviking
openclaw config set plugins.slots.contextEngine legacy
openclaw gateway restart

如果是通过备用方式 ov-install 安装的

npx -y openclaw-openviking-setup-helper@latest --uninstall

此操作会：

1. 停止 OpenClaw 网关。
2. 备份 openclaw.json。
3. 从 openclaw.json 中移除所有 OpenViking 插件配置（plugins.entries.openviking、plugins.allow、plugins.installs.openviking、plugins.slots.contextEngine）。
4. 将插件目录移动到 disabled-extensions/ 作为备份。
5. 移除辅助环境文件（openviking.env、.bat、.ps1）。

添加 --base-url dummy 可启用完全非交互模式（跳过确认提示）。

手动卸载

openclaw gateway stop
openclaw config set plugins.slots.contextEngine legacy
# Then edit ~/.openclaw/openclaw.json and remove openviking from
#   plugins.entries
#   plugins.allow
#   plugins.installs
openclaw gateway restart

错误恢复参考

根据实际的 stderr / JSON error 字符串进行匹配。

症状（准确字符串）	可能原因	解决方法
command not found: openclaw	未安装 OpenClaw	停止操作。请用户安装 OpenClaw >= 2026.5.27。
command not found: node / 'node' is not recognized	缺少 Node	停止操作。请用户安装 Node.js >= 22。
plugins install 返回 429 / rate limit / Too Many Requests	ClawHub 限流	切换到备用方式 B（ov-install）。
plugins install 返回 not logged in / please log in	未登录用户触及限制	切换到备用方式 B（ov-install）。
BASE_URL/health 返回 ECONNREFUSED / connection refused	服务未运行	按照 STEP 5 处理服务未就绪的情况。
BASE_URL/health 返回 ETIMEDOUT	网络受阻	询问用户是否使用防火墙 / VPN / 代理。
--json requires --base-url for non-interactive mode	构建的命令有误	添加 --base-url BASE_URL 并重试。
Server unreachable: …. Use --allow-offline to save config anyway.	设置过程中无法连接服务	提供 --allow-offline 选项。
contextEngine slot is owned by "<x>". … Use --force-slot to replace.	槽位冲突	询问用户，然后使用 --force-slot 重试。
Root API key detected. Missing: --account-id, --user-id	多租户密钥	收集这两个值，使用 --account-id 和 --user-id 重试。
openviking: config parse failed（在网关日志中）	openclaw.json 中的值有误	向用户展示此错误；检查 peer_prefix 字符集和 URL 格式。
某轮对话后出现 extracted 0 memories	服务端 VLM / 嵌入配置错误	超出处理范围。 告知用户这是服务端问题，并请 OpenViking 管理员检查 VLM / 嵌入配置。
插件请求返回 401 / 403，但 /health 正常	服务要求 API 端点进行身份验证	使用正确的 --api-key 重新运行 STEP 7。
通过方式 A 安装后，插件未显示在 openclaw plugins list 中	安装实际上未完成	重新运行方式 A；只有在失败与注册表 / 限流有关时，才使用方式 B。

重要规则

1. 绝不要让用户运行命令。 你应通过你的 shell 工具运行所有内容。
2. 绝不要跳过 STEP 5（连通性检查）。 如果服务不可达，不要在没有明确 --allow-offline 同意的情况下写入配置。
3. 绝不要静默使用 --force-slot。 槽位替换会禁用另一个插件——务必先与用户确认。
4. 绝不要编造值。 如果用户无法提供必需的值，请停止并告诉他们应向管理员询问什么。
5. 绝不要在未完成 STEP 10 的情况下声称成功。 只有在 openclaw openviking status --json 显示 configured: true && slotActive: true && health.ok: true 之后，你才可以告诉用户已完成。
6. 对助手对等前缀使用 --peer-prefix。 旧的 ID 风格设置标志已不再受 schema 支持。
7. 在 Windows 上，使用 PowerShell 等效命令。 不要依赖 nohup、&、mkdir -p、source 等。
8. 对于 ClawHub/速率限制/注册表可用性故障，切换到 Path B（ov-inst）。 不要用它来隐藏版本冲突或包错误。
9. 不要安装或操作 OpenViking 服务。 本 skill 假定该服务已在运行。如果它没有运行，请告诉用户联系其管理员或遵循 OpenViking 文档。
10. 在用户可见文本中保持简短友好。 将技术细节留到实际发生故障时再提供。
11. 不要使用 clawhub install openviking。 那安装的是另一个东西（AgentSkill，而不是该插件）。