差分

diffs は、短い組み込みシステムガイダンスと付属スキルを備えた任意の Plugin ツールで、変更内容をエージェント向けの読み取り専用差分アーティファクトに変換します。

次のいずれかを受け取ります。

• before と after のテキスト
• 統一形式の patch

次を返せます。

• キャンバス表示用の Gateway ビューアー URL
• メッセージ配信用のレンダリング済みファイルパス (PNG または PDF)
• 1 回の呼び出しで両方の出力

有効にすると、この Plugin は簡潔な使用ガイダンスをシステムプロンプト領域に付加し、エージェントがより詳しい手順を必要とする場合のために詳細なスキルも公開します。

# クイックスタート

openclaw plugins install diffs

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
      },
    },
  },
}

# 組み込みシステムガイダンスを無効にする

diffs ツールを有効にしたまま、その組み込みシステムプロンプトガイダンスを無効にしたい場合は、plugins.entries.diffs.hooks.allowPromptInjection を false に設定します。

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
      },
    },
  },
}

これにより、Plugin、ツール、付属スキルは利用可能なまま、diffs Plugin の before_prompt_build フックがブロックされます。

ガイダンスとツールの両方を無効にしたい場合は、代わりに Plugin を無効にしてください。

# 一般的なエージェントワークフロー

# 入力例

{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}

{
  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
  "mode": "both"
}

# ツール入力リファレンス

特記がない限り、すべてのフィールドは任意です。

# 出力 details の契約

このツールは details 配下に構造化メタデータを返します。

モード動作の概要:

# 折りたたまれた未変更セクション

• ビューアーは N unmodified lines のような行を表示できます。
• それらの行の展開コントロールは条件付きであり、すべての入力種別で保証されるわけではありません。
• 展開コントロールは、レンダリング済み差分に展開可能なコンテキストデータがある場合に表示されます。これは変更前後入力では一般的です。
• 多くの統一パッチ入力では、省略されたコンテキスト本文は解析済みパッチハンクで利用できないため、展開コントロールなしで行が表示されることがあります。これは想定される動作です。
• expandUnchanged は、展開可能なコンテキストが存在する場合にのみ適用されます。

# Plugin のデフォルト

Plugin 全体のデフォルトは ~/.openclaw/openclaw.json で設定します。

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          defaults: {
            fontFamily: "Fira Code",
            fontSize: 15,
            lineSpacing: 1.6,
            layout: "unified",
            showLineNumbers: true,
            diffIndicators: "bars",
            wordWrap: true,
            background: true,
            theme: "dark",
            fileFormat: "png",
            fileQuality: "standard",
            fileScale: 2,
            fileMaxWidth: 960,
            mode: "both",
          },
        },
      },
    },
  },
}

サポートされるデフォルト:

• fontFamily
• fontSize
• lineSpacing
• layout
• showLineNumbers
• diffIndicators
• wordWrap
• background
• theme
• fileFormat
• fileQuality
• fileScale
• fileMaxWidth
• mode

明示的なツールパラメーターはこれらのデフォルトを上書きします。

# 永続ビューアー URL 設定

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          viewerBaseUrl: "https://gateway.example.com/openclaw",
        },
      },
    },
  },
}

# セキュリティ設定

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          security: {
            allowRemoteViewer: false,
          },
        },
      },
    },
  },
}

# アーティファクトのライフサイクルと保存

• アーティファクトは一時サブフォルダー $TMPDIR/openclaw-diffs の下に保存されます。
• ビューアーアーティファクトのメタデータには次が含まれます。
  • ランダムなアーティファクト ID (20 桁の 16 進文字)
  • ランダムなトークン (48 桁の 16 進文字)
  • createdAt と expiresAt
  • 保存された viewer.html パス
• 指定されていない場合、デフォルトのアーティファクト TTL は 30 分です。
• 受け付けられるビューアー TTL の最大値は 6 時間です。
• クリーンアップはアーティファクト作成後に機会的に実行されます。
• 期限切れのアーティファクトは削除されます。
• メタデータが欠落している場合、フォールバッククリーンアップにより 24 時間より古い古いフォルダーが削除されます。

# ビューアー URL とネットワーク動作

ビューアールート:

• /plugins/diffs/view/{artifactId}/{token}

ビューアーアセット:

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js

ビューアードキュメントはそれらのアセットをビューアー URL からの相対位置で解決するため、任意の baseUrl パスプレフィックスは両方のアセットリクエストでも維持されます。

URL 構築動作:

• ツール呼び出しの baseUrl が指定されている場合は、厳格な検証後に使用されます。
• それ以外で Plugin の viewerBaseUrl が設定されている場合は、それが使用されます。
• どちらの上書きもない場合、ビューアー URL はループバック 127.0.0.1 が既定値になります。
• Gateway のバインドモードが custom で、gateway.customBindHost が設定されている場合は、そのホストが使用されます。

baseUrl ルール:

• http:// または https:// である必要があります。
• クエリとハッシュは拒否されます。
• オリジンに任意のベースパスを加えたものが許可されます。

# セキュリティモデル

# ファイルモードのブラウザー要件

mode: "file" と mode: "both" には Chromium 互換ブラウザーが必要です。

解決順序:

一般的な失敗テキスト:

• Diff PNG/PDF rendering requires a Chromium-compatible browser...

Chrome、Chromium、Edge、または Brave をインストールするか、上記の実行可能ファイルパスオプションのいずれかを設定して修正します。

# トラブルシューティング

# 運用ガイダンス

• canvas でのローカル対話型レビューには mode: "view" を優先します。
• 添付ファイルが必要な外向きチャットチャネルには mode: "file" を優先します。
• デプロイでリモートビューアー URL が必要でない限り、allowRemoteViewer は無効のままにします。
• 機密性の高い diff には、明示的で短い ttlSeconds を設定します。
• 必要でない場合は、diff 入力にシークレットを送信しないでください。
• チャネルが画像を強く圧縮する場合 (たとえば Telegram や WhatsApp)、PDF 出力 (fileFormat: "pdf") を優先します。

# 関連

• ブラウザー
• プラグイン
• ツール概要