Diffs

diffs 是一个可选的捆绑插件工具，它会将修改前/后的文本或统一补丁转换为只读 diff 产物。它还会在系统提示中追加简短的代理指导，并附带一个配套技能以提供更完整的说明。输入：before + after 文本，或一个统一的 patch（二者互斥）。输出：用于画布展示的网关查看器 URL、用于消息传递的已渲染 PNG/PDF 文件路径，或两者都有。

快速开始

安装插件

openclaw plugins install diffs

启用插件

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

选择模式

view
file
both

以画布优先的流程：代理调用 diffs 时使用 mode: "view"，并通过 canvas present 打开 details.viewerUrl。

聊天文件传递：代理调用 diffs 时使用 mode: "file"，并通过 message 使用 path 或 filePath 发送 details.filePath。

组合模式（默认）：代理调用 diffs 时使用 mode: "both"，一次调用即可同时获取两种产物。

禁用内置系统指导

要保留该工具但去掉前置的系统提示指导，请将 plugins.entries.diffs.hooks.allowPromptInjection 设置为 false：

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

这会阻止该插件的 before_prompt_build 钩子，同时保留工具和技能可用。要同时禁用指导和工具，请改为禁用该插件。

工具输入参考

除非另有说明，所有字段都是可选的。

string

原始文本。当省略 patch 时，需与 after 一起提供。

string

更新后的文本。当省略 patch 时，需与 before 一起提供。

string

统一 diff 文本。与 before 和 after 互斥。

string

before/after 模式的显示文件名。

string

before/after 模式的语言覆盖提示。未知值以及默认查看器集合之外的语言会回退为纯文本，除非安装了 Diff Viewer Language Pack 插件。

string

查看器标题覆盖。

"view" | "file" | "both"

输出模式。默认使用插件默认值 defaults.mode（both）。已弃用别名："image" 的行为与 "file" 完全相同。

"light" | "dark"

查看器主题。默认使用插件默认值 defaults.theme。

"unified" | "split"

diff 布局。默认使用插件默认值 defaults.layout。

boolean

当完整上下文可用时展开未更改部分。仅限每次调用的选项（不是插件默认键）。

"png" | "pdf"

渲染文件格式。默认使用插件默认值 defaults.fileFormat。

"standard" | "hq" | "print"

PNG/PDF 渲染的质量预设。

number

设备缩放覆盖值（1-4）。

number

CSS 像素中的最大渲染宽度（640-2400）。

number

default:"1800"

查看器和独立文件输出的 Artifact 存活时间（TTL），单位为秒。最大值 21600。

string

查看器 URL 源覆盖值。覆盖插件 viewerBaseUrl。必须是 http 或 https，且不能包含 query/hash。

验证和限制

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。
- fileQuality: "print"：最大 24 MP。
- PDF 也最多限制为 50 页。

语法高亮

内置语言： 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。

查看器字段（view 和 both 模式）

changed
artifactId
viewerUrl
viewerPath
title
expiresAt
inputKind
fileCount
mode
context（在可用时包含 agentId、sessionId、messageChannel、agentAccountId）

文件字段（file 和 both 模式）

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

模式	返回内容
`"view"`	仅返回查看器字段。
`"file"`	仅返回文件字段，不返回查看器工件。
`"both"`	返回查看器字段和文件字段。如果文件渲染失败，查看器仍会返回，并附带 `fileError`。

折叠的未更改部分

查看器会显示类似 N 行未修改 的行。只有当渲染后的 diff 包含可展开的上下文数据时，才会出现展开控件（通常用于 before/after 输入）。许多统一补丁在其 hunks 中省略了上下文正文，因此该行可能在没有展开控件的情况下出现——这是预期行为，不是 bug。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 配置

string

当工具调用未传入 baseUrl 时，插件返回查看器链接时使用的后备值。必须是 http 或 https，且不能包含 query/hash。

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          viewerBaseUrl: "https://gateway.example.com/openclaw",
        },
      },
    },
  },
}

安全配置

boolean

default:"false"

false：对 viewer 路由的非回环请求将被拒绝。true：如果带 token 的路径有效，则允许远程 viewer。

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

资源生命周期和存储

Viewer HTML 和元数据保存在共享的 state/openclaw.sqlite 数据库中，位于 Diffs 插件 blob 命名空间下。HTML 采用 gzip 压缩；SQLite 只存储随机 URL token 的 SHA-256 哈希，而不存储 token 本身。
渲染后的 PNG/PDF 文件仍作为临时物化内容保留在 $TMPDIR/openclaw-diffs 下，因为通道传递需要文件路径。SQLite 负责它们的过期元数据；不会写入任何 JSON 侧边文件。
默认制品 TTL：30 分钟。可接受的最大 TTL：6 小时。
清理会在每次 artifact create 调用后机会性运行。首先删除已过期的 SQLite 行，然后删除任何对应的 PNG/PDF 目录。
兜底扫描会移除超过 24 小时且没有对应数据库行的临时文件夹。旧版 meta.json、file-meta.json 和 viewer.html 缓存不会被导入或读取。

