OpenViking OpenClaw 插件帮助文档

本文档面向插件使用者、集成方、排障同学和后续维护者，系统梳理 @openviking/openclaw-plugin 的实现原理、执行流程、核心功能、安装配置、构建测试、Debug、发布上线与验证方式，以及它与火山 OpenViking 的联动机制。

1. 一句话结论

@openviking/openclaw-plugin 是一个 OpenClaw context-engine 插件。它把 OpenClaw 的会话生命周期、上下文组装、记忆召回、会话归档、工具结果回读、资源/技能导入等能力，通过 HTTP API 接到远端 OpenViking 服务上，让 Agent 拥有长期记忆、工作记忆、历史压缩、语义检索和 RAG 能力。

它不负责启动本地 OpenViking Server，也不替代 OpenClaw Runtime；OpenClaw 仍负责 Agent 执行、prompt 编排和工具调用，OpenViking 负责上下文数据库、长期记忆、session/archive、resource/skill 检索与服务端抽取。

2. 插件解决的问题

3. 架构定位

3.1 插件在 OpenClaw 中的形态

插件清单声明了它是 context-engine 插件，并在启动时激活 hook/tool 能力：openclaw.plugin.json:2、openclaw.plugin.json:4、openclaw.plugin.json:6。

包元信息中，插件通过 OpenClaw 扩展入口加载 ./dist/index.js，并提供 setup CLI 入口 ./dist/commands/setup.js：package.json:57。

插件在运行时主要承担四个角色：

1. Context Engine：实现 assemble、afterTurn、compact，并声明自己拥有 compaction。
2. Hook 集成层：监听 session_start、session_end、before_reset 等事件。
3. Tool Provider：注册 memory、archive、resource、skill、tool-result 相关工具。
4. Runtime/Setup 管理层：提供 openclaw openviking setup/status，并在服务启动时做 health check。

3.2 核心文件职责

4. 执行流程总览

4.1 插件加载流程

1. OpenClaw 根据插件入口加载 index.ts 的默认导出。
2. register(api) 读取 api.pluginConfig，用 memoryOpenVikingConfigSchema.parse 解析配置；解析失败时只注册 setup CLI，提示用户运行 setup：index.ts:558、index.ts:576。
3. 创建 OpenVikingClient，注入 baseUrl、apiKey、超时与租户配置：index.ts:625。
4. 注册工具、slash command、hook、context engine 与 service：index.ts:872、index.ts:962、index.ts:1913、index.ts:1945、index.ts:1970。
5. Service 启动时调用 /health 做一次非阻塞 health check，并输出初始化日志：index.ts:1970。

4.2 会话 ID 与 peer 路由流程

OpenClaw 的 sessionId/sessionKey 不能总是直接作为 OpenViking 存储路径。插件用 openClawSessionToOvStorageId 生成安全稳定的 OpenViking session id：

• 如果 sessionId 是 UUID，直接小写复用。
• 如果有 sessionKey，用 SHA-256 生成稳定 id。
• 如果非 UUID 的 sessionId 包含 Windows 路径不安全字符，也用 SHA-256。
• 否则使用原 sessionId。

实现位置：context-engine.ts:342。

插件仍会从 OpenClaw runtime/session context 解析一个稳定的 agent id，用于 peer_role=assistant 时的 assistant peer_id 和数据面 actor peer 视图。peer_prefix 非空时，assistant peer id 会变成 <peer_prefix>_<agentId>；当前实现不发送 X-OpenViking-Agent header，也不再使用废弃的 viking://agent/... 命名空间。

4.3 assemble：回复前组装上下文

OpenClaw 会在 context engine 上调用 assemble。当前实现把 assemble 分成两类：

判断逻辑在 context-engine.ts:1097。

主 assemble 流程：

1. 解析 session 身份，计算 token budget，记录诊断日志。
2. 调用 GET /api/v1/sessions/{sessionId}/context?token_budget=...：context-engine.ts:1193、client.ts:873。
3. 如果 OpenViking 没有可用 archive/session 数据，直接 passthrough，不影响主链路。
4. 将 latest_archive_overview 转成 [Session History Summary]。
5. 将 OpenViking parts 消息转换为 OpenClaw AgentMessage，包括 tool part → toolCall + toolResult。
6. 修复 transcript：合并连续 user/assistant、修复 toolCall/toolResult 配对，必要时插入占位 user 以满足 provider 交替约束。
7. 返回组装后的 messages 和可选 systemPromptAddition。

transformContext auto recall 流程：

