差異

diffs 是一個可選的 Plugin 工具，內建簡短的系統指引，並附帶一個配套 skill，可將變更內容轉換為供代理使用的唯讀 diff 成品。

它接受以下任一輸入：

• before 與 after 文字
• 統一格式的 patch

它可以回傳：

• 用於 canvas 呈現的 Gateway 檢視器 URL
• 用於訊息傳送的已算繪檔案路徑（PNG 或 PDF）
• 在一次呼叫中同時回傳兩種輸出

啟用後，Plugin 會在系統提示空間前置簡潔的使用指引，也會公開詳細的 skill，供代理需要更完整說明時使用。

快速開始

openclaw plugins install diffs

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

停用內建系統指引

如果你想保留啟用 diffs 工具，但停用其內建的系統提示指引，請將 plugins.entries.diffs.hooks.allowPromptInjection 設為 false：

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

這會封鎖 diffs Plugin 的 before_prompt_build hook，同時保留 Plugin、工具與配套 skill 可用。

如果你想同時停用指引與工具，請改為停用 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 的列。
• 這些列上的展開控制項是有條件的，並不保證每種輸入類型都有。
• 當已算繪 diff 具有可展開的內容資料時，會出現展開控制項；這通常見於 before and after 輸入。
• 對於許多統一 patch 輸入，省略的內容主體在已解析的 patch hunk 中不可用，因此該列可能會在沒有展開控制項的情況下出現。這是預期行為。
• expandUnchanged 僅在存在可展開內容時適用。

Plugin 預設值

在 ~/.openclaw/openclaw.json 中設定整個 Plugin 的預設值：

{  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",            ttlSeconds: 21600,          },        },      },    },  },}

支援的預設值：

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

明確的工具參數會覆寫這些預設值。

持久化檢視器 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 個十六進位字元）
  • 隨機 token（48 個十六進位字元）
  • 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 預設為 loopback 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，或設定上述其中一個可執行檔路徑選項。

疑難排解

操作指引

• 對於畫布中的本機互動式檢閱，偏好使用 mode: "view"。
• 對於需要附件的外送聊天管道，偏好使用 mode: "file"。
• 除非你的部署需要遠端檢視器 URL，否則請保持停用 allowRemoteViewer。
• 針對敏感差異設定明確且短的 ttlSeconds。
• 不需要時，避免在差異輸入中傳送秘密。
• 如果你的管道會大幅壓縮圖片（例如 Telegram 或 WhatsApp），請偏好 PDF 輸出（fileFormat: "pdf"）。

相關

• 瀏覽器
• Plugin
• 工具總覽