install-openviking-memory

OpenViking Memory のインストール — エージェントのインストールとリファレンススキル

OpenClaw 用の OpenViking メモリプラグインをインストールして設定します。 ユーザーはターミナルの使い方を知りません。自然な会話を通じていくつかの値を確認し、シェルツールを使ってすべてのコマンドをあなた自身で実行します。

開始する前に、このドキュメント全体を読んでください。すべての手順を順番に実行してください。手順を省略してはいけません。

このスキルは 2 つのパートに分かれています。

• パート 1（STEP 0–10）：自然言語によるインストール手順。 初回インストールまたは再設定時に使用します。
• パート 2：リファレンス。 ツール、設定スキーマ、マルチテナント、マルチインスタンス、日常運用、アンインストール、エラーからの復旧。必要に応じて参照してください。

サーバーの範囲。 このスキルでは 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) OpenViking の長期メモリを設定します。設定が完了すると、会話の重要な情報を自動的に記憶し、次回の会話でも思い出せるようになります。

必要な情報は 3 つです。不明な場合は管理者に確認してください。

1. OpenViking サーバーの URL — 例：https://ov.example.com または http://192.168.1.100:1933。ローカルサーバーの場合は「local」と入力してください。
2. API Key — 認証に使用します。サーバーで認証が有効になっていない場合は「none」と入力してください。
3. メモリの範囲（任意） — すべての会話で共有する user メモリ（デフォルト）、または peers/<assistant_id>／peers/<sender_id> の下に分けて保存するピアメモリ。

サーバーの 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) API Key とは何ですか？サーバーで認証が有効になっていない場合は「none」と入力してください。

• 「no」／「none」／「没有」／「空」／空欄 → API_KEY=""（後でフラグを省略します）。
• それ以外の場合は、そのまま保存します。

4c. PEER_ROLE（任意）

(CN) 记忆要存在哪一层？默认共享在 viking://user/<user_id>/memories（none）。也可以按 OpenClaw 助手存到 .../peers/<assistant_id>/memories（assistant），或按发送者存到 .../peers/<sender_id>/memories（sender）。 (EN) 記憶をどこに保存しますか？デフォルトでは viking://user/<user_id>/memories（none）に共有されます。代わりに、OpenClaw アシスタントごとに .../peers/<assistant_id>/memories（assistant）へ、または送信者ごとに .../peers/<sender_id>/memories（sender）へ保存できます。

デフォルトは none です。別の値を黙って選択しないでください。3 つの選択肢は保存先の構成が異なり、後から変更しにくいためです。

値	具体的な構成	選択する場合
none（デフォルト）	viking://user/<user_id>/memories/... に共有メモリを保存します。具体的な peers/<peer_id>/memories サブツリーは使用しません。	一般的なケースです。この OpenViking ユーザーのすべての会話で、ユーザーレベルのメモリを共有します。
assistant	OpenClaw で解決されたエージェント ID（フォールバックは main。任意のプレフィックスに対応）をキーとして、アシスタントに紐づくピアメモリを viking://user/<user_id>/peers/<assistant_id>/memories/... に保存します。	OpenViking ユーザーが人間の場合：1 人の人間が複数のアシスタントを使い、それぞれのピアメモリを分離したい場合です。例：Alice の main と research アシスタントは、それぞれ .../peers/main/... と .../peers/research/... を使用します。
sender	OpenClaw から渡される送信者 ID をキーとして、送信者に紐づくピアメモリを viking://user/<user_id>/peers/<sender_id>/memories/... に保存します。	OpenViking ユーザーがエージェントの場合：1 つのエージェントが複数の人間と会話し、それぞれのピアメモリを分離したい場合です。例：support-agent は customer-42 と customer-99 を別々のピアサブツリーに保存します。

person は sender の旧式の別名です。既存の設定またはユーザーが明示的に入力した値としては受け付けますが、新しいセットアップ値としては sender に正規化して書き込んでください。

OpenViking は、すべてのユーザーについて管理対象の peers/ コンテナーを初期化します。none にするとそのコンテナーがなくなる、とユーザーに伝えないでください。none では具体的なピアメモリのサブツリーを使用しないだけです。assistant または sender の場合、アクター・ピアの想起には共有ユーザーメモリと現在のピアメモリが含まれ、他のピアのサブツリーは非表示になります。この設定を変更しても、既存のメモリは移動しません。