1. 从最新 user message 提取查询文本。
2. 清洗 metadata、心跳、已注入记忆块等噪音。
3. 快速 precheck，OpenViking 不可用时跳过召回，避免拖慢模型请求。
4. 按 recallTargetTypes 生成搜索计划；默认使用 context_type=memory 检索当前 user 的 memory 视图。配置了 peer_role 时，数据面请求会发送 X-OpenViking-Actor-Peer，由服务端把 peer 集合限制到当前 actor peer；显式设为 resource 时使用 context_type=resource；旧字段 recallResources=true 仅在未显式配置 recallTargetTypes 时把 resource 追加到默认集合。
5. 去重、阈值过滤、leaf 优先、偏好/时间问题 boost、词面重合度 boost。
6. 在 recallMaxInjectedChars 限制内构建完整记忆行，不截断单条记忆。
7. 用 <relevant-memories> 块 prepend 到最新 user message。

自动召回实现入口：context-engine.ts:1125、auto-recall.ts:159。

4.4 afterTurn：每轮对话后自动捕获

afterTurn 负责把本轮新增消息写入 OpenViking session，并在 pending_tokens 超过阈值时异步 commit。

流程：

1. 若 autoCapture=false、heartbeat 或 session 被 bypass，直接跳过。
2. 根据 prePromptMessageCount 只提取本轮新增消息，不重写全量 transcript。
3. extractNewTurnMessages 将 user/assistant 文本和 toolResult 转成 OpenViking parts：text-utils.ts:342。
4. 清理 <relevant-memories>、metadata、时间戳、心跳等噪音。
5. 逐条调用 POST /api/v1/sessions/{sessionId}/messages：context-engine.ts:1378、client.ts:703。
6. 调 GET /api/v1/sessions/{sessionId} 读取 pending_tokens：context-engine.ts:1389、client.ts:770。
7. 若 pending_tokens < commitTokenThreshold，本轮结束。
8. 否则调用 commitSession(wait=false, keepRecentCount=cfg.commitKeepRecentCount)；服务端 Phase 2 记忆抽取异步继续执行：context-engine.ts:1403。
9. 开启 logFindRequests 时，插件轮询 task 结果并打印 Phase 2 抽取状态：context-engine.ts:1424。

4.5 compact：主动压缩边界

compact 是同步边界，用于 /compact 或 OpenClaw 触发压缩时阻塞等待服务端 commit 完成。

流程：

1. 解析 OpenViking session id。
2. 调用 commitSession(wait=true, keepRecentCount=0)，要求服务端归档所有当前消息：context-engine.ts:1500。
3. 如果 Phase 2 failed/timeout，返回失败原因。
4. 如果没有生成 archive，返回 commit_no_archive。
5. 如果归档成功，再回读 getSessionContext，获取最新 latest_archive_overview 作为 summary：context-engine.ts:1605。
6. 返回 tokensBefore/tokensAfter、latest archive id 和 summary。

4.6 before_reset：重置前保护性提交

插件监听 before_reset，在 reset 前尽量 commit 当前 OpenViking session，避免对话被重置时未归档内容丢失：index.ts:1919。

5. 核心功能

5.1 长期记忆自动召回

默认开启 autoRecall。模型回复前，插件会根据当前用户问题搜索长期记忆，并注入相关上下文。

关键配置：

配置默认值在 config.ts:58。

5.2 会话归档与 Working Memory

插件把 OpenClaw turn 持续写入 OpenViking session，由服务端维护 pending_tokens 与 archive。超过阈值时：

• afterTurn 路径：wait=false，异步 Phase 2，默认保留最近 10 条消息。
• compact 路径：wait=true，同步等待 Phase 2，keepRecentCount=0，形成明确压缩边界。

commitKeepRecentCount 默认 10，commitTokenThreshold 默认 20000：config.ts:68。

5.3 显式记忆工具

插件注册了三个长期记忆工具：

注册位置：index.ts:1022、index.ts:1190、index.ts:1309。

5.4 Archive 回查工具

注册位置：index.ts:1421、index.ts:1522。

5.5 Resource / Skill 导入与检索

本地文件/目录不会把原路径直接传给服务端，而是先 temp upload；目录会用纯 JS zip 打包后上传：client.ts:609、client.ts:552。

5.6 外置 Tool Result 回读

当 OpenViking 服务端将大工具结果外置为 viking://user/sessions/.../tool-results/... 时，插件提供：

注册位置：index.ts:1601、index.ts:1698、index.ts:1802。插件会拒绝跨 session 读取 tool result，避免越权或串会话：index.ts:1639、index.ts:1735。

6. 与火山 OpenViking 的联动方式

6.1 HTTP Client 与认证头

插件是 OpenViking 的纯 HTTP Client。所有请求统一走 OpenVikingClient.request：client.ts:313。

请求头逻辑：

peer_role=assistant/person 时，session message 仍通过请求 body 的 peer_id 做消息归因；recall/search/read/import/delete 等数据面请求通过 X-OpenViking-Actor-Peer 进入当前 actor peer 视图。当前实现不发送 X-OpenViking-Agent header。

