差異

diffs 是選用的內建外掛工具，可將變更前／後文字或統一格式修補轉換成唯讀差異成品。它也會在系統提示詞前加入簡短的代理指引，並隨附一項配套 Skill，以提供更完整的操作說明。

輸入：before + after 文字，或統一格式的 patch（兩者互斥）。

輸出：用於畫布呈現的閘道檢視器 URL、用於訊息傳送的已算繪 PNG/PDF 檔案路徑，或兩者皆有。

快速開始

openclaw plugins install diffs

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

停用內建系統指引

若要保留此工具，但移除前置加入的系統提示詞指引，請將 plugins.entries.diffs.hooks.allowPromptInjection 設為 false：

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

這會封鎖外掛的 before_prompt_build 鉤子，同時保留工具與 Skill 可供使用。若要同時停用指引與工具，請改為停用此外掛。

工具輸入參考

除非另有註明，否則所有欄位皆為選填。

語法醒目提示

內建語言：

javascript、typescript、tsx、jsx、json、markdown、yaml、css、html、sh、python、go、rust、java、c、cpp、csharp、php、sql、docker、ruby、swift、kotlin、r、dart、lua、powershell、xml 與 toml。

常用別名（js、ts、bash、md、yml、c++、dockerfile、rb、kt、ps1 等）會正規化為這些語言。

安裝 Diff Viewer Language Pack 外掛可支援更多語言（Astro、Vue、Svelte、MDX、GraphQL、Terraform/HCL、Nix、Clojure、Elixir、Haskell、OCaml、Scala、Zig、Solidity、Verilog/VHDL、Fortran、MATLAB、LaTeX、Mermaid、Sass/Less/SCSS、Nginx、Apache、CSV、dotenv、INI、diff 等）：

openclaw plugins install clawhub:@openclaw/diffs-language-pack

未安裝語言套件時，不支援的語言仍會算繪為可讀的純文字。上游目錄請參閱 Diffs Language Pack 外掛 與 Shiki 語言。

輸出詳細資料契約

所有成功結果都包含 changed：變更前／後輸入相同時，會傳回 false 且不建立成品；已算繪的結果會傳回 true。

摺疊的未變更區段

檢視器會顯示類似 N unmodified lines 的列。只有在算繪後的差異內容具有可展開的上下文資料時（常見於前後輸入），才會顯示展開控制項。許多統一格式修補程式的區塊不含上下文內容，因此可能顯示該列但沒有展開控制項——這是預期行為，不是錯誤。expandUnchanged 只會在有可展開的上下文時套用。

多檔案導覽

涉及多個檔案的修補程式會以變更檔案摘要卡片開頭：其中包含 +N / -N 總計數、各檔案計數、新增／刪除／重新命名徽章，以及可跳至各檔案的錨點連結。算繪後的 PNG/PDF 檔案會保留各檔案標頭中的計數，但移除互動式檢視切換控制項，因為這些控制項在靜態檔案中無法運作。

外掛預設值

在 ~/.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",            ttlSeconds: 21600,          },        },      },    },  },}

支援的 defaults 鍵：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 下。
• 檢視器中繼資料會儲存隨機的 20 位十六進位字元成品 ID、隨機的 48 位十六進位字元權杖、createdAt/expiresAt，以及所儲存的 viewer.html 路徑。
• 預設成品存留時間：30 分鐘。可接受的最長存留時間：6 小時。
• 每次建立成品的呼叫後，都會視情況執行清理；過期的成品會被刪除。
• 當中繼資料遺失時，備援清理會移除建立超過 24 小時的舊資料夾。

檢視器 URL 與網路行為

檢視器路由：/plugins/diffs/view/{artifactId}/{token}

檢視器資產：

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js
• /plugins/diffs-language-pack/assets/viewer.js（僅當差異內容使用語言套件中的語言時）

檢視器文件會相對於檢視器 URL 解析這些資產，因此選用的 baseUrl 路徑前綴也會套用至資產要求。

URL 解析順序：工具呼叫的 baseUrl（通過嚴格驗證後）-> 外掛的 viewerBaseUrl -> 預設迴路位址 127.0.0.1。若閘道繫結模式為 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"）。

相關內容

• 瀏覽器
• 外掛
• 工具概覽