@openviking/openclaw-plugin 2026.5.26 → 2026.6.17-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/INSTALL-AGENT.md +355 -355
  2. package/INSTALL-ZH.md +405 -345
  3. package/INSTALL.md +366 -362
  4. package/README.md +364 -338
  5. package/adapters/http-transport.ts +3 -0
  6. package/adapters/resource-packager.ts +141 -0
  7. package/auto-recall.ts +518 -257
  8. package/client.ts +963 -939
  9. package/commands/setup.ts +1169 -1002
  10. package/config/feature-gates.json +10 -0
  11. package/config.ts +819 -476
  12. package/context-engine.ts +408 -1737
  13. package/dist/adapters/http-transport.js +1 -0
  14. package/dist/adapters/resource-packager.js +114 -0
  15. package/dist/auto-recall.js +228 -32
  16. package/dist/client.js +125 -161
  17. package/dist/commands/setup.js +170 -32
  18. package/dist/config.js +285 -64
  19. package/dist/context-engine.js +64 -1179
  20. package/dist/index.js +209 -1470
  21. package/dist/memory-ranking.js +35 -12
  22. package/dist/plugin/command-registration.js +5 -0
  23. package/dist/plugin/openviking-archive-tools.js +210 -0
  24. package/dist/plugin/openviking-bypass-runtime.js +8 -0
  25. package/dist/plugin/openviking-client-runtime.js +28 -0
  26. package/dist/plugin/openviking-command-args.js +146 -0
  27. package/dist/plugin/openviking-command-definitions.js +206 -0
  28. package/dist/plugin/openviking-context-engine-ref.js +11 -0
  29. package/dist/plugin/openviking-context-engine-registration.js +23 -0
  30. package/dist/plugin/openviking-feature-gates.js +250 -0
  31. package/dist/plugin/openviking-import-runtime.js +50 -0
  32. package/dist/plugin/openviking-import-tools.js +86 -0
  33. package/dist/plugin/openviking-lifecycle-hooks.js +33 -0
  34. package/dist/plugin/openviking-memory-recall-tools.js +233 -0
  35. package/dist/plugin/openviking-memory-tools.js +199 -0
  36. package/dist/plugin/openviking-query-config-command.js +203 -0
  37. package/dist/plugin/openviking-query-runtime.js +367 -0
  38. package/dist/plugin/openviking-query-tools.js +91 -0
  39. package/dist/plugin/openviking-recall-trace-runtime.js +387 -0
  40. package/dist/plugin/openviking-recall-trace-tools.js +38 -0
  41. package/dist/plugin/openviking-runtime-state.js +26 -0
  42. package/dist/plugin/openviking-runtime-utils.js +62 -0
  43. package/dist/plugin/openviking-services.js +20 -0
  44. package/dist/plugin/openviking-session-routing-runtime.js +61 -0
  45. package/dist/plugin/openviking-tool-result-tools.js +268 -0
  46. package/dist/plugin/recall-trace-routes.js +77 -0
  47. package/dist/plugin/tool-registration.js +23 -0
  48. package/dist/process-manager.js +5 -17
  49. package/dist/query-config.js +336 -0
  50. package/dist/recall-trace.js +309 -0
  51. package/dist/registries/recall-resource-types.js +58 -0
  52. package/dist/routing/identity-routing.js +152 -0
  53. package/dist/routing/memory-uri.js +7 -0
  54. package/dist/services/context-lifecycle-service.js +847 -0
  55. package/dist/services/context-message-adapter.js +340 -0
  56. package/dist/session-transcript-repair.js +0 -1
  57. package/dist/text-utils.js +14 -31
  58. package/dist/token-estimator.js +51 -0
  59. package/index.ts +408 -1985
  60. package/install-manifest.json +57 -47
  61. package/memory-ranking.ts +303 -267
  62. package/openclaw.plugin.json +497 -335
  63. package/package.json +86 -76
  64. package/plugin/command-registration.ts +34 -0
  65. package/plugin/openviking-archive-tools.ts +301 -0
  66. package/plugin/openviking-bypass-runtime.ts +26 -0
  67. package/plugin/openviking-client-runtime.ts +74 -0
  68. package/plugin/openviking-command-args.ts +187 -0
  69. package/plugin/openviking-command-definitions.ts +294 -0
  70. package/plugin/openviking-context-engine-ref.ts +16 -0
  71. package/plugin/openviking-context-engine-registration.ts +97 -0
  72. package/plugin/openviking-feature-gates.ts +335 -0
  73. package/plugin/openviking-import-runtime.ts +105 -0
  74. package/plugin/openviking-import-tools.ts +133 -0
  75. package/plugin/openviking-lifecycle-hooks.ts +65 -0
  76. package/plugin/openviking-memory-recall-tools.ts +368 -0
  77. package/plugin/openviking-memory-tools.ts +299 -0
  78. package/plugin/openviking-query-config-command.ts +230 -0
  79. package/plugin/openviking-query-formatters.ts +108 -0
  80. package/plugin/openviking-query-runtime.ts +476 -0
  81. package/plugin/openviking-query-tools.ts +161 -0
  82. package/plugin/openviking-recall-trace-runtime.ts +482 -0
  83. package/plugin/openviking-recall-trace-tools.ts +99 -0
  84. package/plugin/openviking-runtime-state.ts +52 -0
  85. package/plugin/openviking-runtime-utils.ts +67 -0
  86. package/plugin/openviking-services.ts +49 -0
  87. package/plugin/openviking-session-routing-runtime.ts +105 -0
  88. package/plugin/openviking-tool-result-tools.ts +397 -0
  89. package/plugin/recall-trace-routes.ts +133 -0
  90. package/plugin/tool-registration.ts +51 -0
  91. package/process-manager.ts +41 -45
  92. package/query-config.ts +400 -0
  93. package/recall-trace.ts +442 -0
  94. package/registries/openviking-tools.ts +84 -0
  95. package/registries/recall-resource-types.ts +74 -0
  96. package/routing/identity-routing.ts +210 -0
  97. package/routing/memory-uri.ts +8 -0
  98. package/runtime-utils.ts +5 -5
  99. package/services/context-lifecycle-service.ts +1209 -0
  100. package/services/context-message-adapter.ts +375 -0
  101. package/services/setup/config-writer.ts +125 -0
  102. package/services/setup/exit-utils.ts +5 -0
  103. package/services/setup/package-metadata.ts +56 -0
  104. package/services/setup/probe-service.ts +143 -0
  105. package/services/setup/setup-flow.ts +306 -0
  106. package/services/setup/version-compatibility.ts +41 -0
  107. package/session-transcript-repair.ts +528 -530
  108. package/skills/install-openviking-memory/SKILL.md +752 -665
  109. package/skills/openviking-context-database/SKILL.md +286 -0
  110. package/text-utils.ts +488 -507
  111. package/token-estimator.ts +65 -0
  112. package/tool-call-id.ts +331 -331