6.2 OpenViking 官方 API 完整清单与插件映射

官方 HTTP API 统一前缀为 /api/v1/，成功响应一般为 { "status": "ok", "result": ..., "time": ... }，错误响应为 { "status": "error", "error": { "code", "message" }, "time" }。插件只做 HTTP Client，不嵌入 OpenViking SDK；统一封装点是 OpenVikingClient.request：client.ts:313。

6.2.1 System / Observer

6.2.2 Retrieval / Search

6.2.3 Filesystem / Content

6.2.4 Resources / Skills Import

6.2.5 Sessions / Working Memory

6.2.6 Skills Runtime

6.2.7 Admin / Authentication

认证方式：OpenViking HTTP 支持 X-API-Key: <key> 和 Authorization: Bearer <key>；插件固定使用 X-API-Key。如果服务端启用了多租户且当前 key 需要显式租户上下文，插件还会附加 X-OpenViking-Account、X-OpenViking-User。

6.3 URI 与命名空间

插件使用 OpenViking 的 filesystem paradigm，常见 URI：

viking://agent/... 已由 OpenViking 废弃，当前插件不再把它作为检索目标。session 消息的说话人归因由 peer_role / peer_prefix 解析出的 peer_id 控制；recall/search/read/import/delete 的 peer 视图由 X-OpenViking-Actor-Peer 控制。

7. 安装与使用

7.0 五分钟快速路径

如果你只想先把插件跑起来，按这 4 步执行：

# 1. 确认 OpenViking Server 已启动
curl http://127.0.0.1:1933/health

# 2. 安装插件
openclaw plugins install clawhub:@openviking/openclaw-plugin

# 3. 写入 OpenViking 连接配置并激活 contextEngine slot
openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key <OPENVIKING_API_KEY> --json

# 4. 重启并验证
openclaw gateway restart
openclaw openviking status --json
openclaw config get plugins.slots.contextEngine

期望结果：status 中 configured=true、slotActive=true、health.ok=true，并且 plugins.slots.contextEngine 输出 openviking。

本仓库示例仅保留 ClawHub / 本地开发安装说明；TOS release 包安装、上传、下载和回滚流程不在 examples/openclaw-plugin 范围内。

7.1 前置要求

兼容性声明在 install-manifest.json:43。

7.2 启动 OpenViking Server

插件只连接远端 OpenViking，不启动服务端。先启动服务端：

pip install openviking --upgrade --force-reinstall
openviking-server init
openviking-server doctor
openviking-server --host 0.0.0.0 --port 1933

openviking-server init 会生成 OpenViking 服务端配置；openviking-server doctor 会检查模型 provider、embedding provider、workspace 权限等基础依赖；openviking-server 才是真正启动 HTTP API 的进程。OpenClaw 使用插件期间，这个服务进程需要一直运行。

验证服务：

curl http://127.0.0.1:1933/health

后台启动可以用：

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，而不是服务端本机视角的 127.0.0.1。

7.3 OpenViking 服务端配置文件

OpenViking 服务端配置与 OpenClaw 插件配置是两层配置，位置不同、作用也不同：

最小 ~/.openviking/ov.conf 示例：

{
  "storage": {
    "workspace": "/Users/bytedance/.openviking/data"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "$ARK_API_KEY",
      "model": "doubao-embedding-vision-250615",
      "dimension": 2048
    },
    "max_concurrent": 10
  },
  "vlm": {
    "provider": "volcengine",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "$ARK_API_KEY",
    "model": "doubao-seed-2-0-pro-260215",
    "max_concurrent": 20
  }
}

也可以使用 OpenAI / LiteLLM 等 provider，例如：

{
  "storage": {
    "workspace": "/Users/bytedance/.openviking/data"
  },
  "embedding": {
    "dense": {
      "provider": "openai",
      "api_base": "https://api.openai.com/v1",
      "api_key": "$OPENAI_API_KEY",
      "model": "text-embedding-3-large",
      "dimension": 1536
    }
  },
  "vlm": {
    "provider": "openai",
    "api_base": "https://api.openai.com/v1",
    "api_key": "$OPENAI_API_KEY",
    "model": "gpt-4o"
  }
}

提前设置方式：

mkdir -p ~/.openviking
$EDITOR ~/.openviking/ov.conf

# 不建议把真实 key 写进文档或命令历史；优先通过环境变量注入
export ARK_API_KEY=<your-ark-key>
# 或 OpenAI provider：export OPENAI_API_KEY=<your-openai-key>

openviking-server doctor
openviking-server --host 127.0.0.1 --port 1933

如果要使用自定义配置文件：

export OV_CONFIG=/path/to/ov.conf
openviking-server doctor
openviking-server --host 127.0.0.1 --port 1933

注意事项：

