OpenViking OpenClaw 插件参考文档

本文档汇总当前分支提供的插件配置参数、安装/配置命令、Slash 命令、Agent 可见 Tools、Gateway API 以及插件调用的 OpenViking 后端 API。适用于接入、运维、排障和二次开发。

1. 插件入口与运行结构

OpenViking 插件以 OpenClaw context-engine plugin 方式运行：

• 插件入口：dist/index.js
• Setup CLI 入口：dist/commands/setup.js
• 插件 ID：openviking
• Context engine slot：plugins.slots.contextEngine = "openviking"

运行期主要能力分为 6 层：

1. 配置层：解析 plugins.entries.openviking.config，并支持部分环境变量兜底。
2. Context Engine 层：负责 session assemble、afterTurn 写入、compact、auto-recall、auto-capture。
3. Agent Tools 层：向模型暴露记忆、资源查询、归档检索、工具结果恢复等工具。
4. Slash Commands 层：向用户暴露 /add-resource、/add-skill、/ov-search、/ov-recall-trace。
5. Gateway API 层：向外提供 recall trace 查询接口。
6. OpenViking Client 层：封装 OpenViking Server HTTP API。

2. 配置文件位置与基本结构

默认配置文件：

~/.openclaw/openclaw.json

如果设置了 OPENCLAW_STATE_DIR，则使用：

$OPENCLAW_STATE_DIR/openclaw.json

典型配置结构：

{
  "plugins": {
    "slots": {
      "contextEngine": "openviking"
    },
    "entries": {
      "openviking": {
        "config": {
          "mode": "remote",
          "baseUrl": "http://127.0.0.1:1933",
          "apiKey": "${OPENVIKING_API_KEY}",
          "autoCapture": true,
          "autoRecall": true,
          "recallTargetTypes": ["user", "agent"]
        }
      }
    }
  }
}

3. 配置参数参考

3.1 连接与认证

3.2 Peer 与检索隔离

3.3 自动捕获与提交

3.4 自动召回与显式召回

3.5 Recall Trace

3.6 诊断、绕过与工具开关

4. Agent Tools 开关

4.1 工具分组

enabledTools / disabledTools 支持以下分组：

4.2 只保留资源查询工具

适用于“禁用记忆，但允许 Agent 查询 OpenViking 知识库资源”的场景：

{
  "autoCapture": false,
  "autoRecall": false,
  "enabledTools": ["resource_query"]
}

注册结果：

• ov_search
• ov_read

不会注册：

• memory_recall
• memory_store
• memory_forget
• 其他默认 tools

4.3 保留默认工具但禁用记忆 Tools

{
  "disabledTools": ["memory"]
}

会禁用：

• memory_recall
• memory_store
• memory_forget

保留默认工具中的资源查询、归档、trace、tool result 能力。

4.4 启用 add_resource Agent Tool

add_resource 需要双重 opt-in：

{
  "enabledTools": ["add_resource"],
  "enableAddResourceTool": true
}

如果配置为：

{
  "enabledTools": ["all"]
}

但没有设置 enableAddResourceTool=true，add_resource 仍不会注册。

5. Setup / CLI 命令

5.1 openclaw openviking setup

用途：配置插件连接 OpenViking Server，并激活 context-engine slot。

openclaw openviking setup [options]

参数：

常见示例：

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-xxx \
  --account-id acc_123 \
  --user-id user_456 \
  --json

只召回资源：

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

Server 暂不可达但仍写配置：

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

替换已有 context-engine slot owner：

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

5.2 openclaw openviking status

用途：查看当前配置、连接状态、slot 是否激活。

openclaw openviking status [--zh] [--json]

参数：

示例：

openclaw openviking status --json

5.3 Runtime Slash Alias

Manifest 中声明了 runtime slash alias：

具体可用性取决于当前 OpenClaw runtime 是否支持该 alias 类型。

6. Slash Commands

6.1 /add-resource

用途：手动把文件、目录、URL、Git 仓库或 OpenClaw media attachment 导入 OpenViking resources。

/add-resource <source> [--to URI] [--parent URI] [--reason TEXT] [--instruction TEXT] [--wait] [--timeout SEC]

参数：

示例：

/add-resource ./README.md --to viking://resources/project-readme --reason "project docs" --wait