• 空欄／「default」／「默认」／「共用」→ 未設定のままにします（プラグインのデフォルトは none）。
• それ以外は --peer-role none|assistant|sender を渡します。明示された旧式の値 person は sender として扱います。それ以外の値の場合は、もう一度確認します。

4d. PEER_PREFIX（任意、PEER_ROLE=assistant の場合のみ）

(CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、_、-。 (EN) このエージェントにメモリのプレフィックスを設定しますか？空欄にするとデフォルトを使います。使用できるのは英字、数字、_、- のみです。

• PEER_ROLE=assistant の場合にのみ意味があります。それ以外の場合は質問を省略します。
• 空欄／「default」／「默认」→ 未設定のままにします（プラグインのデフォルトは ""）。
• それ以外の場合は /^[A-Za-z0-9_-]+$/ に照らして検証します。無効な場合は、もう一度確認します。

4e.（条件付き）マルチテナントのルートキーフィールド

STEP 7 でルートキーが検出された場合（Root API key detected. Missing: --account-id, --user-id）にのみ、これらを質問します。先に質問しないでください。

• ACCOUNT_ID
• USER_ID

これらの意味については、リファレンス：マルチテナントを参照してください。

---

STEP 5：接続前チェック（ユーザーには知らせずに実行）

ユーザーには簡潔に伝えます。

(CN) 我先测一下能不能连上服务…… (EN) サーバーに接続できるか確認します……

次を実行します。

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 サーバーをインストールしたり、操作したりしません。ユーザーのサーバーに接続できない場合は、状況を正直に伝え、次の2つの方法を案内します。

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

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

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

(EN) ❌ BASE_URL に接続できません。考えられる原因：

1. サーバーが起動していない — OpenViking の管理者にサーバーを起動するよう依頼してください。ご自身でサーバーを管理している場合は、OpenViking の公式ドキュメント（https://github.com/volcengine/OpenViking）に従ってサーバーを起動してください。このスキルはサーバーをインストールしたり、実行したりしません。
2. URL が間違っている — 正しい URL を教えてください。
3. ネットワークでブロックされている（ファイアウォール／VPN／プライベートネットワーク）— 接続を確認してください。

または、今すぐ設定を保存（--allow-offline）して、サーバーが起動したら自動的に有効にすることもできます。そうしますか？

ユーザーが URL を修正した場合 → STEP 4a に戻ります。
ユーザーが --allow-offline を希望した場合 → ALLOW_OFFLINE=true を記憶し、STEP 6 に進みます。
ユーザーが断念した場合、または修正できない場合 → ここで停止します。問題のある状態のまま続行しないでください。

---

STEP 6: プラグインをインストールする

プラグインは2つの方法でインストールできます。必ず最初に方法 A を試してください。 方法 B は、ClawHub を利用できない、レート制限がある、または認証によって匿名でのインストールがブロックされるために方法 A が失敗した場合に限り、代替として使用します。バージョンの競合、依存関係のエラー、その他レジストリ以外の問題が発生した場合は、黙って方法を切り替えず、停止してエラーをユーザーに表示してください。

方法 A — 優先：openclaw plugins install（ClawHub を使用）

ユーザーに次のように伝えます。

(CN) 现在开始装插件…… (EN) プラグインをインストールしています…

次を実行します。

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 を指定します。

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. 明示的な --allow-offline または --force-slot の同意が必要な場合は、ゼロ以外の終了コードを返します。

つまり、STEP 7 は実質的に ov-install によって完了します。ov-install が終了コード 0 で終了したら、STEP 9（ゲートウェイの再起動）とSTEP 10（検証）に進みます。

ov-install がゼロ以外の終了コードで終了した場合は、出力の最後の 30 行を取得してユーザーに表示し、停止します。むやみに再試行しないでください。

---

STEP 7：設定（パス A のみ — パス B ではこの処理は完了しています）

セットアップウィザードを非対話形式で実行します。収集した値からフラグを組み立てます。

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 を指定します。assistant のピアプレフィックスには --peer-prefix を使います。以前の ID 形式のセットアップフラグはサポートされなくなりました。
• STEP 7 のルートキー検出後に限り、--account-id / --user-id を指定します（下記を参照）。
• 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" が含まれる	ルートキーのパス — 下記を参照してください。
success: false かつ認証失敗の詳細の後に error に "Invalid API key" が含まれる、または keyProbe.keyType: "unknown" である	API キーが間違っています。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?

ユーザーが同意した場合は、同じセットアップコマンドの末尾に --force-slot を追加して再実行します。同意しない場合は、設定は保存されたもののスロットは変更されていないことを伝え、ここで終了します。

ルートキーのパス

エラーメッセージは次のようになります。

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.

値を受け取ったら、セットアップコマンドの末尾に --account-id と --user-id を追加して再実行します。

---

STEP 8：予約済み（STEP 7 内または ov-install で実行済み）

セットアップウィザードでは、すでに plugins.entries.openviking.config.* が書き込まれ、（成功した場合は）plugins.slots.contextEngine = "openviking" が設定されています。独立した STEP 8 はありません。STEP 9 に進んでください。

---

STEP 9：ゲートウェイを再起動する

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 を省略していた場合は、今すぐ置き換えるかユーザーに確認し、STEP 7 を --force-slot 付きで再実行します。それ以外の場合は、ゲートウェイの再起動に問題があります。STEP 9 に戻ります。
• configured: true だが health.ok: false → サーバーに接続できなくなっています。ユーザーに伝えてください。サーバーが復旧すれば、設定は機能し始めます。
• configured: false → セットアップが実際には保存されていません。ステータス JSON 全体をユーザーに表示して終了します。

成功メッセージ

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

工作方式：

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

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

(EN) 🎉 すべて完了しました！OpenViking の長期記憶が接続されました。

仕組み：

• 毎ターン：会話が OpenViking のセッションに自動で追加されます。自動抽出は、しきい値に達したときのコミットまたは /compact によって行われます。
• 明示的に記憶を依頼した場合：長期的な事実を記憶、保存するよう依頼すると、memory_store を使ってすぐに記憶パイプラインへコミットできます。
• /compact の実行時：コミット待ちのセッションメッセージが、OpenViking サーバー上で長期記憶に抽出されます。
• 今後のセッション：返信の前に、関連する記憶が自動で取得され、コンテキストに追加されます。

確認してみますか？「私のメールアドレスは [email protected] だと覚えて」と伝えてください。memory_store を使ってすぐにコミットできます。または、記憶に値する事実をいくつか話してから /compact を実行してください。その後、新しいチャットを始めて「私のメールアドレスは？」と聞けば、思い出せるはずです。

---

パート 2 — リファレンス

仕組み

コンテキストエンジンのパイプラインは、明確に分かれた3つの段階と、明示的な書き込み経路で構成されています。特に、メモリがいつ検索可能な長期メモリとしてOpenVikingサーバーに保存されるかをユーザーに説明する際は、それぞれを混同しないでください。

• アーカイブ／キャプチャ（コンテキストエンジンのafterTurn）：ユーザーのターンの終了時に、プラグインはPOST /api/v1/sessions/.../messagesを介してユーザー／アシスタントのメッセージをOpenVikingセッションに追加します。pending_tokensがcommitTokenThresholdを超えない限り、これはセッションのキャプチャのみです。しきい値を下回っている間は、メモリ抽出は実行されません。サーバー上のセッションメッセージ数は増えますが、viking://user/.../memories/の下に新しいファイルは作成されません。
• メモリ抽出（しきい値到達時のコミットまたは/compact）：メモリ抽出はセッションのコミット後に実行されます。コミットは、afterTurnがcommitTokenThresholdを超えたときに非同期で、ユーザーがOpenClawの/compactコマンドを実行したときに同期で、またはmemory_storeによって明示的に実行できます。サーバー側の抽出パイプラインはアーカイブされたセッションを読み取り、新しいメモリを書き込みます。
  • captureMode: "semantic"（デフォルト）：サーバーの抽出パイプラインが、条件を満たすすべてのテキストをフィルタリングします。
  • captureMode: "keyword"：トリガーワード（例：「覚えておいて」「好み」）に一致するテキストのみが対象になります。
• 自動リコール（コンテキストエンジンのassemble()）：プロンプトのコンテキストを組み立てる前に、プラグインはOpenVikingに関連するメモリを問い合わせ、それらをコンテキストに挿入します。まだ抽出されたメモリがなくてもリコールは機能しますが、結果は何も返されません。

テスト時の実際的な注意点：短い事実を書き留めた後、しきい値に達するコミットや/compact、memory_storeを実行せずにすぐリコールしようとすると、プラグインはそれを長期メモリとしてではなく、直近のセッションコンテキストとしてのみ取得する場合があります。セッションをまたいだ長期メモリを確実に検証するには、/compactを実行するか、テスト対象の事実にmemory_storeを使用してください。

明示的な長期メモリの書き込み

自動キャプチャはベストエフォートであり、コミットに依存します。ユーザーが重要な長期的事実、好み、プロジェクト、または決定を覚えておく、保存する、記録するよう明示的に求めた場合、エージェントは通常の自動キャプチャを待たずにmemory_storeを呼び出してください。

永続メモリへの保存要求に対応するための、統合側の確実な経路としてmemory_storeを使用します。

• 指定されたテキストをOpenVikingセッションに書き込み、commit(wait=true)を呼び出します。
• 自動キャプチャを補完するものであり、通常のセッションキャプチャに取って代わるものではありません。
• コミット後にメモリが0件抽出された場合でも、明示的な経路としての役割は果たしています。これはサーバー側の抽出、モデル、設定の問題として扱い、OpenVikingのログを確認してください。

利用可能なツール

インストール後にエージェントが呼び出せるプラグインツールは次のとおりです。

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	はい	1 つのキーワードまたは短い語句です。具体的な名前、日付、コマンド、パス、または特徴的な名詞を優先してください。
archiveId	いいえ	archive_002 などの任意のアーカイブ ID です。

[Session History Summary] の情報が大まかすぎる場合に使用します。詳細を確認できないと結論づける前に、少なくとも 2 種類のキーワードで検索してください。

ov_archive_expand — アーカイブを展開

パラメーター	必須	説明
archiveId	はい	[Archive Index] にあるアーカイブ ID。例：archive_002。

add_resource — リソースをインポート

エージェントから見える 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	いいえ	処理が完了するまで待機します。

add_skill — エージェントスキルをインポート

パラメーター	必須	説明
source	いいえ	ローカルの SKILL.md パスまたはスキルディレクトリです。source または data のいずれか一方が必須です。
data	いいえ	SKILL.md の生のコンテンツまたは MCP ツールの dict です。source または data のいずれか一方が必須です。
wait	いいえ	処理が完了するまで待機します。

エージェントスキルのベストプラクティス：フロントマターに、明確な name、トリガーを意識した description、役立つ tags、明示的なスコープの境界、具体的な実行手順が含まれていることを確認してください。スキルのコンテンツにシークレットを含めないでください。

ov_search — リソースとスキルを検索

パラメーター	必須	説明
query	はい	検索クエリです。
uri	いいえ	任意の検索 URI です。デフォルトではリソースとエージェントスキルが対象です。
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	""	assistant の 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 インスタンスを実行している場合（例：複数のエージェントを並行してテストする場合）、各インスタンスには独自の状態ディレクトリがあります。

デフォルト以外のインスタンスを指定するには：

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

状態ディレクトリがデフォルト以外の場合、ov-install は補助環境変数ファイルを書き込みます。

• Unix：export OPENCLAW_STATE_DIR='...' を含む ~/.openclaw/openviking.env
• 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 のスロットリング	バックアップの Path B（ov-install）に切り替えます。
plugins install の not logged in / please log in	匿名ユーザーが制限に達しました	バックアップの Path 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／埋め込み設定を確認するよう依頼します。
/health は動作するが、プラグインのリクエストで 401 / 403 が発生する	サーバーが API エンドポイントで認証を要求しています	正しい --api-key を指定して STEP 7 を再実行します。
Path A の後も openclaw plugins list にプラグインが表示されない	インストールが完了していません	Path A を再実行します。Path B を使うのは、失敗の原因がレジストリまたはレート制限に関係する場合のみです。

重要なルール

1. **ユーザーにコマンドの実行を依頼しないでください。**すべてシェルツール経由で実行してください。
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 形式のセットアップフラグは、現在のスキーマではサポートされていません。
7. Windows では PowerShell に対応する方法を使用してください。nohup、&、mkdir -p、source などに頼らないでください。
8. **ClawHub／レート制限／レジストリの利用可否に関する問題が発生した場合に限り、Path B（ov-install）に切り替えてください。**バージョンの競合やパッケージの検証エラーを回避するために使用してはいけません。
9. **OpenViking サーバーをインストールまたは操作しないでください。**このスキルはサーバーがすでに稼働していることを前提としています。稼働していない場合は、管理者に問い合わせるか、OpenViking のドキュメントに従うようユーザーに伝えてください。
10. **ユーザーに見える文章は、簡潔で親しみやすいものにしてください。**問題が実際に発生した場合にのみ、技術的な詳細を説明してください。
11. **clawhub install openviking は使用しないでください。**これは別のもの（プラグインではなく AgentSkill）をインストールします。