• ov.conf 是服务端模型与存储配置，决定服务端如何做 embedding、VLM 抽取、resource 解析和 session archive；插件不会读取或修改这个文件。
• api_key 字段建议写成 $ARK_API_KEY、$OPENAI_API_KEY 这类环境变量占位，并在启动服务前导出真实 key，避免密钥落盘或进入 Git。
• 切换 embedding 模型或 dimension 后，历史向量索引可能不兼容；本地测试环境可清理 workspace 后重建，生产环境需要按服务端迁移/重建索引方案处理。
• workspace 要放在服务端进程有读写权限且磁盘容量足够的位置，长期记忆、资源索引、归档和日志都会持续增长。

7.4 本机拉起单机版测试

本机单机版适合开发、调试和端到端验证。推荐最小链路如下：

# 1. 安装 OpenViking Python 包
python3 -m pip install openviking --upgrade --force-reinstall

# 2. 初始化服务端配置
openviking-server init

# 3. 导出模型 provider key，或提前写入自定义 ov.conf
export ARK_API_KEY=<your-ark-key>

# 4. 检查服务端配置和 provider 可用性
openviking-server doctor

# 5. 启动本地 HTTP 服务
openviking-server --host 127.0.0.1 --port 1933

另开一个终端验证：

curl http://127.0.0.1:1933/health

然后配置 OpenClaw 插件连接本机服务：

openclaw openviking setup \
  --base-url http://127.0.0.1:1933 \
  --api-key <OPENVIKING_API_KEY> \
  --json

openclaw gateway restart
openclaw openviking status --json

如果本机 OpenViking 服务没有开启 API key 校验，可按服务端实际策略传空 key 或测试 key；如果使用火山 OpenViking Service / root key / trusted server 流程，则按服务端要求补充 --account-id 和 --user-id。

单机版联调检查点：

1. curl /health 返回正常。
2. openclaw openviking status --json 中 configured=true、health.ok=true。
3. openclaw config get plugins.slots.contextEngine 输出 openviking。
4. 与 Agent 对话一轮后，服务端日志 ~/.openviking/data/log/openviking.log 或前台输出能看到 session/message/commit 相关请求。
5. 触发 /compact 或等待 pending_tokens 超过阈值后，在 OpenViking Console/TUI 或插件工具中能检索到 archive/memory。

7.5 安装插件

openclaw plugins install clawhub:@openviking/openclaw-plugin

不要使用 clawhub install openviking 安装本插件；那是另一个 AgentSkill，不是 OpenClaw 插件。

7.6 配置插件

交互式：

openclaw openviking setup

非交互式：

openclaw openviking setup \
  --base-url http://127.0.0.1:1933 \
  --api-key sk-xxx \
  --json

如果使用 root key：

openclaw openviking setup \
  --base-url http://127.0.0.1:1933 \
  --api-key <ROOT_API_KEY> \
  --account-id <ACCOUNT_ID> \
  --user-id <USER_ID> \
  --json

如果已有别的 context engine 占用 slot，确认要替换时才加：

openclaw openviking setup --base-url <URL> --api-key <KEY> --force-slot --json

7.7 重启与验证

openclaw gateway restart
openclaw openviking status --json
openclaw config get plugins.slots.contextEngine

期望：

• configured=true
• slotActive=true
• health.ok=true
• plugins.slots.contextEngine 输出 openviking

7.8 本地安装脚本边界

examples/openclaw-plugin 不包含 TOS release 安装脚本。需要验证本地包时，优先使用 ClawHub 安装或在插件目录内运行 npm run build 后用 OpenClaw 本地插件能力加载；TOS 下载、校验、灰度和回滚流程已从本示例中排除。

构建和安装时应确认运行时依赖 @sinclair/typebox 位于 dependencies，避免 OpenClaw 加载插件时报缺失依赖。

8. 常用命令与工具用法

8.1 插件命令

# 配置
openclaw openviking setup

# 非交互配置
openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json

# 状态检查
openclaw openviking status --json

# 查看配置
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine

8.2 Slash Commands

/add-resource ./README.md --to viking://resources/openviking-readme --wait
/add-resource https://example.com/spec.html --parent viking://resources/project-docs --wait
/add-skill ./skills/install-openviking-memory --wait
/ov-search "OpenViking install" --uri viking://resources/openviking-readme
/ov-search "memory install skill" --uri viking://user/skills

8.3 Agent 工具触发场景

9. 配置参数说明

环境变量解析逻辑在 config.ts:139、config.ts:147。

9.1 搜索 / 召回相关配置总表

如果你关注的是“插件里的搜索能力可以怎么从外部设定”，可以按下面这张表看。这里的“搜索”包括三类：

• 自动召回：回复前自动查长期记忆 / resources 并注入 <relevant-memories>
• 显式检索：memory_recall、ov_search、ov_archive_search
• 搜索诊断：打开 routing / find 日志，排查“为什么没搜到 / 搜到了但没注入”

