ov-memory-doctor

OpenViking Memory Doctor

OpenViking メモリプラグインのクライアント側トラブルシューティングです。プラグインには 3 つの構成要素があり、それぞれ独自の形で問題をひそかに引き起こします。

• インストール — マーケットプレイスへの登録、プラグインの有効化、9 つのフック、stdio MCP プロキシです。ここに問題があると、フックは実行されず、どこにもログが記録されません。
• 設定 — ~/.openviking/ovcli.conf、~/.openviking/ov.conf、OPENVIKING_* 環境変数です。環境変数 → ovcli.conf → ov.conf → デフォルトの順に解決されます。ファイルが不正な形式だと「設定なし」として読み込まれ、プラグインがひそかに無効になります。不要な環境変数があると、ファイルの設定がひそかに上書きされます。
• 接続 — セルフホストサーバーでは、無効なキーを指定しても /health は 200 を返すため、ステータスラインが緑色でも、実際のリクエストはすべて 401 になります。OpenViking Cloud ではゲートウェイが /health と /ready も認証するため、キーなしでは同じプローブが 401 を返し、URL については何も分かりません。

解決後の URL がループバックの場合、サーバーはこのマシン上で動作しているため、doctor は サーバーのヘルス セクションを追加します。このセクションでは、ポートで何かがリッスンしているか、サーバーの起動を妨げる ov.conf 内のプラグイン専用キー（claude_code、codex、cursor、trae、trae_cn、zcode、opencode、dsh、pi のように、ハーネス名を付けたトップレベルブロック、および server.url）、GET /ready による各サブシステム（agfs、vectordb、API キー、埋め込み、ollama）のサーバー自身の判定結果を確認します。リモートサーバーでは /ready のみをプローブします。サーバー側のその他すべての項目（設定の検証、実際の埋め込みプローブ、ネイティブエンジン、ディスク）は、サーバーの Python 環境で実行する openviking-server doctor で確認します。

ステップ 1 — doctor を実行する

node ${CLAUDE_PLUGIN_ROOT}/scripts/ov-memory-doctor.mjs

オプション：--json（機械可読形式）、--offline（ネットワークプローブをスキップ）、--timeout <ms>（プローブごとのタイムアウト。デフォルトは 5000）、--no-color。

レポートは 6 つのセクション（環境、プラグインのインストール、設定、接続、サーバーのヘルス、最近のアクティビティ）と、修正方法を示す ✗／⚠ の一覧を含む概要で構成されます。 対処する前にレポート全体を読んでください。ひとつの根本原因が複数のセクションに現れることがよくあります（たとえば、無効なキー → 「API キーが拒否されました」＋「system/status → 401」＋ turns_failed > 0）。

「このスクリプトは登録済みのインストールから実行されていません」とレポートに表示された場合は、出力されたパスから再実行してください。Claude Code はそのコピーからフックを実行します。

API キーが全桁表示されることはありません。3 セグメントのキーは account=<a> user=<u> secret=abcd…wxyz として表示されます（最初の 2 セグメントは base64url 形式の ID なので、デコードして、キーがどのアカウント／ユーザーのものか確認できるようにしています）。それ以外の形式は abcd…wxyz (N chars, unsupported format) として表示されます。ユーザーに見せる内容でも、この形式を維持してください。

ステップ 2 — 検出結果を原因に対応付ける

上から順に確認し、最初の ✗ を修正したら、次に進む前に再実行してください。