package/INSTALL.md CHANGED
@@ -1,362 +1,366 @@
1
- # Install OpenViking for OpenClaw
2
-
3
- OpenViking provides long-term memory, knowledge base search, semantic retrieval, and RAG-style context for OpenClaw through the `@openviking/openclaw-plugin` plugin.
4
-
5
- This guide describes the current plugin install flow. It is written for both people and automation agents.
6
-
7
- ## Do Not Install The Skill By Mistake
8
-
9
- `@openviking/openclaw-plugin` is an OpenClaw plugin.
10
-
11
- Do not use this command for plugin installation:
12
-
13
- ```bash
14
- clawhub install openviking
15
- ```
16
-
17
- That command installs an AgentSkill named `openviking`, not the OpenClaw plugin.
18
-
19
- Use this plugin command instead:
20
-
21
- ```bash
22
- openclaw plugins install clawhub:@openviking/openclaw-plugin
23
- ```
24
-
25
- ## Requirements
26
-
27
- | Component | Required |
28
- | --- | --- |
29
- | Node.js | >= 22 |
30
- | OpenClaw | >= 2026.4.8 |
31
-
32
- The plugin connects to an existing OpenViking server. It does not start the OpenViking server for you. Start OpenViking first, keep it running, then point the plugin `baseUrl` at that HTTP service. The default local URL is `http://127.0.0.1:1933`.
33
-
34
- OpenClaw plugin package boundaries:
35
-
36
- - `2026.4.8` is the minimum supported OpenClaw version for the current plugin.
37
- - `2026.5.3` starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
38
- - `2026.5.4` and later stop falling back to `.ts` source for installed/global plugin runtime loading when compiled JavaScript is missing.
39
- - The recommended `openclaw plugins install clawhub:@openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.
40
- - `ov-install` is the backup/source install path. Use it when ClawHub or the OpenClaw plugin manager path is unavailable/rate-limited, or when explicitly testing a source ref. For OpenClaw `>= 2026.5.3`, it builds the plugin during installation.
41
-
42
- Quick check:
43
-
44
- ```bash
45
- node -v
46
- openclaw --version
47
- ```
48
-
49
- ## Start OpenViking Server
50
-
51
- For a local OpenViking server on the same machine as OpenClaw:
52
-
53
- ```bash
54
- pip install openviking --upgrade --force-reinstall
55
- openviking-server init
56
- openviking-server doctor
57
- openviking-server
58
- ```
59
-
60
- `openviking-server init` writes the server configuration, `openviking-server doctor` validates local model/provider auth, and `openviking-server` starts the HTTP API. Keep this process running while OpenClaw uses the plugin.
61
-
62
- To run the server in the background:
63
-
64
- ```bash
65
- mkdir -p ~/.openviking/data/log
66
- nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &
67
- ```
68
-
69
- If OpenViking runs on another machine, start it on a reachable host/port, for example:
70
-
71
- ```bash
72
- openviking-server --host 0.0.0.0 --port 1933
73
- ```
74
-
75
- Then configure the OpenClaw plugin `baseUrl` to that address, such as `http://your-server:1933`.
76
-
77
- Verify the server before installing or restarting the plugin:
78
-
79
- ```bash
80
- curl http://127.0.0.1:1933/health
81
- ```
82
-
83
- ## Recommended Install Path
84
-
85
- Use this path for normal users, production installs, and agent-assisted installs.
86
-
87
- ### 1. Install The Plugin
88
-
89
- ```bash
90
- openclaw plugins install clawhub:@openviking/openclaw-plugin
91
- ```
92
-
93
- If your OpenClaw installation requires an explicit registry prefix, use:
94
-
95
- ```bash
96
- openclaw plugins install clawhub:@openviking/openclaw-plugin
97
- ```
98
-
99
- ### 2. Configure The Plugin
100
-
101
- For interactive human setup:
102
-
103
- ```bash
104
- openclaw openviking setup
105
- ```
106
-
107
- For non-interactive agent setup:
108
-
109
- ```bash
110
- openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
111
- ```
112
-
113
- Example:
114
-
115
- ```bash
116
- openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json
117
- ```
118
-
119
- The setup command writes `plugins.entries.openviking.config` and activates `plugins.slots.contextEngine=openviking`.
120
-
121
- If the OpenViking server is temporarily unreachable but you still want to save the config:
122
-
123
- ```bash
124
- openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json
125
- ```
126
-
127
- If your API key is a root key, setup may require tenant context:
128
-
129
- ```bash
130
- openclaw openviking setup \
131
- --base-url <OPENVIKING_URL> \
132
- --api-key <ROOT_API_KEY> \
133
- --account-id <ACCOUNT_ID> \
134
- --user-id <USER_ID> \
135
- --json
136
- ```
137
-
138
- If another context engine already owns the slot, setup will not replace it by default. To intentionally replace the current owner:
139
-
140
- ```bash
141
- openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
142
- ```
143
-
144
- If you need a custom agent routing prefix (optional; most users leave this empty):
145
-
146
- ```bash
147
- openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
148
- ```
149
-
150
- ### 3. Restart OpenClaw Gateway
151
-
152
- ```bash
153
- openclaw gateway restart
154
- ```
155
-
156
- If your OpenClaw version uses a different restart command, use the equivalent gateway restart for your environment.
157
-
158
- ### 4. Verify
159
-
160
- ```bash
161
- openclaw openviking status --json
162
- ```
163
-
164
- Expected result:
165
-
166
- | JSON field | Expected value |
167
- | --- | --- |
168
- | `configured` | `true` |
169
- | `slotActive` | `true` |
170
- | `health.ok` | `true` when the server is reachable |
171
-
172
- You can also inspect the raw OpenClaw config:
173
-
174
- ```bash
175
- openclaw config get plugins.entries.openviking.config
176
- openclaw config get plugins.slots.contextEngine
177
- ```
178
-
179
- `plugins.slots.contextEngine` should be `openviking`.
180
-
181
- ## Agent Result Handling
182
-
183
- Automation should prefer `--json` and branch on these fields:
184
-
185
- | Result | Meaning | Recommended action |
186
- | --- | --- | --- |
187
- | `success: true` | Config saved and setup completed | Restart gateway, then run status |
188
- | `success: false`, `action: "slot_blocked"` | Config may be saved, but another plugin owns `contextEngine` | Ask before rerunning with `--force-slot` |
189
- | `success: false`, `action: "error"` | Validation failed | Show `error`; do not claim install succeeded |
190
- | `health.ok: false` | Server unreachable | Check URL/server, or rerun with `--allow-offline` only if the user accepts |
191
- | `keyProbe.keyType: "root_key"` | Root key needs tenant context | Rerun with `--account-id` and `--user-id` |
192
-
193
- ## Configuration Reference
194
-
195
- The plugin config lives at:
196
-
197
- ```text
198
- plugins.entries.openviking.config
199
- ```
200
-
201
- Core fields:
202
-
203
- | Field | Default | Description |
204
- | --- | --- | --- |
205
- | `mode` | `remote` | Legacy compatibility field. Only remote mode is supported. |
206
- | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint |
207
- | `apiKey` | empty | OpenViking API key |
208
- | `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-`. |
209
- | `accountId` | empty | Required when using a root API key |
210
- | `userId` | empty | Required when using a root API key |
211
-
212
- Use setup for normal changes when possible:
213
-
214
- ```bash
215
- openclaw openviking setup --reconfigure
216
- ```
217
-
218
- Manual config inspection:
219
-
220
- ```bash
221
- openclaw config get plugins.entries.openviking.config
222
- ```
223
-
224
- ## Upgrade
225
-
226
- ```bash
227
- openclaw plugins update openviking
228
- openclaw gateway restart
229
- openclaw openviking status --json
230
- ```
231
-
232
- Confirm that `configured` and `slotActive` are both `true`.
233
-
234
- ## Uninstall
235
-
236
- ```bash
237
- openclaw plugins uninstall openviking
238
- openclaw config set plugins.slots.contextEngine legacy
239
- openclaw gateway restart
240
- ```
241
-
242
- Current OpenClaw native uninstall does not always reset `plugins.slots.contextEngine`. The explicit `config set` step avoids leaving the slot pointed at an uninstalled plugin.
243
-
244
- ## Optional Pipeline Health Check
245
-
246
- After status passes, you can run the bundled end-to-end health check from a repository checkout:
247
-
248
- ```bash
249
- python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
250
- ```
251
-
252
- This checks the Gateway to OpenViking path by injecting a real conversation and verifying capture, commit, archive, and memory extraction. See [health_check_tools/HEALTHCHECK.md](./health_check_tools/HEALTHCHECK.md).
253
-
254
- ## Backup Path: ov-install
255
-
256
- `ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install clawhub:@openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
257
-
258
- Try the OpenClaw plugin manager first. If that path is unavailable, run:
259
-
260
- ```bash
261
- npm install -g openclaw-openviking-setup-helper
262
- ov-install
263
- ```
264
-
265
- Useful backup/source flags:
266
-
267
- | Flag | Meaning |
268
- | --- | --- |
269
- | `--workdir PATH` | Target OpenClaw state directory |
270
- | `--plugin-version=REF` | Plugin version: npm version, npm dist-tag, or Git ref to install |
271
- | `--current-version` | Print the version tracked by the helper |
272
- | `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
273
- | `--api-key KEY` | OpenViking API key |
274
- | `--agent-prefix PREFIX` | Agent routing prefix |
275
- | `--update` | Update an existing helper-managed install |
276
-
277
- For user-facing installs, use `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
278
-
279
- ## Migrate From ov-install To openclaw plugin install
280
-
281
- If you previously installed OpenViking with `ov-install`, follow these steps before switching to the recommended `openclaw plugins install` path.
282
-
283
- ### Same Plugin ID (openviking, version >= 0.3.x)
284
-
285
- The ov-install context-engine deployment writes files to `~/.openclaw/extensions/openviking/`. After installing via npm, OpenClaw may still load from the old directory. Clean it up:
286
-
287
- ```bash
288
- # Remove ov-install deployed files
289
- rm -rf ~/.openclaw/extensions/openviking/
290
-
291
- # Install via the OpenClaw plugin manager
292
- openclaw plugins install clawhub:@openviking/openclaw-plugin
293
-
294
- # Reconfigure (your existing config in openclaw.json is preserved)
295
- openclaw openviking setup --reconfigure
296
- openclaw gateway restart
297
- openclaw openviking status --json
298
- ```
299
-
300
- Your existing config fields (`baseUrl`, `apiKey`, `agentId`, etc.) are preserved. The new plugin version reads old field names at runtime — no manual config edits needed.
301
-
302
- The plugin configuration lives under `plugins.entries.openviking.config`.
303
-
304
- Get the current full plugin configuration:
305
-
306
- ```bash
307
- openclaw config get plugins.entries.openviking.config
308
- ```
309
-
310
- ### Configuration Parameters
311
-
312
- The plugin connects to an existing remote OpenViking server.
313
-
314
- | Parameter | Default | Meaning |
315
- | --- | --- | --- |
316
- | `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |
317
- | `apiKey` | empty | Optional OpenViking API key |
318
- | `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-` |
319
-
320
- Common settings:
321
-
322
- ```bash
323
- openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
324
- openclaw config set plugins.entries.openviking.config.apiKey your-api-key
325
- openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix
326
- ```
327
-
328
- ## Start
329
-
330
- After installation (if you skipped reconfigure above):
331
-
332
- ```bash
333
- openclaw gateway restart
334
- openclaw openviking status --json
335
- ```
336
-
337
- ### Old Plugin ID (memory-openviking, version < 0.3.x)
338
-
339
- The old memory plugin used a different plugin ID and slot:
340
-
341
- ```bash
342
- # Uninstall old plugin
343
- openclaw plugins uninstall memory-openviking 2>/dev/null || true
344
-
345
- # Clean up old slot and files
346
- openclaw config set plugins.slots.memory none
347
- rm -rf ~/.openclaw/extensions/memory-openviking/
348
-
349
- # Install new plugin
350
- openclaw plugins install clawhub:@openviking/openclaw-plugin
351
- openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
352
- openclaw gateway restart
353
- openclaw openviking status --json
354
- ```
355
-
356
- Or use the cleanup script:
357
-
358
- ```bash
359
- bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
360
- ```
361
-
362
- See also: [INSTALL-ZH.md](./INSTALL-ZH.md) and [INSTALL-AGENT.md](./INSTALL-AGENT.md).
1
+ # Install OpenViking for OpenClaw
2
+
3
+ OpenViking provides long-term memory, knowledge base search, semantic retrieval, and RAG-style context for OpenClaw through the `@openviking/openclaw-plugin` plugin.
4
+
5
+ This guide describes the current plugin install flow. It is written for both people and automation agents.
6
+
7
+ ## Do Not Install The Skill By Mistake
8
+
9
+ `@openviking/openclaw-plugin` is an OpenClaw plugin.
10
+
11
+ Do not use this command for plugin installation:
12
+
13
+ ```bash
14
+ clawhub install openviking
15
+ ```
16
+
17
+ That command installs an AgentSkill named `openviking`, not the OpenClaw plugin.
18
+
19
+ Use this plugin command instead:
20
+
21
+ ```bash
22
+ openclaw plugins install clawhub:@openviking/openclaw-plugin
23
+ ```
24
+
25
+ ## Requirements
26
+
27
+ | Component | Required |
28
+ | --- | --- |
29
+ | Node.js | >= 22 |
30
+ | OpenClaw | >= 2026.4.8 |
31
+
32
+ The plugin connects to an existing OpenViking server. It does not start the OpenViking server for you. Start OpenViking first, keep it running, then point the plugin `baseUrl` at that HTTP service. The default local URL is `http://127.0.0.1:1933`.
33
+
34
+ OpenClaw plugin package boundaries:
35
+
36
+ - `2026.4.8` is the minimum supported OpenClaw version for the current plugin.
37
+ - `2026.5.3` starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
38
+ - `2026.5.4` and later stop falling back to `.ts` source for installed/global plugin runtime loading when compiled JavaScript is missing.
39
+ - The recommended `openclaw plugins install clawhub:@openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.
40
+ - `ov-install` is the backup/source install path. Use it when ClawHub or the OpenClaw plugin manager path is unavailable/rate-limited, or when explicitly testing a source ref. For OpenClaw `>= 2026.5.3`, it builds the plugin during installation.
41
+
42
+ Quick check:
43
+
44
+ ```bash
45
+ node -v
46
+ openclaw --version
47
+ ```
48
+
49
+ ## Start OpenViking Server
50
+
51
+ For a local OpenViking server on the same machine as OpenClaw:
52
+
53
+ ```bash
54
+ pip install openviking --upgrade --force-reinstall
55
+ openviking-server init
56
+ openviking-server doctor
57
+ openviking-server
58
+ ```
59
+
60
+ `openviking-server init` writes the server configuration, `openviking-server doctor` validates local model/provider auth, and `openviking-server` starts the HTTP API. Keep this process running while OpenClaw uses the plugin.
61
+
62
+ To run the server in the background:
63
+
64
+ ```bash
65
+ mkdir -p ~/.openviking/data/log
66
+ nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &
67
+ ```
68
+
69
+ If OpenViking runs on another machine, start it on a reachable host/port, for example:
70
+
71
+ ```bash
72
+ openviking-server --host 0.0.0.0 --port 1933
73
+ ```
74
+
75
+ Then configure the OpenClaw plugin `baseUrl` to that address, such as `http://your-server:1933`.
76
+
77
+ Verify the server before installing or restarting the plugin:
78
+
79
+ ```bash
80
+ curl http://127.0.0.1:1933/health
81
+ ```
82
+
83
+ ## Recommended Install Path
84
+
85
+ Use this path for normal users, production installs, and agent-assisted installs.
86
+
87
+ ### 1. Install The Plugin
88
+
89
+ ```bash
90
+ openclaw plugins install clawhub:@openviking/openclaw-plugin
91
+ ```
92
+
93
+ If your OpenClaw installation requires an explicit registry prefix, use:
94
+
95
+ ```bash
96
+ openclaw plugins install clawhub:@openviking/openclaw-plugin
97
+ ```
98
+
99
+ ### 2. Configure The Plugin
100
+
101
+ For interactive human setup:
102
+
103
+ ```bash
104
+ openclaw openviking setup
105
+ ```
106
+
107
+ For non-interactive agent setup:
108
+
109
+ ```bash
110
+ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
111
+ ```
112
+
113
+ Example:
114
+
115
+ ```bash
116
+ openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json
117
+ ```
118
+
119
+ The setup command writes `plugins.entries.openviking.config` and activates `plugins.slots.contextEngine=openviking`.
120
+
121
+ If the OpenViking server is temporarily unreachable but you still want to save the config:
122
+
123
+ ```bash
124
+ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json
125
+ ```
126
+
127
+ If your API key is a root key, setup may require tenant context:
128
+
129
+ ```bash
130
+ openclaw openviking setup \
131
+ --base-url <OPENVIKING_URL> \
132
+ --api-key <ROOT_API_KEY> \
133
+ --account-id <ACCOUNT_ID> \
134
+ --user-id <USER_ID> \
135
+ --json
136
+ ```
137
+
138
+ If another context engine already owns the slot, setup will not replace it by default. To intentionally replace the current owner:
139
+
140
+ ```bash
141
+ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
142
+ ```
143
+
144
+ If you want assistant messages to carry a prefixed `peer_id` and data-plane recall/search requests to use the matching actor peer view, pass a prefix explicitly:
145
+
146
+ ```bash
147
+ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
148
+ ```
149
+
150
+ ### 3. Restart OpenClaw Gateway
151
+
152
+ ```bash
153
+ openclaw gateway restart
154
+ ```
155
+
156
+ If your OpenClaw version uses a different restart command, use the equivalent gateway restart for your environment.
157
+
158
+ ### 4. Verify
159
+
160
+ ```bash
161
+ openclaw openviking status --json
162
+ ```
163
+
164
+ Expected result:
165
+
166
+ | JSON field | Expected value |
167
+ | --- | --- |
168
+ | `configured` | `true` |
169
+ | `slotActive` | `true` |
170
+ | `health.ok` | `true` when the server is reachable |
171
+
172
+ You can also inspect the raw OpenClaw config:
173
+
174
+ ```bash
175
+ openclaw config get plugins.entries.openviking.config
176
+ openclaw config get plugins.slots.contextEngine
177
+ ```
178
+
179
+ `plugins.slots.contextEngine` should be `openviking`.
180
+
181
+ ## Agent Result Handling
182
+
183
+ Automation should prefer `--json` and branch on these fields:
184
+
185
+ | Result | Meaning | Recommended action |
186
+ | --- | --- | --- |
187
+ | `success: true` | Config saved and setup completed | Restart gateway, then run status |
188
+ | `success: false`, `action: "slot_blocked"` | Config may be saved, but another plugin owns `contextEngine` | Ask before rerunning with `--force-slot` |
189
+ | `success: false`, `action: "error"` | Validation failed | Show `error`; do not claim install succeeded |
190
+ | `health.ok: false` | Server unreachable | Check URL/server, or rerun with `--allow-offline` only if the user accepts |
191
+ | `keyProbe.keyType: "root_key"` | Root key needs tenant context | Rerun with `--account-id` and `--user-id` |
192
+
193
+ ## Configuration Reference
194
+
195
+ The plugin config lives at:
196
+
197
+ ```text
198
+ plugins.entries.openviking.config
199
+ ```
200
+
201
+ Core fields:
202
+
203
+ | Field | Default | Description |
204
+ | --- | --- | --- |
205
+ | `mode` | `remote` | Legacy compatibility field. Only remote mode is supported. |
206
+ | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint |
207
+ | `apiKey` | empty | OpenViking API key |
208
+ | `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
209
+ | `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant`. |
210
+ | `accountId` | empty | Required when using a root API key |
211
+ | `userId` | empty | Required when using a root API key |
212
+
213
+ Use setup for normal changes when possible:
214
+
215
+ ```bash
216
+ openclaw openviking setup --reconfigure
217
+ ```
218
+
219
+ Manual config inspection:
220
+
221
+ ```bash
222
+ openclaw config get plugins.entries.openviking.config
223
+ ```
224
+
225
+ ## Upgrade
226
+
227
+ ```bash
228
+ openclaw plugins update openviking
229
+ openclaw gateway restart
230
+ openclaw openviking status --json
231
+ ```
232
+
233
+ Confirm that `configured` and `slotActive` are both `true`.
234
+
235
+ ## Uninstall
236
+
237
+ ```bash
238
+ openclaw plugins uninstall openviking
239
+ openclaw config set plugins.slots.contextEngine legacy
240
+ openclaw gateway restart
241
+ ```
242
+
243
+ Current OpenClaw native uninstall does not always reset `plugins.slots.contextEngine`. The explicit `config set` step avoids leaving the slot pointed at an uninstalled plugin.
244
+
245
+ ## Optional Pipeline Health Check
246
+
247
+ After status passes, you can run the bundled end-to-end health check from a repository checkout:
248
+
249
+ ```bash
250
+ python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
251
+ ```
252
+
253
+ This checks the Gateway to OpenViking path by injecting a real conversation and verifying capture, commit, archive, and memory extraction. See [health_check_tools/HEALTHCHECK.md](./health_check_tools/HEALTHCHECK.md).
254
+
255
+ ## Backup Path: ov-install
256
+
257
+ `ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install clawhub:@openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
258
+
259
+ Try the OpenClaw plugin manager first. If that path is unavailable, run:
260
+
261
+ ```bash
262
+ npm install -g openclaw-openviking-setup-helper
263
+ ov-install
264
+ ```
265
+
266
+ Useful backup/source flags:
267
+
268
+ | Flag | Meaning |
269
+ | --- | --- |
270
+ | `--workdir PATH` | Target OpenClaw state directory |
271
+ | `--plugin-version=REF` | Plugin version: npm version, npm dist-tag, or Git ref to install |
272
+ | `--current-version` | Print the version tracked by the helper |
273
+ | `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
274
+ | `--api-key KEY` | OpenViking API key |
275
+ | `--peer-role ROLE` | Peer role: `none`, `assistant`, or `person` |
276
+ | `--peer-prefix PREFIX` | Prefix for assistant `peer_id` / actor peer values |
277
+ | `--update` | Update an existing helper-managed install |
278
+
279
+ For user-facing installs, use `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
280
+
281
+ ## Migrate From ov-install To openclaw plugin install
282
+
283
+ If you previously installed OpenViking with `ov-install`, follow these steps before switching to the recommended `openclaw plugins install` path.
284
+
285
+ ### Same Plugin ID (openviking, version >= 0.3.x)
286
+
287
+ The ov-install context-engine deployment writes files to `~/.openclaw/extensions/openviking/`. After installing via npm, OpenClaw may still load from the old directory. Clean it up:
288
+
289
+ ```bash
290
+ # Remove ov-install deployed files
291
+ rm -rf ~/.openclaw/extensions/openviking/
292
+
293
+ # Install via the OpenClaw plugin manager
294
+ openclaw plugins install clawhub:@openviking/openclaw-plugin
295
+
296
+ # Reconfigure (your existing config in openclaw.json is preserved)
297
+ openclaw openviking setup --reconfigure
298
+ openclaw gateway restart
299
+ openclaw openviking status --json
300
+ ```
301
+
302
+ Your existing config fields such as `baseUrl`, `apiKey`, `peer_role`, and `peer_prefix` are preserved.
303
+
304
+ The plugin configuration lives under `plugins.entries.openviking.config`.
305
+
306
+ Get the current full plugin configuration:
307
+
308
+ ```bash
309
+ openclaw config get plugins.entries.openviking.config
310
+ ```
311
+
312
+ ### Configuration Parameters
313
+
314
+ The plugin connects to an existing remote OpenViking server.
315
+
316
+ | Parameter | Default | Meaning |
317
+ | --- | --- | --- |
318
+ | `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |
319
+ | `apiKey` | empty | Optional OpenViking API key |
320
+ | `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`; session messages use body `peer_id`, while data-plane recall/search uses `X-OpenViking-Actor-Peer` |
321
+ | `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant` |
322
+
323
+ Common settings:
324
+
325
+ ```bash
326
+ openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
327
+ openclaw config set plugins.entries.openviking.config.apiKey your-api-key
328
+ openclaw config set plugins.entries.openviking.config.peer_role assistant
329
+ openclaw config set plugins.entries.openviking.config.peer_prefix your-prefix
330
+ ```
331
+
332
+ ## Start
333
+
334
+ After installation (if you skipped reconfigure above):
335
+
336
+ ```bash
337
+ openclaw gateway restart
338
+ openclaw openviking status --json
339
+ ```
340
+
341
+ ### Old Plugin ID (memory-openviking, version < 0.3.x)
342
+
343
+ The old memory plugin used a different plugin ID and slot:
344
+
345
+ ```bash
346
+ # Uninstall old plugin
347
+ openclaw plugins uninstall memory-openviking 2>/dev/null || true
348
+
349
+ # Clean up old slot and files
350
+ openclaw config set plugins.slots.memory none
351
+ rm -rf ~/.openclaw/extensions/memory-openviking/
352
+
353
+ # Install new plugin
354
+ openclaw plugins install clawhub:@openviking/openclaw-plugin
355
+ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
356
+ openclaw gateway restart
357
+ openclaw openviking status --json
358
+ ```
359
+
360
+ Or use the cleanup script:
361
+
362
+ ```bash
363
+ bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
364
+ ```
365
+
366
+ See also: [INSTALL-ZH.md](./INSTALL-ZH.md), [INSTALL-AGENT.md](./INSTALL-AGENT.md), and [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md).