9.2 哪些配置只能走配置文件，哪些可以直接走环境变量

9.2.1 可直接通过环境变量生效的搜索相关项

9.2.2 只能通过插件配置文件设定的搜索行为项

这些项当前没有独立环境变量，需要写到 ~/.openclaw/openclaw.json 里的 plugins.entries.openviking.config：

• targetUri
• timeoutMs
• autoRecall
• recallTargetTypes（可通过安装脚本 --recall-target-types 或 setup CLI 参数写入配置，但运行时不是直接读环境变量）
• recallLimit
• recallScoreThreshold
• recallMaxInjectedChars
• recallPreferAbstract
• recallTokenBudget（废弃兼容）
• recallMaxContentChars（废弃兼容）
• captureMode
• captureMaxLength
• bypassSessionPatterns

9.3 推荐配置示例

9.3.1 Resource-only 召回配置

当前默认召回目标是 memory 类型视图：["user","agent"] 作为兼容配置会合并为一次 context_type=memory 检索；配置了 actor peer 时由 X-OpenViking-Actor-Peer 限制当前 peer 视图。如果你的场景主要是“导入文档 / 知识库问答”，并希望默认召回只查 resources，需要显式配置 recallTargetTypes：

openclaw config set plugins.entries.openviking.config.recallTargetTypes '["resource"]'
openclaw gateway restart

安装后也可以通过 openclaw config set 显式写入；本示例不包含 TOS 安装脚本参数。

注意：recallResources=true 是旧兼容加法开关，只会在未显式配置 recallTargetTypes 时把 resource 追加到默认 memory 视图，默认不会改成 resource-only。

9.3.2 仅通过环境变量快速打开“额外可搜 resources 的自动召回”

export OPENVIKING_BASE_URL="http://127.0.0.1:1933"
export OPENVIKING_API_KEY="<YOUR_KEY>"
export OPENVIKING_RECALL_RESOURCES=1

适合：你已经有稳定的 openclaw.json，只想临时把 viking://resources 追加到自动召回和默认 memory_recall，同时保留默认 user + agent 记忆召回。

9.3.3 通过插件配置文件精细控制召回和 trace

{
  "plugins": {
    "entries": {
      "openviking": {
        "config": {
          "baseUrl": "${OPENVIKING_BASE_URL}",
          "apiKey": "${OPENVIKING_API_KEY}",
          "targetUri": "viking://user/memories",
          "autoRecall": true,
          "recallTargetTypes": ["user", "agent", "resource"],
          "recallLimit": 8,
          "recallScoreThreshold": 0.2,
          "recallMaxInjectedChars": 6000,
          "recallPreferAbstract": true,
          "logFindRequests": true,
          "traceRecall": true,
          "traceRecallPersist": true
        }
      }
    }
  }
}

这里有两个关键点：

• baseUrl / apiKey 支持在配置文件里写 ${ENV} 占位，加载时会做环境变量替换：config.ts:82
• 但 recallTargetTypes / recallLimit / recallScoreThreshold / autoRecall / traceRecall 这类行为项不会从环境变量自动读取，仍以配置文件为准。
• 开启 recall trace 必须显式设置 traceRecall=true；只设置 recallTargetTypes 或 recallResources 不会启用 trace。

9.4 外部配置生效顺序

搜索相关配置的实际生效顺序可以概括为：

1. 显式工具参数优先：例如 memory_recall(limit=3, scoreThreshold=0.4, targetUri=...)、/ov-search --limit 20 --uri ... 会优先覆盖默认配置：index.ts:1046、index.ts:1050、index.ts:1054、index.ts:824、index.ts:408
2. 插件配置文件其次：plugins.entries.openviking.config.*
3. 环境变量补默认值：只对少数支持 env 的项生效，如 OPENVIKING_BASE_URL、OPENVIKING_API_KEY、OPENVIKING_RECALL_RESOURCES：config.ts:139、config.ts:202、config.ts:284
4. 代码默认值兜底：例如 recallLimit=6、recallScoreThreshold=0.15、recallMaxInjectedChars=4000：config.ts:63、config.ts:64、config.ts:67

9.5 搜索相关配置的排查建议

10. Debug 与排障

10.1 快速状态检查

openclaw openviking status --json
openclaw plugins list
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine
curl http://127.0.0.1:1933/health

10.2 打开插件侧路由日志

配置方式：

openclaw config set plugins.entries.openviking.config.logFindRequests true
openclaw gateway restart

或临时环境变量：

OPENVIKING_LOG_ROUTING=1 openclaw gateway restart

日志会打印 account/user header 是否设置、actor peer header、target_uri、query preview、session commit 等信息，但不会打印 apiKey。

