差異

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

它接受以下任一輸入：

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

它可以回傳：

• 用於畫布呈現的 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",
          },
        },
      },
    },
  },
}

支援的預設值：

• 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,
          },
        },
      },
    },
  },
}

# 成品生命週期與儲存

• 成品會儲存在 temp 子資料夾底下：$TMPDIR/openclaw-diffs。
• 檢視器成品中繼資料包含：
  • 隨機成品 ID（20 個十六進位字元）
  • 隨機權杖（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，或設定上述其中一個可執行檔路徑選項。

# 疑難排解

# 操作指引

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

# 相關

• 瀏覽器
• Plugin
• 工具概覽