查看器 URL 和网络行为

查看器路由：/plugins/diffs/view/{artifactId}/{token} 查看器资源：

/plugins/diffs/assets/viewer.js
/plugins/diffs/assets/viewer-runtime.js
/plugins/diffs-language-pack/assets/viewer.js（仅当 diff 使用语言包语言时）

查看器文档会相对于 viewer URL 解析这些资源，因此可选的 baseUrl 路径前缀也会传递到资源请求中。 URL 解析顺序：工具调用的 baseUrl（严格验证后）-> 插件的 viewerBaseUrl -> gateway.publicOrigin -> 现有的绑定感知 Gateway 后备值。 baseUrl 规则：必须是 http:// 或 https://；会拒绝 query 和 hash；允许 origin 加可选的基础路径。

安全模型

查看器加固

默认仅允许回环访问。
带令牌的查看器路径，并对 ID 和令牌模式进行严格验证。
查看器响应的 CSP：default-src 'none'；脚本/资源仅允许来自自身；不允许任何外部 connect-src。
启用远程访问时的远程未命中限流：60 秒内 40 次失败将触发 60 秒锁定（429 Too Many Requests）。

文件渲染加固

截图浏览器请求路由采用默认拒绝策略。
仅允许来自 http://127.0.0.1/plugins/diffs/assets/* 的本地 viewer 资源。
外部网络请求被阻止。

文件模式的浏览器要求

mode: "file" 和 mode: "both" 需要与基于 Chromium 的浏览器兼容。解析顺序：

配置

OpenClaw 配置中的 browser.executablePath。

环境变量

OPENCLAW_BROWSER_EXECUTABLE_PATH
BROWSER_EXECUTABLE_PATH
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH

平台回退

Chrome、Chromium、Edge 和 Brave 的常见安装路径，以及 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) 源点，不要包含 query/hash。
{field} exceeds maximum size (...) — 减少负载大小。
Large patch rejection — 减少 patch 文件数量或总行数。

查看器可访问性

默认情况下，Viewer URL 解析为 127.0.0.1。
如需远程访问，请设置 gateway.publicOrigin、设置插件的 viewerBaseUrl，或按次调用传入 baseUrl。
如果 gateway.trustedProxies 为同主机代理（例如 Tailscale Serve）包含回环地址，则没有转发客户端 IP 标头的原始回环查看器请求会按设计安全失败。
对于该代理拓扑，优先使用 mode: "file"/"both" 生成附件，或有意启用 security.allowRemoteViewer，并配合插件的 viewerBaseUrl/代理的 baseUrl 生成可共享的查看器链接。
仅当确实需要外部查看器访问时，才启用 security.allowRemoteViewer。

未修改行没有展开按钮

对于缺少可展开上下文的 patch 输入，这是预期行为；不是查看器故障。

未找到制品

制品因 TTL 过期。
Token 或路径已更改。
清理操作移除了过期数据。

操作指南

本地在画布中进行交互式审阅时，优先使用 mode: "view"。
需要附件的外部聊天频道中，优先使用 mode: "file"。
除非你的部署需要远程查看器 URL，否则请保持 allowRemoteViewer 处于禁用状态。
对于敏感差异，请设置明确且较短的 ttlSeconds。
在不需要时，避免在差异输入中发送密钥。
如果你的频道会对图片进行强压缩（例如 Telegram 或 WhatsApp），请优先使用 PDF 输出（fileFormat: "pdf"）。

差异渲染引擎由 Diffs 提供支持。

概览

插件

插件指南

构建插件

技能

自动化

工具

智能体协作

快速开始

禁用内置系统指导

工具输入参考

语法高亮

输出详情契约

折叠的未更改部分

多文件导航

插件默认值

持久化查看器 URL 配置

安全配置

资源生命周期和存储

查看器 URL 和网络行为

安全模型

文件模式的浏览器要求

故障排查

操作指南

另请参阅

​快速开始

​禁用内置系统指导

​工具输入参考

​语法高亮

​输出详情契约

​折叠的未更改部分

​多文件导航

​插件默认值

​持久化查看器 URL 配置

​安全配置

​资源生命周期和存储

​查看器 URL 和网络行为

​安全模型

​文件模式的浏览器要求

​故障排查

​操作指南

​另请参阅

快速开始

禁用内置系统指导

工具输入参考

语法高亮

输出详情契约

折叠的未更改部分

多文件导航

插件默认值

持久化查看器 URL 配置

安全配置

资源生命周期和存储

查看器 URL 和网络行为

安全模型

文件模式的浏览器要求

故障排查

操作指南

另请参阅