Doctor の診断結果	意味	対処方法
plugin disabled — every hook exits immediately	解析可能な設定がない、OPENVIKING_MEMORY_ENABLED=0、または ov.conf の claude_code.enabled: false	表示された原因を修正します。新しいマシンの場合は、url と api_key を含む ~/.openviking/ovcli.conf を作成します（chmod 600）。
ovcli.conf cannot be parsed	末尾のコンマまたはコメントがあり、プラグインはファイルを存在しないものとして扱います	JSON を修正します。「インストール済みなのに何も起きない」場合の最も一般的な原因です。
not registered in installed_plugins.json / claude plugin list does not show …	プラグインがインストールされていないか、古い ID でインストールされています	1 行のインストーラーを再実行します（curl -fsSL https://openviking.ai/install | bash -s -- --harness claude）。
plugin is disabled in ~/.claude/settings.json	インストールされていますが、enabledPlugins が false または未設定です	claude plugin enable openviking-memory@openviking を実行し、Claude Code を再起動します。
marketplace 'openviking' … missing directory / file として登録されている	チェックアウト／アーカイブが移動したか、ファイル形式のマーケットプレイスです（marketplace update が EISDIR で失敗します）	claude plugin marketplace remove openviking を実行してから、インストーラーを再実行します。
no skills/ directory in this plugin copy / 登録バージョンがリポジトリより古い	バージョンごとに保存されるキャッシュが古くなっています。バージョン文字列が変わっていない場合、claude plugin update は何も行いません	claude plugin marketplace update openviking && claude plugin uninstall openviking-memory@openviking && claude plugin install openviking-memory@openviking を実行します。
legacy openviking hooks … settings.json / 余分なプラグイン ID / ユーザースコープの MCP openviking	2.0 より前のインストールの残骸です。各フックが 2 回実行され、MCP サーバーが 2 回登録されています	~/.claude/settings.json の .hooks から openviking の項目を削除し（バックアップを取ってください）、claude plugin uninstall <stale id> と claude mcp remove openviking -s user を実行します。
node is not on PATH / node < 18	フックと .mcp.json は node というコマンドをそのまま実行します。GUI／IDE からの起動では nvm／volta のシムが利用できないことがよくあります	起動環境の PATH に node を追加するか、~/.claude/settings.json の env ブロックで PATH を設定します。
server unreachable（接続拒否／DNS／タイムアウト／TLS）	url／ポートの誤り、サーバー停止、DNS／VPN、プライベート CA	curl -sS <url>/health の結果と比較します。curl が成功して Doctor が失敗する場合は、プロキシまたは CA の問題です（ステップ 3 を参照）。
base URL ends with /api/v1 または /mcp、スキームがない、GET /health → 404	url の形式が正しくありません（パスはそのまま連結されます）。Cloud では /openviking のプレフィックスが必要です	url を API ルートに修正します。
/health is authenticated at this deployment（情報）/ api key rejected on /health → 401	OpenViking Cloud はゲートウェイで /health と /ready を保護しているため、キーなしのプローブは 401 になり、url について何も分かりません	情報行は修正不要です。レポートでは代わりにキーを使って /health を確認します。✗ はゲートウェイがこのキーを拒否したことを示します。このデプロイメント用に発行されたキーを使ってください（Cloud のキーは Volcengine コンソールから取得します）。
api key rejected（/health は 200 だが ID がない）、その後 system/status → 401 Invalid API Key	キーが無効、失効済み、または別のデプロイメント用です。存在しないアカウントの 3 セグメントキーも同じように見えます。	キーを再発行してもらいます。環境変数が ovcli.conf の値を上書きしていないことを確認します（Configuration セクションの「← env」）。
using the ROOT api key / 403 ROOT API keys cannot access tenant-scoped data APIs	api_key が ov.conf の server.root_api_key にフォールバックしたか、ユーザーがルートキーを貼り付けました	ルートキーを使ってユーザーキーを作成し（POST /api/v1/admin/accounts/<account>/users）、ovcli.conf に設定します。
server is in trusted mode and needs account + user / 400 Trusted mode requests must include…	サーバーの ID はヘッダーから取得されます	ovcli.conf で account と user を設定します。
configured account/user differ from the key's identity	api_key モードではサーバーは X-OpenViking-Account/User を無視し、データはキーの ID に紐づけて保存されます	それらを削除するか、その ID 用のキーを使います。「アカウントを変更したのに何も変わらない」場合の原因です。
request/capture timeout exceeds the hook budget	リクエストが完了する前に Claude Code がフックを終了します	OPENVIKING_TIMEOUT_MS／OPENVIKING_CAPTURE_TIMEOUT_MS の値を下げます。
/health は正常なのに POST /mcp tools/list → 404/406/502/504	リバースプロキシが /mcp を転送していない、Accept を書き換えている、または SSE をバッファリングしています	プロキシを修正します（proxy_buffering off、/mcp を転送、Authorization を渡す）。
proxy variables set があり、curl は成功するのに Doctor／フックが失敗する	Node の fetch は HTTP(S)_PROXY を無視します。プラグインにはプロキシ／CA の処理が含まれていません	Claude Code を起動する環境の env ブロック（~/.claude/settings.json）で NODE_USE_ENV_PROXY=1 または NODE_EXTRA_CA_CERTS=<ca.pem> を設定します。
last auto-recall … reason=offline/bypass/disabled/short_query	フックは実行されましたが、挿入しないと判断しました	offline → 接続、bypass → OPENVIKING_BYPASS_SESSION*、short_query → プロンプトが minQueryLength より短い場合です。検索が実際に実行されたことを示すのは no_results／filtered_out のみです。検索呼び出しで 401 が発生した場合も no_results と表示されることに注意してください。
turns_failed > 0 / capture payload(s) waiting	書き込みが拒否された（401／403／404 はキューに入れず破棄されます）か、サーバーが停止していました（キューに入り、次の SessionStart で再送されます）	認証情報／接続を修正します。OPENVIKING_WRITE_PATH_ASYNC=0 にすると、エラーが stderr に表示されます。
MCP proxy last started against <other url>	プロキシは長時間実行されるプロセスです。url を変更しても、再起動するまで反映されません	Claude Code を再起動するか、/mcp → reconnect を実行します。ovcli.conf がディスク上で変更されていれば、401 の後にキーのローテーションが自動的に復旧します。
recall is pinned to the legacy /search/recall endpoint	"mode" に言及する 4xx が 1 回発生すると、recall が 6 時間固定されます	rm ~/.openviking/state/context-face.json を実行します。
no hook log … debug is on but no hook has run	フックがまったく起動されていません	サーバーではなく、登録／有効化／node の問題です。
ov.conf has a top-level '<harness>' block / server.url is rejected	サーバー自体の設定にプラグイン専用のキーがあります。任意のハーネス名（claude_code、codex、cursor、trae、trae_cn、zcode、opencode、dsh、pi）を名前に持つトップレベルブロックと server.url が含まれていると、次回の再起動時にサーバーは起動を拒否します（Unknown config field／Extra inputs are not permitted）	それらを ovcli.conf（plugin.<harness>、url）に移し、ov.conf から削除します。この ov.conf でサーバーを起動しない場合に限り、無視してかまいません。
nothing listens on port … — the server is not running	サーバーが停止しているか、起動していません。.openviking.lock が存在していても、サーバーが実行中とは限りません	ターミナルで openviking-server を実行して起動します（初回は openviking-server init を実行します）。起動時の出力を確認してください。ユーザーが実行しているサーバーを再起動する前に、許可を求めてください。
/ready: embedding → error …	実行中のサーバーが埋め込みプロバイダーを呼び出せません。recall 検索では何も見つからず、コミットでは何も抽出されません	ov.conf の embedding.*（api_key／api_base／model）を修正して再起動します。openviking-server doctor でプロバイダーの応答を確認できます。
/ready: vectordb → … / /ready: agfs → …	ストレージの障害です。ディスク容量不足、1 つのワークスペースで 2 台のサーバーを実行、インデックスの破損などが考えられます	サーバーログを確認し、重複するサーバーを停止して、ディスクの空き容量を確保します。
server is still initializing (503 /ready)	初回起動時にローカルの埋め込みモデルをダウンロードしているか、初期化に時間がかかっています	待ってから再実行します。完了しない場合はサーバーログを確認します。
docker container is up but has no ov.conf	公式イメージが設定のマウントなしで起動しています（すべてのリクエストが 503 になります）	~/.openviking を /app/.openviking にマウントするか、docker exec -it openviking openviking-server init を実行します。
より多くの症状、正確なエラー文字列、ログのステージ名については、reference.md を参照してください。