10.3 打开标准诊断日志

openclaw config set plugins.entries.openviking.config.emitStandardDiagnostics true
openclaw gateway restart

然后在日志中搜索：

openviking: diag {"stage":"assemble_entry"...}
openviking: diag {"stage":"assemble_result"...}
openviking: diag {"stage":"afterTurn_entry"...}
openviking: diag {"stage":"afterTurn_commit"...}
openviking: diag {"stage":"compact_result"...}

10.4 对话时观测召回与文档命中

如果需要在与 OpenClaw 对话时确认“本轮到底从 OpenViking 召回了哪些数据、用了哪些文档、对应路径是什么”，推荐按以下顺序排查。

10.4.0 启用 recall trace

Recall trace 是独立的可观测能力，必须打开 traceRecall=true 才会记录；只设置 recallResources 或 recallTargetTypes 只会改变召回范围，不会自动启用 trace。

# 只保留当前 gateway 进程内的内存 trace
openclaw config set plugins.entries.openviking.config.traceRecall true

# 如需 gateway 重启后还能查历史 trace，再打开持久化
openclaw config set plugins.entries.openviking.config.traceRecallPersist true
openclaw config set plugins.entries.openviking.config.traceRecallDir ~/.openclaw/openviking/recall-traces

openclaw gateway restart

查询方式：

# Agent tool
ov_recall_trace(query="用户问题关键词", limit=10)

# Slash command
/ov-recall-trace --query "用户问题关键词" --limit 10

# Gateway route adapter 可用时
GET /api/openviking/recall-traces
GET /api/openviking/recall-traces/<traceId>

排查边界：

10.4.1 先打开插件侧可观测配置

# 打印 OpenViking search/session 路由、target_uri、query、agent/account/user header 等
openclaw config set plugins.entries.openviking.config.logFindRequests true

# 打印 assemble/afterTurn/compact 标准诊断
openclaw config set plugins.entries.openviking.config.emitStandardDiagnostics true

# 如果希望自动召回只查导入的文档/URL/目录资源，设置 resource-only
openclaw config set plugins.entries.openviking.config.recallTargetTypes '["resource"]'

# 如果希望保留默认 user/agent 记忆，同时额外查 resources，也可使用旧兼容加法开关
openclaw config set plugins.entries.openviking.config.recallResources true

# 如果希望记录本轮召回详情，必须显式打开 trace
openclaw config set plugins.entries.openviking.config.traceRecall true

openclaw gateway restart

也可以临时用环境变量打开路由日志：

OPENVIKING_LOG_ROUTING=1 openclaw gateway restart
# 或
OPENVIKING_DEBUG=1 openclaw gateway restart

10.4.2 看日志中的关键字段

一次自动召回通常会产生三类可观测信息：

其中 inject-detail 是排查“本轮模型实际看到了哪些 OpenViking 召回内容”的首选入口。它会列出每条被注入内容的 uri，例如：

openviking: inject-detail {"count":2,"memories":[{"uri":"viking://user/default/memories/preferences/...","category":"preferences","abstract":"...","score":0.82,"is_leaf":true},{"uri":"viking://resources/project-docs/api.md#chunk-3","category":"resource","abstract":"...","score":0.71,"is_leaf":true}]}

注意：自动注入到模型输入里的 <relevant-memories> 块默认只包含类别和内容，不直接暴露 URI；URI/路径主要从插件日志、memory_recall / ov_search 工具 details、或 OpenViking API 返回中获取。

10.4.3 用 OpenClaw 工具显式复现召回

如果想把“命中的路径”直接展示给 Agent 或用户，可以让 Agent 显式调用工具：

# 查长期记忆，默认查 memory 类型视图；recallTargetTypes 可切换默认范围
memory_recall(query="用户问题关键词", limit=10)

# 查导入的文档、URL、目录、仓库资源
ov_search(query="用户问题关键词", uri="viking://resources", limit=10)

# 查 OpenViking skills
ov_search(query="用户问题关键词", uri="viking://user/skills", limit=10)

ov_search 的文本结果会显示 type、uri、level、score 和摘要；工具 details 里也会保留原始 resources[] / skills[] / memories[] 数组。

注意：这些 uri 是 OpenViking 虚拟 URI，不是本地文件路径。需要完整内容时，让 Agent 调用 ov_read(uri="viking://...")，不要把 viking://... 或历史兼容展示里的 openviking://... 当作本地路径交给文件读取工具。

10.4.4 直接调用 OpenViking API 获取路径和内容

插件调用 OpenViking 时统一携带认证和路由 header。手工排查时也要保持一致：

export OPENVIKING_BASE_URL="http://127.0.0.1:1933"
export OPENVIKING_API_KEY="<your-api-key>"

