Diffs

使用可选的 Diffs 插件将前后文本或统一补丁渲染为 Gateway 托管的差异视图、文件（PNG 或 PDF）或两者兼备。

diffs 是一个可选的插件工具和配套技能，将变更内容转化为代理的只读差异产物。它接受以下任一输入：

before 和 after 文本
统一 patch

它可以返回：

用于画布展示的 Gateway 查看器 URL
用于消息交付的渲染文件路径（PNG 或 PDF）
在一次调用中同时提供两种输出

快速开始

启用插件。
使用 mode: "view" 调用 diffs 以进行画布优先的工作流。
使用 mode: "file" 调用 diffs 以进行聊天文件交付工作流。
使用 mode: "both" 调用 diffs 以在需要两种产物时使用。

启用插件

json5

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

典型代理工作流

代理调用 diffs。
代理读取 details 字段。
代理执行以下操作之一：
- 使用 canvas present 打开 details.viewerUrl
- 使用 message 工具通过 path 或 filePath 发送 details.filePath
- 同时执行两者

输入示例

前后对比：

json

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

补丁：

json

{
  "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）：统一差异文本。与 before 和 after 互斥。
path（string）：前后对比模式的显示文件名。
lang（string）：前后对比模式的语言覆盖提示。
title（string）：查看器标题覆盖。
mode（"view" | "file" | "both"）：输出模式。默认为插件默认值 defaults.mode。
theme（"light" | "dark"）：查看器主题。默认为插件默认值 defaults.theme。
layout（"unified" | "split"）：差异布局。默认为插件默认值 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 字节。
补丁复杂度上限：最多 128 个文件和 120000 总行数。
同时提供 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

渲染 PNG 或 PDF 时的文件字段：

filePath
path（与 filePath 值相同，用于 message 工具兼容性）
fileBytes
fileFormat
fileQuality
fileScale
fileMaxWidth

模式行为摘要：

mode: "view"：仅查看器字段。
mode: "file"：仅文件字段，无查看器产物。
mode: "both"：查看器字段加文件字段。如果文件渲染失败，查看器仍然返回并附带 fileError。

折叠的未更改部分

查看器可以显示 N unmodified lines 这样的行。
这些行上的展开控件是有条件的，并非对每种输入类型都保证存在。
当渲染的差异具有可展开的上下文数据时，展开控件会出现，这在前后对比输入中是典型的。
对于许多统一补丁输入，省略的上下文体在解析的补丁块中不可用，因此该行可能出现但没有展开控件。这是预期行为。
expandUnchanged 仅在可展开上下文存在时适用。

插件默认值

在 ~/.openclaw/openclaw.json 中设置插件范围的默认值：

json5

{
  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：如果令牌化路径有效，则允许远程查看器。

示例：

json5

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

产物生命周期和存储

产物存储在临时子文件夹下：$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，在严格验证后使用它。
没有 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 兼容浏览器。

解析顺序：

OpenClaw 配置中的 browser.executablePath。
环境变量：
- OPENCLAW_BROWSER_EXECUTABLE_PATH
- BROWSER_EXECUTABLE_PATH
- PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
平台命令/路径发现回退。

常见错误文本：

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 (...)
- 减少载荷大小。
大型补丁被拒绝
- 减少补丁文件数量或总行数。

查看器可访问性问题：

查看器 URL 默认解析为 127.0.0.1。
对于远程访问场景，可以：
- 每次工具调用传递 baseUrl，或
- 使用 gateway.bind=custom 和 gateway.customBindHost
- 仅在需要外部查看器访问时启用 security.allowRemoteViewer。

未修改行没有展开按钮：

这可能发生在补丁输入中，当补丁不携带可展开上下文时。
这是预期行为，不表示查看器故障。

产物未找到：

产物因 TTL 过期。
令牌或路径已更改。
清理移除了陈旧数据。

操作指南

对于本地交互式审查，优先使用 mode: "view" 在画布中查看。
对于需要附件的出站聊天频道，优先使用 mode: "file"。
除非你的部署需要远程查看器 URL，否则保持 allowRemoteViewer 禁用。
为敏感差异设置显式的短 ttlSeconds。
在不需要时避免在差异输入中发送敏感信息。
如果你的频道会对图像进行激进压缩（例如 Telegram 或 WhatsApp），优先使用 PDF 输出（fileFormat: "pdf"）。

差异渲染引擎：

由 Diffs 提供支持。

Diffs ​

快速开始 ​

启用插件 ​

典型代理工作流 ​

输入示例 ​

工具输入参考 ​

输出详情契约 ​

折叠的未更改部分 ​

插件默认值 ​

安全配置 ​

产物生命周期和存储 ​

查看器 URL 和网络行为 ​

安全模型 ​

文件模式的浏览器要求 ​

故障排除 ​

操作指南 ​

相关文档 ​

Diffs

快速开始

启用插件

典型代理工作流

输入示例

工具输入参考

输出详情契约

折叠的未更改部分

插件默认值

安全配置

产物生命周期和存储

查看器 URL 和网络行为

安全模型

文件模式的浏览器要求

故障排除

操作指南

相关文档