OpenClaw Diffsプラグイン活用ガイド：差分表示を自動化

コードの変更点を確認する際、プラスとマイナスの記号が並んだテキストだけでは、全体像を把握するのが難しいことがありますよね。特に複雑な修正をレビューする場合、視覚的に分かりやすい形式で差分を確認できるツールがあれば、開発効率はぐっと上がります。

diffs は、変更内容を読み取り専用の差分アーティファクトに変換する、オプションのプラグインツールです。短い組み込みのシステムガイダンスと、エージェント向けのスキルがセットになっています。

このツールは以下のいずれかを受け取ります：

• before と after のテキスト
• 統合された patch

また、以下の出力を返すことができます：

• Canvas プレゼンテーション用の Gateway ビューアー URL
• メッセージ配信用のレンダリング済みファイルパス（PNG または PDF）
• 1 回の呼び出しで両方の出力

有効にすると、プラグインは簡潔な使用ガイドをシステムプロンプトのスペースの先頭に追加します。また、エージェントがより詳細な指示を必要とする場合のために、詳細なスキルも公開します。

クイックスタート

1. プラグインを有効にします。
2. Canvas 優先のフローでは、mode: "view" で diffs を呼び出します。
3. チャットでのファイル配信フローでは、mode: "file" で diffs を呼び出します。
4. 両方のアーティファクトが必要な場合は、mode: "both" で diffs を呼び出します。

プラグインの有効化

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

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

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

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

これにより、プラグイン、ツール、およびコンパニオンスキルは利用可能な状態を維持しつつ、diffs プラグインの before_prompt_build フックをブロックします。

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

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

1. エージェントが diffs を呼び出します。
2. エージェントが details フィールドを読み取ります。
3. エージェントは以下のいずれかを行います：
   • canvas present を使用して details.viewerUrl を開く
   • path または filePath を使用して message で details.filePath を送信する
   • その両方を行う

入力例

Before と After の場合：

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

Patch の場合：

{
  "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"
}

ツール入力リファレンス

特に明記されていない限り、すべてのフィールドはオプションです：

• before (string): 元のテキスト。patch を省略した場合、after と共に必須です。
• after (string): 更新後のテキスト。patch を省略した場合、before と共に必須です。
• patch (string): 統合された diff テキスト。before および after とは排他的です。
• path (string): before/after モードでの表示用ファイル名。
• lang (string): before/after モードでの言語オーバーライドのヒント。不明な値はプレーンテキストにフォールバックされます。
• title (string): ビューアーのタイトルのオーバーライド。
• mode ("view" | "file" | "both"): 出力モード。デフォルトはプラグインのデフォルト設定 defaults.mode です。 非推奨のエイリアス："image" は "file" と同じように動作し、後方互換性のために引き続き受け入れられます。
• theme ("light" | "dark"): ビューアーのテーマ。デフォルトはプラグインのデフォルト設定 defaults.theme です。
• layout ("unified" | "split"): diff のレイアウト。デフォルトはプラグインのデフォルト設定 defaults.layout です。
• expandUnchanged (boolean): 完全なコンテキストが利用可能な場合に、変更されていないセクションを展開します。呼び出しごとのオプションのみ（プラグインのデフォルトキーではありません）。
• fileFormat ("png" | "pdf"): レンダリングされるファイル形式。デフォルトはプラグインのデフォルト設定 defaults.fileFormat です。
• fileQuality ("standard" | "hq" | "print"): PNG または PDF レンダリングの品質プリセット。
• fileScale (number): デバイススケールのオーバーライド（1-4）。
• fileMaxWidth (number): CSS ピクセル単位の最大レンダリング幅（640-2400）。
• ttlSeconds (number): ビューアーアーティファクトの TTL（秒単位）。デフォルトは 1800、最大は 21600。
• baseUrl (string): ビューアー URL のオリジンのオーバーライド。http または https である必要があり、クエリやハッシュは含められません。

バリデーションと制限：

• before と after はそれぞれ最大 512 KiB。
• patch は最大 2 MiB。
• path は最大 2048 バイト。
• lang は最大 128 バイト。
• title は最大 1024 バイト。
• Patch の複雑さの制限：最大 128 ファイル、合計 120,000 行。
• patch と before または after を同時に指定すると拒否されます。
• レンダリングされたファイルの安全制限（PNG と PDF に適用）：
  • fileQuality: "standard": 最大 8 MP（8,000,000 レンダリングピクセル）。
  • fileQuality: "hq": 最大 14 MP（14,000,000 レンダリングピクセル）。
  • fileQuality: "print": 最大 24 MP（24,000,000 レンダリングピクセル）。
  • PDF は最大 50 ページまで。

出力詳細の仕様

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

ビューアーを作成するモードの共通フィールド：

• artifactId
• viewerUrl
• viewerPath
• title
• expiresAt
• inputKind
• fileCount
• mode
• context（利用可能な場合、agentId, sessionId, messageChannel, agentAccountId）

PNG または PDF がレンダリングされる際のファイルフィールド：

• artifactId
• expiresAt
• filePath
• path（メッセージツールとの互換性のために filePath と同じ値）
• fileBytes
• fileFormat
• fileQuality
• fileScale
• fileMaxWidth

