Diffs

diffs 是一个可选插件工具，带有简短的内置系统指导和配套 Skills，可将变更内容转换为供智能体使用的只读 diff 工件。

它接受以下任一输入：

• before 和 after 文本
• 统一格式的 patch

它可以返回：

• 用于 canvas 展示的 Gateway 网关查看器 URL
• 用于消息投递的渲染文件路径（PNG 或 PDF）
• 一次调用同时返回两种输出

启用后，该插件会将简明的使用指导预置到系统提示空间中，并且还会暴露一个详细的 Skills，用于智能体需要更完整说明的场景。

# 快速开始

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 插件的 before_prompt_build 钩子，同时保持插件、工具和配套 Skills 可用。

如果你想同时禁用指导和工具，请改为禁用该插件。

# 典型智能体工作流

# 输入示例

{
  "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 下返回结构化元数据。

模式行为摘要：

# 折叠的未更改部分

• 查看器可以显示类似 N unmodified lines 的行。
• 这些行上的展开控件是有条件的，并不保证适用于每种输入类型。
• 当渲染后的 diff 具有可展开的上下文数据时，会显示展开控件，这对于 before 和 after 输入很常见。
• 对于许多统一 patch 输入，被省略的上下文正文在解析后的 patch hunk 中不可用，因此该行可能出现但没有展开控件。这是预期行为。
• expandUnchanged 仅在存在可展开上下文时生效。

# 插件默认值

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

支持的默认值：

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

# 工件生命周期和存储

• 工件存储在临时子文件夹下：$TMPDIR/openclaw-diffs。
• 查看器工件元数据包含：
  • 随机工件 ID（20 个十六进制字符）
  • 随机 token（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，会在严格校验后使用它。
• 否则如果配置了插件 viewerBaseUrl，则使用它。
• 如果两者都没有覆盖，查看器 URL 默认使用 loopback 127.0.0.1。
• 如果 Gateway 网关绑定模式为 custom 且设置了 gateway.customBindHost，则会使用该主机。

baseUrl 规则：

• 必须是 http:// 或 https://。
• 查询和 hash 会被拒绝。
• 允许来源加可选基础路径。

# 安全模型

# 文件模式的浏览器要求

mode: "file" 和 mode: "both" 需要兼容 Chromium 的浏览器。

解析顺序：

常见失败文本：

• Diff PNG/PDF rendering requires a Chromium-compatible browser...

可通过安装 Chrome、Chromium、Edge 或 Brave，或设置上述某个可执行文件路径选项来修复。

# 故障排除

# 运维指导

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

# 相关

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