Skip to main content

​
Diffs

diffs is an optional plugin tool that renders a read-only diff from either:
  • arbitrary before / after text
  • a unified patch
The tool can produce:
  • a gateway-hosted viewer URL for canvas use
  • a PNG image for message delivery
  • both outputs together

​
Enable the plugin

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

​
What agents get back

  • mode: "view" returns details.viewerUrl and details.viewerPath
  • mode: "image" returns details.imagePath only
  • mode: "both" returns the viewer details plus details.imagePath
Typical agent patterns:
  • open details.viewerUrl in canvas with canvas present
  • send details.imagePath with the message tool using path or filePath

​
Tool inputs

Before/after input: 
{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}
Patch input: 
{
  "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"
}
Useful options:
  • mode: view, image, or both
  • layout: unified or split
  • theme: light or dark
  • expandUnchanged: expand unchanged sections instead of collapsing them
  • path: display name for before/after input
  • title: explicit diff title
  • ttlSeconds: viewer artifact lifetime
  • baseUrl: override the gateway base URL used in the returned viewer link

​
Plugin defaults

Set plugin-wide defaults in ~/.openclaw/openclaw.json: 
{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          defaults: {
            fontFamily: "Fira Code",
            fontSize: 15,
            layout: "unified",
            wordWrap: true,
            background: true,
            theme: "dark",
            mode: "both",
          },
        },
      },
    },
  },
}
Supported defaults:
  • fontFamily
  • fontSize
  • layout
  • wordWrap
  • background
  • theme
  • mode
Explicit tool parameters override the plugin defaults.

​
Notes

  • Viewer pages are hosted locally by the gateway under /plugins/diffs/....
  • Viewer artifacts are ephemeral and stored locally.
  • mode: "image" uses a faster image-only render path and does not create a viewer URL.
  • PNG rendering requires a Chromium-compatible browser. If auto-detection is not enough, set browser.executablePath.
  • Diff rendering is powered by Diffs.