huawei-cloud-openviking-agent-integration

Huawei Cloud Agent Integration（OpenViking 長期メモリ）

bwrap サンドボックス（/root/job-envs/sandboxes/）で実行されるコーディングエージェントに、OpenViking の長期メモリを統合／解除します。各エージェントのネイティブな仕組み（MCP、HTTP メモリプロバイダー、TS 拡張フック、settings.json）を使用するため、エージェントのアップグレード後も統合が維持されます。書き込みはテンプレートレベルで永続化されます。設定は /root/template/<agent>/start.sh に挿入されるため、サンドボックスを stop + start しても統合は維持されます。

対応エージェント

エージェント	仕組み
CodeArts CLI	@openviking/opencode-plugin → .codeartsdoer/
OpenCode	@openviking/opencode-plugin（npm ミラー → GitHub フォールバック）
OpenClaw	clawhub:@openviking/openclaw-plugin + contextEngine スロット（session-memory フックを無効化し、memory_search を拒否）
Hermes	組み込みの memory.provider: openviking（HTTP REST、MCP なし）
WorkSwarm	デュアルチャネル：ネイティブプロバイダー + MCP（15 個のツール）+ code-mode パッチ
KimiCode	フック + MCP（セッションのライフサイクル）— config.toml [[hooks]] → ov-kimi-hook.sh + mcp.json 経由の MCP
DeepSeek Harness	@openviking/dsh-memory-plugin バンドル（必要に応じて GitHub から取得）
Prime Agent	@openviking/pi-coding-agent-extension（必要に応じて GitHub から取得）

エージェントごとの設定パスと詳細については、references/agent-configs.md を参照してください。

前提条件

• OpenViking サーバーが正常であること：curl -s http://127.0.0.1:1933/health → healthy。
• 対象のサンドボックスが /root/job-envs/sandboxes/ 配下に存在すること。
• ホストツール：curl、python3、bash。OpenCode／OpenClaw では npm、verify_mcp.sh では pip install --upgrade "mcp>=2.0" が必要です。
• Huawei Cloud IAM は不要です。ローカルの bwrap サンドボックスのみで動作します。

パラメーター

フラグ	必須	説明
--agent <name>	はい（--all を指定しない場合）	対象エージェント
--all	はい（--agent を指定しない場合）	8 個すべてのエージェントを操作します
--endpoint <url>	いいえ	OpenViking の URL（デフォルトは http://127.0.0.1:1933）
--api-key <key>	いいえ	認証モードのサーバー用です。チャットに出力しないでください。エージェント設定または verify_mcp.sh で使用する必要があります。使用されない --api-key は警告として報告されます。
--dry-run	いいえ	適用せずに変更内容を表示します
--yes / -y	いいえ	確認を省略します（自動化専用）
--json	いいえ	status.sh：機械可読形式の出力

主なコマンド

機能	コマンド
状態の確認	scripts/status.sh（--json / --agent <name>）
MCP の検証	scripts/verify_mcp.sh
統合	scripts/integrate.sh --agent <name> [--endpoint URL] [--dry-run] [--yes]（または --all）
解除	scripts/unbind.sh --agent <name> [--dry-run] [--yes]（または --all）

ワークフロー

SKILL_DIR=/root/.agents/skills/huawei-cloud-openviking-agent-integration
$SKILL_DIR/scripts/status.sh          # per-agent: template+live / template only / live only / none
$SKILL_DIR/scripts/verify_mcp.sh      # full MCP handshake (initialize → tools/list → health)
$SKILL_DIR/scripts/integrate.sh --agent <name> [--yes]
$SKILL_DIR/scripts/unbind.sh  --agent <name> [--yes]

1. まず状態を確認 — status.sh で確認するまでは、統合済みと決して断言しないでください（状態を捏造しないでください）。
2. MCP を検証 — 統合の前に verify_mcp.sh を実行してください。
3. 統合／解除 — いずれも明示的な confirm（または --yes）が必要です。--dry-run を使うと安全にプレビューできます。
4. 状態：template + live = 有効、template only = 再起動時に有効化、live only = 再起動時に失われます（ユーザーに警告してください）。

認証と安全性

• integrate.sh／unbind.sh には明示的な確認が必要です。エージェント設定を直接編集せず、スキルスクリプトを使用してください。
• 設定を変更するたびに .bak.<timestamp> が作成されます（5 個を保持）。
• --api-key の値を出力に含めてはいけません。

能力边界（できないこと）

このスキルで行うのは「OpenViking のメモリとコーディングエージェントの連携・解除・状態確認・検証」のみです。以下の操作は明示的に対象外です。該当する場合は、適切な方法に切り替えるか、明確なエラーを返してください。

• エージェントの設定ファイル、サンドボックス内の業務データ、ユーザーコードを直接読み書きしません。すべて scripts/integrate.sh / unbind.sh などのエントリーポイントを通じて実行します。
• ユーザーが自分でインストールしたサードパーティ製パッケージ、ディレクトリ、データを削除・変更しません。アンインストール時に削除するのは、OpenViking 自身の生成物（@openviking/* プラグイン、注入された設定セクション、OV 専用ディレクトリ）のみです。node_modules ディレクトリ全体を削除するなど、範囲外の操作は不具合であり、実行しません。
• サーバーに接続できない、またはヘルスチェックに失敗した場合は、成功と報告しません。integrate.sh、unbind.sh、verify_mcp.sh はいずれも最初にヘルスチェックを行い、失敗した場合は処理も失敗します（終了コードは 0 以外）。成功したように見せかけることは決してありません。
• --dry-run は変更内容をプレビューするだけで、永続ファイルには何も書き込みません。プレビュー後に実際の処理を行う場合も、確認が必要です。
• --api-key は、いずれかのエージェント設定または検証フローで実際に使用される必要があります。指定されても使用先がない場合、スクリプトは警告します（黙って無視することはありません）。
• 埋め込みモデルの切り替え、ベクトルデータベースの再構築、サーバー自体の設定変更は行いません。これらは huawei-cloud-openviking-embedding-switch などのスキルの対象です。
• 連携・解除の処理中に、OpenViking のアカウント、ユーザー、権限体系を作成・変更することはできません。
• 「確認 → 連携済み」とは断定しません。必ず status.sh の実測結果を基準とし、テンプレートから稼働中の状態を推測することは禁止されています。

参考資料

ドキュメント	読むタイミング
agent-configs.md	エージェントごとの設定パス／形式、MCP ツール、サーバー情報を確認するとき
notes.md	ガードレール、環境変数、サンドボックスの再起動、プラグインのソース、トラブルシューティング、新しいエージェントの追加について確認するとき