# root key / trusted server 场景按需补充
export OPENVIKING_ACCOUNT_ID="<account-id>"
export OPENVIKING_USER_ID="<user-id>"

语义检索并获取命中 URI：

headers=(
  -H "Content-Type: application/json"
  -H "X-API-Key: $OPENVIKING_API_KEY"
)

if [ -n "${OPENVIKING_ACCOUNT_ID:-}" ]; then
  headers+=( -H "X-OpenViking-Account: $OPENVIKING_ACCOUNT_ID" )
fi
if [ -n "${OPENVIKING_USER_ID:-}" ]; then
  headers+=( -H "X-OpenViking-User: $OPENVIKING_USER_ID" )
fi

curl -sS "$OPENVIKING_BASE_URL/api/v1/search/find" \
  "${headers[@]}" \
  -d '{
    "query": "用户问题关键词",
    "target_uri": "viking://resources",
    "limit": 10,
    "score_threshold": 0.15
  }'

典型返回中需要关注：

{
  "resources": [
    {
      "uri": "viking://resources/project-docs/api.md#chunk-3",
      "level": 2,
      "score": 0.71,
      "abstract": "命中的段落摘要",
      "category": "resource"
    }
  ],
  "memories": [],
  "skills": [],
  "total": 1
}

拿到 uri 后读取完整内容：

curl -sS "$OPENVIKING_BASE_URL/api/v1/content/read?uri=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe=""))' 'viking://resources/project-docs/api.md#chunk-3')" \
  "${headers[@]}"

10.4.5 OpenViking API 速查表

完整官方 API 清单、参数说明和插件映射见 6.2 OpenViking 官方 API 完整清单与插件映射。本节只保留排查“召回了哪些数据 / 用了哪些文档”时最常用的调用。

10.4.6 判断“用了哪些文档”的边界

• 如果文档是通过 auto recall 进入模型上下文：看 inject-detail 中 category=resource 或 uri 以 viking://resources 开头的条目。
• 如果文档是通过 显式工具 进入模型上下文：看 ov_search 工具结果里的 uri 和工具 details.resources[]。
• 如果只看到了 find POST 但没有 injecting / inject-detail：说明插件发起了检索，但最终可能因为分数阈值、去重、leaf 过滤或 recallMaxInjectedChars 预算没有注入模型。
• 如果未显式配置 recallTargetTypes，自动召回默认使用 context_type=memory 查当前 user 的 memory 视图，不会把 viking://resources 文档自动注入；resource-only 用 recallTargetTypes=["resource"]，默认 memory 视图 + resources 用 recallResources=true 或 recallTargetTypes=["user","agent","resource"]。
• 如果没查到 recall trace，先检查 traceRecall=true 是否已配置并重启 Gateway；recallTargetTypes / recallResources 不负责启用 trace。
• 当前插件没有单独生成“模型最终引用/采纳哪些文档”的 citation 文件；最可靠的依据是本轮注入内容、工具调用结果、OpenViking API 返回和模型回复本身。

10.5 常见问题定位

10.6 OpenViking 服务侧排查

# 服务端日志，路径以实际部署为准
tail -f ~/.openviking/data/log/openviking.log

# Web Console
python -m openviking.console.bootstrap \
  --host 0.0.0.0 \
  --port 8020 \
  --openviking-url http://127.0.0.1:1933

# TUI
ov tui

11. 验证与测试

11.1 仓库本地验证

npm install
npm run typecheck
npm test
npm run build

当前 package.json 中提供的脚本：build、test、typecheck：package.json:36。

11.2 关键单测覆盖方向

11.3 插件链路验证

openclaw openviking status --json
openclaw config get plugins.slots.contextEngine

如果需要完整链路验证，可以运行健康检查脚本：

python health_check_tools/ov-healthcheck.py

该脚本用于注入真实对话，并在 OpenViking 侧验证会话捕获、提交、归档和记忆抽取。说明见 health_check_tools/HEALTHCHECK-ZH.md。

11.4 手工端到端验证建议

1. 安装并配置插件。
2. 打开 logFindRequests 和 emitStandardDiagnostics。
3. 与 Agent 对话输入一条明确偏好，例如“记住：我喜欢用中文回复技术文档”。
4. 等待 afterTurn 或手动触发 /compact。
5. 新开一轮问“我之前偏好什么语言回复技术文档？”。
6. 观察最新 user message 是否注入 <relevant-memories>，或用 memory_recall 显式查。
7. 用 OpenViking Console/TUI 检查 viking://user/.../memories 是否产生 leaf memory。
8. 对长工具输出场景，确认 preview 中有 viking://user/sessions/.../tool-results/...，再用 tool-result 工具读取完整内容。

12. 注意事项