ステップ 3 — 対象を絞った確認（報告内容だけでは結論が出ない場合に限る）

フックが実行されていることを確認します。OPENVIKING_DEBUG=1 は Claude Code 自身のプロセスに渡す必要があります。シェルでのエクスポートでは渡りませんが、~/.claude/settings.json の env ブロックなら渡せます。その後、新しいセッションでプロンプトを 1 つ送信し、~/.openviking/logs/cc-hooks.log（JSONL。"error" と "hook":"mcp-proxy","stage":"start" を grep します）を確認します。subagent-stop transcript_read ENOENT の行は無害なノイズです。

キーと ID を手動で確認します（Bearer は大文字と小文字を区別し、スペースは正確に 1 つです）。

URL=<url>; KEY=<key>
curl -sS "$URL/health"                                  # reachability, version, auth_mode (401 on Cloud: the gateway gates /health)
curl -sS -H "Authorization: Bearer $KEY" "$URL/health"  # 200 without account_id/user_id/role ⇒ key invalid
curl -sS -w '\n%{http_code}\n' -H "Authorization: Bearer $KEY" "$URL/api/v1/system/status"  # real 401/403

/mcp を直接確認します（ステートレスのため、initialize は不要です）。

curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$URL/mcp" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $KEY" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude Code の MCP 接続設定を確認します。claude mcp list（時間がかかります。30～60 秒）に plugin:openviking-memory:openviking: node <installPath>/servers/mcp-proxy.mjs - ✔ Connected と表示される必要があります。claude mcp get 'plugin:openviking-memory:openviking' には、名前全体を引用符で囲んで指定する必要があります。セッション内で /mcp を実行すると、プロキシが再接続されます。

キャプチャが保存されたことを確認します。~/.openviking/state/last-capture.json から ov_session_id を取得し、GET $URL/api/v1/sessions/<id>（または ov session get <id>）を実行します。total_message_count はキャプチャされたターン数以上である必要があります。commit_count > 0 であれば、抽出が実行されています。