注意：/add-resource 是手动命令，不受 enableAddResourceTool=false 限制。

6.2 /add-skill

用途：手动导入 SKILL.md 文件或 skill 目录。

/add-skill <source> [--wait] [--timeout SEC]

参数：

示例：

/add-skill ./skills/my-skill --wait --timeout 30

6.3 /ov-search

用途：搜索 OpenViking resources 和 skills。

/ov-search <query> [--uri URI] [--limit N]

参数：

示例：

/ov-search "OpenViking install" --uri viking://resources --limit 5

返回的 viking://... 是 OpenViking 虚拟 URI，不是本地文件路径。如需读取完整内容，请使用 ov_read Agent Tool。

6.4 /ov-recall-trace

用途：查询 recall trace，排查 auto-recall、memory_recall、ov_search、ov_archive_search 的召回链路。

/ov-recall-trace [--turn latest|all] [--trace-id ID] [--session-id ID] [--session-key KEY] [--ov-session-id ID] [--source SOURCE] [--resource-types TYPES] [--since TS] [--until TS] [--include-content] [--limit N]

参数：

示例：

/ov-recall-trace --source ov_search --include-content --limit 10

7. Agent-visible Tools

7.1 默认 Tools

7.2 Opt-in Tool：add_resource

安全边界：搜索、读取、trace 和资源消费路径应优先使用 ov_search / ov_read，不要让 Agent 在检索阶段自动导入新资源，除非用户明确授权。

8. Gateway API

8.1 GET /api/openviking/recall-traces

用途：查询 recall trace 列表。

Query 参数：

示例：

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?source=ov_search&includeContent=true&limit=10'

8.2 GET /api/openviking/recall-traces/:traceId

用途：按 trace id 查询单条或相关 trace。

示例：

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces/ov_search-1780329600000-a1b2c3d4'

8.3 Gateway route 不可用时的替代方式

如果当前 OpenClaw Gateway 没有提供 route adapter，插件会跳过 HTTP route 注册。此时可使用：

• Agent Tool：ov_recall_trace
• Slash Command：/ov-recall-trace

9. OpenViking 后端 API 封装

插件通过 OpenVikingClient 调用 OpenViking Server。统一 Header：

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

后端 API 封装清单：

10. 常见配置组合

10.1 记忆与资源默认模式

{
  "autoCapture": true,
  "autoRecall": true,
  "recallTargetTypes": ["user", "agent"]
}

10.2 自动召回资源库，不启用记忆写入

{
  "autoCapture": false,
  "autoRecall": true,
  "recallTargetTypes": ["resource"],
  "enabledTools": ["resource_query"]
}

10.3 完全禁用自动记忆，只保留手动资源查询

{
  "autoCapture": false,
  "autoRecall": false,
  "enabledTools": ["resource_query"]
}

10.4 开启 Recall Trace 排障

{
  "traceRecall": true,
  "traceRecallPersist": true,
  "traceRecallDir": "~/.openclaw/openviking/recall-traces",
  "traceRecallRetentionDays": 14,
  "traceRecallMaxEntries": 1000,
  "traceRecallMaxResultsPerSearch": 20,
  "traceRecallPreviewChars": 240
}

10.5 Root Key / Trusted 部署

{
  "baseUrl": "https://openviking.example.com",
  "apiKey": "${OPENVIKING_API_KEY}",
  "accountId": "${OPENVIKING_ACCOUNT_ID}",
  "userId": "${OPENVIKING_USER_ID}"
}

11. 注意事项

1. viking://... 是 OpenViking 虚拟 URI，不是本地文件路径。
2. 读取 OpenViking 搜索结果全文应使用 ov_read 或 /api/v1/content/read，不要交给本地文件读取工具。
3. add_resource Agent Tool 默认禁用；手动 /add-resource 始终可用。
4. 如果只想保留资源查询能力，优先设置 autoCapture=false、autoRecall=false、enabledTools=["resource_query"]。
5. 如果要排查召回未命中，开启 traceRecall=true，并使用 /ov-recall-trace 或 Gateway recall trace API。
6. logFindRequests 会输出路由、target URI、query 等信息，但不会输出 API Key。
7. Root key 场景通常必须配置 accountId 和 userId，否则服务端可能无法确定租户上下文。