モードの動作サマリー：

• mode: "view": ビューアーフィールドのみ。
• mode: "file": ファイルフィールドのみ。ビューアーアーティファクトは作成されません。
• mode: "both": ビューアーフィールドとファイルフィールドの両方。ファイルのレンダリングに失敗した場合でも、fileError と共にビューアーは返されます。

折りたたまれた変更のないセクション

• ビューアーには N unmodified lines（N行の変更なし）のような行が表示されることがあります。
• それらの行の展開コントロールは条件付きであり、すべての入力形式で保証されるわけではありません。
• 展開コントロールは、レンダリングされた diff に展開可能なコンテキストデータがある場合に表示されます。これは通常、before/after 入力の場合です。
• 多くの統合パッチ入力では、省略されたコンテキストの本体は解析されたパッチハンプ内で利用できないため、展開コントロールなしで行が表示されることがあります。これは期待される動作です。
• expandUnchanged は、展開可能なコンテキストが存在する場合にのみ適用されます。

プラグインのデフォルト設定

~/.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

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

セキュリティ設定

• security.allowRemoteViewer (boolean, デフォルト false)
  • false: ビューアールートへの非ループバックリクエストは拒否されます。
  • true: トークン化されたパスが有効であれば、リモートビューアーが許可されます。

例：

{
  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 が提供されている場合、厳密なバリデーションの後にそれが使用されます。
• baseUrl がない場合、ビューアー URL はデフォルトでループバック 127.0.0.1 になります。
• Gateway のバインドモードが custom で、gateway.customBindHost が設定されている場合、そのホストが使用されます。

baseUrl のルール：

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

セキュリティモデル

ビューアーの要塞化：

• デフォルトではループバックのみ。
• 厳密な ID とトークンのバリデーションを備えたトークン化されたビューアーパス。
• ビューアーレスポンスの CSP：
  • default-src 'none'
  • スクリプトとアセットは self からのみ
  • 外部への connect-src はなし
• リモートアクセスが有効な場合のリモートミススロットリング：
  • 60 秒間に 40 回の失敗
  • 60 秒間のロックアウト（429 Too Many Requests）

ファイルレンダリングの要塞化：

• スクリーンショットブラウザのリクエストルーティングは、デフォルトで拒否されます。
• http://127.0.0.1/plugins/diffs/assets/* からのローカルビューアーアセットのみが許可されます。
• 外部ネットワークリクエストはブロックされます。

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

mode: "file" および mode: "both" には、Chromium 互換のブラウザが必要です。

解決順序：

1. OpenClaw 設定の browser.executablePath。
2. 環境変数：
   • OPENCLAW_BROWSER_EXECUTABLE_PATH
   • BROWSER_EXECUTABLE_PATH
   • PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
3. プラットフォームのコマンド/パス検出フォールバック。

一般的なエラーテキスト：

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

Chrome, Chromium, Edge, または Brave をインストールするか、上記の実行パスオプションのいずれかを設定することで修正できます。

トラブルシューティング

入力バリデーションエラー：

• Provide patch or both before and after text.
  • before と after の両方を含めるか、patch を提供してください。
• Provide either patch or before/after input, not both.
  • 入力モードを混ぜないでください。
• Invalid baseUrl: ...
  • http(s) オリジンとオプションのパスを使用してください。クエリやハッシュは含めないでください。
• {field} exceeds maximum size (...)
  • ペイロードのサイズを小さくしてください。
• Large patch rejection
  • パッチのファイル数または合計行数を減らしてください。

ビューアーのアクセシビリティの問題：

• ビューアー URL はデフォルトで 127.0.0.1 に解決されます。
• リモートアクセスのシナリオでは、以下のいずれかを行ってください：
  • ツール呼び出しごとに baseUrl を渡す。
  • gateway.bind=custom と gateway.customBindHost を使用する。
• 外部からのビューアーアクセスを意図している場合にのみ、security.allowRemoteViewer を有効にしてください。

変更のない行に展開ボタンがない：

• パッチに入力に展開可能なコンテキストが含まれていない場合に発生することがあります。
• これは期待される動作であり、ビューアーの不具合ではありません。

アーティファクトが見つからない：

• TTL によりアーティファクトが期限切れになりました。
• トークンまたはパスが変更されました。
• クリーンアップにより古いデータが削除されました。

運用ガイドライン

• Canvas でのローカルな対話型レビューには、mode: "view" を優先してください。
• 添付ファイルが必要な外部チャットチャネルには、mode: "file" を優先してください。
• デプロイメントでリモートビューアー URL が必要な場合を除き、allowRemoteViewer は無効のままにしてください。
• 機密性の高い diff については、明示的に短い ttlSeconds を設定してください。
• 必要のない限り、diff の入力にシークレットを送信しないでください。
• 使用しているチャネルで画像が大幅に圧縮される場合（例：Telegram や WhatsApp）、PDF 出力（fileFormat: "pdf"）を検討してください。

Diff レンダリングエンジン：

• Diffs を使用しています。

関連ドキュメント

• Tools overview
• Plugins
• Browser

次のステップ

• AI Setup Assistant で設定をサポート
• API リファレンス を確認する