CLI で別の方法から確認します。ov health と ov config validate は、同じ ~/.openviking/ovcli.conf を読み取ります（キーに対応するアカウント／ユーザー／ロールが表示されます）。ov config list では、ov config switch で別のプロファイルに切り替わっているかどうかを確認できます。これもプラグインの接続先を変更します。

サーバー側（サーバーがこのマシン上で実行されている場合に限り有効です）：

curl -sS "$URL/ready"                       # agfs / vectordb / api_key_manager / embedding (live probe, ≤10s) / ollama
openviking-server doctor                    # in the server's own environment: config, native engine, embedding probe, VLM key, disk
lsof -nP -iTCP:1933 -sTCP:LISTEN            # who owns the port
docker logs --tail 100 openviking           # container deployments

log.output のデフォルトは stdout です。そのため、サーバーログは、サーバーを実行しているターミナル／tmux ペイン、nohup ファイル、journalctl -u openviking、または docker logs で確認できます。"file" の場合は <storage.workspace>/log/openviking.log に出力されます。起動時に終了するサーバーは、その場で理由を出力します。原因を確認するには、openviking-server をフォアグラウンドで実行するのが最も手早い方法です。これはユーザーのプロセスです。停止または再起動する前に、必ずユーザーに確認してください。

修正

• ~/.openviking/ovcli.conf は、ユーザーの同意を得てから編集してください。変更内容を示し、不明なキーは残し、モードを 0600 に保ち、キーを表示しないでください。
• マシン全体に適用するオーバーライドには、~/.claude/settings.json の env ブロックで環境変数を設定する方法を優先してください。シェル rc でのエクスポートは、そのシェルから起動したセッションにしか渡らず、あらゆる場所でファイルの設定を暗黙に上書きします。
• url の変更後、プラグインのインストール後または更新後は、Claude Code を再起動してください。フックは呼び出しごとに設定を読み直しますが、MCP プロキシは読み直しません。
• 更新方法：GitHub からインストールした場合 → claude plugin marketplace update openviking && claude plugin update openviking-memory@openviking； Claude Code 2.1.224+ の TOS インストール（url マーケットプレイス）の場合は、バックグラウンドで自動更新されるか、必要に応じて claude plugin update openviking-memory@openviking を実行します； 古い TOS、アーカイブ、開発用チェックアウトからインストールした場合 → インストーラーを再実行します。
• doctor を再実行し、次のプロンプトで <openviking-context> ブロックが表示されることを確認して、修正を検証します。

ドキュメント

• ソースコードとイシュー：https://github.com/volcengine/OpenViking — プラグインのコードは examples/ に、共通インストーラーは examples/memory-plugin-shared/ にあります。
• ドキュメントのインデックス（LLM 向け）：https://docs.openviking.ai/llms.txt；その下にあるハーネス連携ページで、インストール方法、設定キー、既知の制限事項を確認できます。
• https://api.vikingdb.cn-beijing.volces.com/openviking は、Volcengine がホストする OpenViking Service（OpenViking Cloud）です。パスプレフィックスはベース URL の一部です。Authorization: Bearer のみを受け付け、キーはセルフホストの管理者ではなく Volcengine コンソールから発行されます。

ルール

• API キー全体や ovcli.conf の生の内容を決して表示しないでください。表示してよいのは、doctor がマスキングした形式までです。
• scripts/setup.mjs の実行には TTY が必要です。また、古いプラグインバージョンでは ovcli.conf がすでに存在している必要があります。新しいマシンではファイルを直接書き込むか、インストーラーを再実行してください。
• claude plugin list を grep -q にパイプしないでください。先に出力を取得してください。pipefail のもとで早期終了すると、「未インストール」と判定されます。
• /health が 200 を返すことが示すのは、到達可能であることだけです。認証が確認できるのは、キーを使った場合の ID フィールド、または /api/v1/system/status です。
• ov doctor は openviking-server doctor です。サーバー自身の設定と、サーバーの Python 環境にあるプロバイダーを検証し、実際に埋め込み呼び出しを行います。このプラグインについては何も示しません。最初に実行するのではなく、プロバイダーレベルのエラーが発生した場合に実行してください。
• doctor は読み取りのみを行います。ユーザーのサーバーを停止、再起動、または kill したり、許可なく ov.conf を編集したりしないでください。
• 古いプロキシバージョンでは「ov serve が実行中であることを確認してください」と表示されます。そのようなコマンドはありません。サーバーは openviking-server で起動します。
• OPENVIKING_MEMORY_ENABLED=0 はフックを無効にしますが、MCP ツールは無効にしません。OPENVIKING_MCP_URL はこのプラグインに影響しません。