1. 插件只支持 remote 模式：旧 local mode 会被迁移提示，不会启动本地 OpenViking 进程。
2. 必须重启 Gateway：安装或配置后要 openclaw gateway restart 才能生效。
3. 不要装错包：@openviking/openclaw-plugin 是插件；clawhub install openviking 是 AgentSkill。
4. API Key 不进日志：插件路由日志不会打印 key，但仍应避免把 key 写入公开文档或命令历史。
5. Root Key 需要租户上下文：若服务端要求 account/user header，必须配置 accountId 和 userId。
6. peer 配置要一致：需要说话人隔离时，确认 peer_role / peer_prefix 与预期一致，否则会导致写查不一致。
7. afterTurn commit 是异步抽取：立即返回不代表长期记忆已可检索；看 task 或服务端日志。
8. compact 是同步边界：需要明确压缩和抽取完成时用 compact，但它会阻塞等待服务端 Phase 2。
9. 记忆注入有预算：recallMaxInjectedChars 会跳过放不下的完整记忆，而不是截断。
10. bypassSessionPatterns 会完全绕过 OpenViking：匹配后自动捕获、召回、工具都会跳过。
11. tool result 工具限制当前 session：插件拒绝读取其他 session 的外置结果。
12. 本地资源导入先上传：本地文件/目录通过 temp upload，不把本地路径直接交给服务端；目录会 zip，注意权限与体积。

13. 维护者代码阅读路线

建议按以下顺序阅读：

1. openclaw.plugin.json：了解插件声明、工具 contract、配置 schema。
2. package.json：了解构建、OpenClaw 入口、兼容版本。
3. commands/setup.ts：了解用户安装配置如何写入 OpenClaw config。
4. index.ts：了解插件注册、工具、hook 和 service。
5. client.ts：了解 OpenViking API 封装和 header/URI 处理。
6. context-engine.ts：理解 assemble/afterTurn/compact 主链路。
7. auto-recall.ts + memory-ranking.ts：理解召回注入和排序。
8. text-utils.ts + session-transcript-repair.ts：理解消息清洗与 transcript 结构修复。
9. tests/ut/*：用测试反向确认 contract。

14. 快速排障 Checklist

• OpenViking Server GET /health 可达。
• openclaw openviking status --json 中 configured=true。
• slotActive=true。
• Gateway 已重启。
• plugins.entries.openviking.config.baseUrl 指向正确服务。
• root key 场景已配置 accountId/userId。
• 需要说话人隔离时，peer_role / peer_prefix 与预期一致。
• autoCapture/autoRecall 未被关闭。
• 当前 session 没有命中 bypassSessionPatterns。
• pending_tokens 是否达到 commitTokenThreshold。
• Phase 2 task 是否 completed。
• 需要细节时是否使用 archive 工具回查。

15. 构建、测试和本地验证流程

本章面向维护者，按“改代码 → 本地验证 → 构建 → 本地加载验证”的顺序给出最短路径。TOS 上传、下载、灰度、发布和回滚流程不属于本示例范围。

15.1 本地开发准备

git clone <repo-url>
cd arkclaw-openviking-plugin
node -v        # 需要 Node.js >= 22
npm install

核心脚本来自 package.json：

15.2 本地测试

最小代码质量检查：

npm run typecheck
npm test
npm run build

构建后应确认 dist/index.js 和 dist/commands/setup.js 存在，且 package.json 中的 OpenClaw 入口指向 dist/。

重要契约：运行时依赖必须留在 dependencies，例如 @sinclair/typebox 和 fflate，避免 OpenClaw 运行时加载插件失败。

15.3 本地加载验证

npm run build
openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key <OPENVIKING_API_KEY> --json

安装后检查：

openclaw openviking status --json
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine

15.4 运行后 Debug Checklist

openclaw openviking status --json
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine
curl <OPENVIKING_BASE_URL>/health

建议临时打开：

openclaw config set plugins.entries.openviking.config.logFindRequests true
openclaw config set plugins.entries.openviking.config.emitStandardDiagnostics true
openclaw gateway restart

如果排查“召回到底用了哪些结果”，再打开 trace：

openclaw config set plugins.entries.openviking.config.traceRecall true
openclaw config set plugins.entries.openviking.config.traceRecallPersist true
openclaw gateway restart

然后使用 ov_recall_trace / /ov-recall-trace 查询。注意：traceRecall=true 是 trace 总开关，配置召回范围（如 recallTargetTypes=["resource"]）不会自动打开 trace。

15.5 常见问题

16. 参考文档

• README_CN.md：项目中文快速说明。
• INSTALL-ZH.md：安装、升级、卸载指南。
• INSTALL-AGENT.md：Agent 自动安装说明。
• docs/workmemory-v2-design.md：Working Memory v2 设计。
• docs/workmemory-v2-test-report.md：Working Memory v2 测试报告。
• health_check_tools/HEALTHCHECK-ZH.md：健康检查脚本说明。