TrueNAS AIops

TrueNAS AIops

免責事項：コミュニティが保守するオープンソースプロジェクトです。iXsystems または TrueNAS プロジェクトとは提携、推奨、後援のいずれも受けていません。「TrueNAS」はその所有者の商標です。MIT ライセンスです。

TrueNAS SCALE のストレージ運用を AI で支援します。ガバナンスハーネスを内蔵しており、統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスクレベルを備えています。TrueNAS の両方の API、REST v2.0 と、TrueNAS 26 で置き換えられる JSON-RPC/WebSocket API に対応しています。

検証状況：実機の TrueNAS SCALE 25.04.2.1 に対し、両方のトランスポートで実地検証済みです。書き込み → 監査 → 取り消し → 復元確認の一連の動作も含みます。対応状況はエンドポイントごとに記載しており、未対応の項目も docs/VERIFICATION.md に記載しています。「検証済み」を「すべて検証済み」と解釈せず、こちらをご覧ください。

対応する TrueNAS バージョンと使用する API

truenas-aiops は TrueNAS の両方の APIに対応し、今後も利用できる API を選択します。

TrueNAS バージョン	REST API v2.0	WebSocket 上の JSON-RPC	このツールの動作
≤ 25.10.0	対応	—	REST
25.04 – 25.10.x	非推奨（呼び出しのたびにアプライアンスのアラートが発生します）	/api/current ですでに提供済み	WebSocket（自動）
26 以降	削除済み	必須	WebSocket

config.yaml でターゲットごとに transport: を設定します。

targets:
  - name: nas1
    host: nas1.example.com
    transport: auto        # default — probe /api/current, prefer WebSocket
    # transport: websocket # pin the API that survives TrueNAS 26
    # transport: rest      # pin REST while migrating

auto は、軽量な HTTP アップグレード（認証情報は消費しません）を使って /api/current を確認します。アプライアンスが対応していればこのツールはその API を使用し、そうでなければ REST にフォールバックします。REST は 25.10 以前でも引き続き正しく動作します。

iXsystems のドキュメントによると、TrueNAS 26 へのアップグレードで既存の API キーは無効になります。そのため、アップグレード後に新しいキーを発行する必要があると考えてください。こちらではこの動作を再現していません。これは検証済みのアップグレード結果ではなく、上流のリリースノートに基づく情報です。測定結果ではなく、注意事項として扱ってください。

truenas-aiops doctor は、接続で実際に使用されたトランスポートとサーバーのバージョンを確認します。また、REST の場合は、REST が対応済み、非推奨、または削除済みのいずれかを明確に表示します。バージョンを解析できない場合は UNKNOWN と報告し、根拠のない正常判定は行いません。

動作する機能

• CLI（truenas-aiops ...）：init、overview、system、pool list/get/status/scrub-status/capacity/scrub-start、dataset list/get/create、diagnose pool-health/alerts、snapshot list/create/delete、disk list/smart、alert list、service list/restart、replication list/cloudsync、secret set/list/rm/migrate/rotate-password、doctor、mcp。
• MCP サーバー（truenas-aiops mcp または truenas-aiops-mcp）：25 個のツール（読み取り 19 個、書き込み 6 個）。すべてに同梱の @governed_tool ハーネスが適用されています。
• 認証情報の暗号化：TrueNAS API キーは暗号化ストア ~/.truenas-aiops/secrets.enc（Fernet + scrypt）に保存され、ディスク上に平文で保存されることはありません。MCP／CI では TRUENAS_AIOPS_MASTER_PASSWORD から取得したマスターパスワードで、CLI では対話型プロンプトでロックを解除します。
• 可逆性：snapshot_create は、逆操作となる snapshot_delete の取り消し記述子を記録します。取り消し不能な snapshot_delete（リスクレベルは high）は、監査記録にスナップショットの実行前の状態を保存し、取り消し操作がないことを明示します。
• 安全性：破壊的な CLI 操作（snapshot delete、service restart）には二重確認が必要で、--dry-run に対応しています。

このツールが判断すること、判断しないこと

TrueNAS SCALE のストレージ操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続に使用するアカウントの権限によります。TrueNAS API キーの権限を制限したアカウントに設定すれば、書き込みは、実際に権限を管理する装置側で失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何も記録されずに実行されることがないということです。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.truenas-aiops/audit.db に監査行として記録され、元に戻せる書き込みについては、実行前の状態も取得し、逆操作を記録します。

各ツールは risk_level を宣言します。テストによって [READ]／[WRITE] のドキュメントタグとの一致が保たれ、説明用の段階として監査行にも記録されるため、レビュー担当者は高リスクの削除を示す行をひと目で確認できます。これはラベルであり、ゲートではありません。

小型モデル／ローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが代わりに適用するガードレール（そのため、プロンプトのトークン予算を使って繰り返し説明する必要はありません）と、残りの項目に使用できる、そのまま使えるシステムプロンプトを記載しています。

プレイブック：劣化したプールのトリアージ

truenas-aiops diagnose pool-health            # worst-first: bad state, error counters, capacity
# → e.g. CRITICAL tank "pool status is DEGRADED", and "read=4 checksum=2" on a vdev
truenas-aiops pool status tank                # inspect the topology / scan detail it cited
truenas-aiops pool scrub-start tank           # kick an integrity scrub (governed, medium risk)
truenas-aiops diagnose alerts                 # cross-check active alerts + any datasets near full

各検出項目には、問題を検知した測定値（ステータス文字列、エラー数、使用率）が記載されているため、なぜフラグが立ったのかを確認できます。そのうえで、対応に使う正確な読み取り／書き込みコマンドを示します。

機能マトリックス（25 個の MCP ツール）

