Diffs

diffs 是一个可选的内置插件工具，可将前后文本或统一补丁转换为只读 diff 工件。它还会在系统提示词前添加简短的智能体指导，并附带一个配套 Skill，提供更完整的说明。

输入：before + after 文本，或统一格式的 patch（互斥）。

输出：用于画布呈现的 Gateway 网关查看器 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 的行。仅当渲染后的差异包含可展开的上下文数据时（通常见于 before/after 输入），才会出现展开控件。许多统一格式补丁的区块中不包含上下文正文，因此可能会出现该行但没有展开控件——这是预期行为，并非错误。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 路径。
• 默认工件 TTL：30 分钟。可接受的最大 TTL：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（仅当 diff 使用语言包中的语言时）

查看器文档会相对于查看器 URL 解析这些资源，因此可选的 baseUrl 路径前缀也会沿用到资源请求中。

URL 解析顺序：工具调用的 baseUrl（经过严格验证后）-> 插件的 viewerBaseUrl -> 默认 local loopback 127.0.0.1。如果 Gateway 网关绑定模式为 custom 且已设置 gateway.customBindHost，则使用该主机而不是 local loopback。

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"）。

相关内容

• 浏览器
• 插件
• 工具概览