カテゴリ	ツール	数	読み取り／書き込み
概要／システム	overview、system_info	2	読み取り
診断／RCA	pool_health_rca、alert_and_capacity_rca	2	読み取り
プール	pool_list、pool_get、pool_status、scrub_status、pool_capacity	5	読み取り
	pool_scrub_start	1	書き込み（中）
データセット	dataset_list、dataset_get	2	読み取り
	dataset_create	1	書き込み（中）
スナップショット	snapshot_list	1	読み取り
	snapshot_create（中）、snapshot_delete（高）	2	書き込み
ディスク	disk_list、smart_test_results	2	読み取り
アラート	alert_list	1	読み取り
サービス	service_list	1	読み取り
	service_restart	1	書き込み（中）
レプリケーション	replication_list、cloudsync_list	2	読み取り
取り消し（ガバナンス）	undo_list	1	読み取り
	undo_apply	1	書き込み（中）

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方を導入できます。

/plugin marketplace add AIops-tools/marketplace
/plugin install truenas-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されるため、監査行を、その行を書き込んだコードまでたどれます。認証情報は引き続き truenas-aiops init で設定します。詳しくは以下をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/truenas-aiops
openclaw skills info truenas-aiops          # expect: Visible to model: yes

その後、OpenClaw ゲートウェイを再起動して、プラグインを読み込ませてください。MCP サーバーは uv で取得され、このリリースのバージョンに固定されるため、uvx が PATH 上にある必要があります。これがない場合、スキルはインストールされますが、Visible to model: no と表示されます。認証情報は以下と同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install truenas-aiops
truenas-aiops init        # interactive wizard: connection details + encrypted API key
truenas-aiops doctor      # verify config, encrypted store, connectivity (hits /system/info)

init は ~/.truenas-aiops/config.yaml（秘密情報ではない接続情報）を書き込み、API キーを 暗号化 して ~/.truenas-aiops/secrets.enc に保存します。生成される設定の例：

targets:
  - name: nas1
    host: 10.0.0.30
    port: 443
    verify_ssl: false          # self-signed lab certs only
    api_path: /api/v2.0

API キーは TrueNAS UI の Credentials → API Keys で作成します。非対話型の用途（MCP サーバー、CI、cron）では、プロンプトを表示せずにストアのロックを解除できるよう、マスターパスワードをエクスポートします。

export TRUENAS_AIOPS_MASTER_PASSWORD='your-master-password'

そのパスワードの保存場所：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取り可能で、シェルの履歴にも記録されます。共有ホストや長期間稼働するホストでは、対話型プロンプトを使うか、必要なコマンドの実行中だけシークレットマネージャーから注入してください。

シークレットの管理

truenas-aiops secret set nas1             # prompts hidden for the API key
truenas-aiops secret list                 # names only, values never shown
truenas-aiops secret rm nas1
truenas-aiops secret rotate-password      # re-encrypt under a new master password
truenas-aiops secret migrate              # import a legacy plaintext .env, then deletes it

旧形式の平文環境変数 TRUENAS_<TARGET_NAME_UPPER>_APIKEY もフォールバックとして引き続き使用できますが、非推奨の警告が表示されます（truenas-aiops secret migrate で移行してください）。

対応範囲

バージョン：TrueNAS SCALE 25.04 以降では JSON-RPC/WebSocket 経由、REST v2.0 を引き続き提供するビルドでは REST 経由 — トランスポートは自動的に選択されます。対応する TrueNAS バージョンを参照してください。iXsystems は TrueNAS 26 へのアップグレードで 既存の API キーが取り消される と説明しています（これは上流の主張であり、ここでは再現していません）。

読み取り：システム情報、ZFS プール（一覧／取得／ステータス／スクラブのステータス／容量）、データセット（一覧／取得）、スナップショット（一覧）、ディスクと S.M.A.R.T. の結果、アラート、サービス、レプリケーションとクラウド同期タスク、単発のヘルス概要、読み取り専用の診断／RCA（pool_health_rca、alert_and_capacity_rca）。変更操作（ガバナンス対象、ドライランおよび破壊的操作では二重確認あり）：pool_scrub_start、dataset_create、snapshot_create、snapshot_delete、service_restart。

機能が足りませんか？ 対応範囲は意図的に絞っています。github.com/AIops-tools/TrueNAS-AIops で issue または PR を作成してください。機能リクエスト、貢献、コメントを歓迎します。

注意事項

• TrueNAS SCALE 25.04.2.1 で両方のトランスポートを使って実機検証済み — 読み取り結果をアプライアンス自身の API と照合し、書き込み → 監査 → 元に戻す → 復元を検証する一連のループを完了しています。対象となるものとならないものは、docs/VERIFICATION.md にエンドポイントごとに記載されています。「検証済み」がすべてを意味すると思い込まず、内容を確認してください。
• 未検証：障害のあるメディアに対する S.M.A.R.T.（実機が必要です。virtio では S.M.A.R.T. がまったく公開されません）、実際のターゲットに対するレプリケーション／クラウド同期、TrueNAS 26 の auth.login_ex（25.04 ではフォールバックのみを検証しています）。
• CLI の終了コード：0 は確認済み、1 は失敗または拒否、2 は結果不明（操作がまだ進行中の可能性があります。再試行する前にポーリングしてください）。
• 設計上、対象外としているもの：大量のデータを破壊する操作（データセット／プールの削除、上書きを伴うレプリケーションの実行）です。データを削除するのは snapshot_delete のみで、リスクは high、二重確認が必須です。

対象外

その他の NAS／ストレージ製品やバックアップ製品、ハイパーバイザーの VM ライフサイクル、コンテナークラスター、ネットワーク機器は、このツールの対象外です。

ライセンス

MIT — github.com/AIops-tools/TrueNAS-AIops