Use this file to discover all available pages before exploring further.

Diffs

text

diffs

is an optional plugin tool with short built-in system guidance and a companion skill that turns change content into a read-only diff artifact for agents.

It accepts either:

text
before
and
text
after
text
a unified
text
patch

It can return:

a gateway viewer URL for canvas presentation
a rendered file path (PNG or PDF) for message delivery
both outputs in one call

When enabled, the plugin prepends concise usage guidance into system-prompt space and also exposes a detailed skill for cases where the agent needs fuller instructions.

Quick start

Enable the plugin

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

Pick a mode

Canvas-first flows: agents call `diffs` with `mode: "view"` and open `details.viewerUrl` with `canvas present`.


text
  <Tab title="file">
    Chat file delivery: agents call `diffs` with `mode: "file"` and send `details.filePath` with `message` using `path` or `filePath`.
  </Tab>

  <Tab title="both">
    Combined: agents call `diffs` with `mode: "both"` to get both artifacts in one call.
  </Tab>
</Tabs>

Disable built-in system guidance

If you want to keep the

text

diffs

tool enabled but disable its built-in system-prompt guidance, set

text

plugins.entries.diffs.hooks.allowPromptInjection

text

false


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

This blocks the diffs plugin's

text

before_prompt_build

hook while keeping the plugin, tool, and companion skill available.

If you want to disable both the guidance and the tool, disable the plugin instead.

Typical agent workflow

Call diffs

Agent calls the `diffs` tool with input.

Read details

Agent reads `details` fields from the response.

Present

Agent either opens `details.viewerUrl` with `canvas present`, sends `details.filePath` with `message` using `path` or `filePath`, or does both.

Input examples

```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" } ```

Tool input reference

All fields are optional unless noted.

Original text. Required with `after` when `patch` is omitted. Updated text. Required with `before` when `patch` is omitted. Unified diff text. Mutually exclusive with `before` and `after`. Display filename for before and after mode. Language override hint for before and after mode. Unknown values fall back to plain text. Viewer title override. Output mode. Defaults to plugin default `defaults.mode`. Deprecated alias: `"image"` behaves like `"file"` and is still accepted for backward compatibility. Viewer theme. Defaults to plugin default `defaults.theme`. Diff layout. Defaults to plugin default `defaults.layout`. Expand unchanged sections when full context is available. Per-call option only (not a plugin default key). Rendered file format. Defaults to plugin default `defaults.fileFormat`. Quality preset for PNG or PDF rendering. Device scale override (`1`-`4`). Max render width in CSS pixels (`640`-`2400`). Artifact TTL in seconds for viewer and standalone file outputs. Max 21600. Viewer URL origin override. Overrides plugin `viewerBaseUrl`. Must be `http` or `https`, no query/hash.

Output details contract

The tool returns structured metadata under

text

details

Mode behavior summary:

Mode	What is returned
text `"view"`	Viewer fields only.
text `"file"`	File fields only, no viewer artifact.
text `"both"`	Viewer fields plus file fields. If file rendering fails, viewer still returns with text `fileError` and text `imageError` alias.

Collapsed unchanged sections

The viewer can show rows like
text
N unmodified lines
.
Expand controls on those rows are conditional and not guaranteed for every input kind.
Expand controls appear when the rendered diff has expandable context data, which is typical for before and after input.
For many unified patch inputs, omitted context bodies are not available in the parsed patch hunks, so the row can appear without expand controls. This is expected behavior.
text
expandUnchanged
applies only when expandable context exists.

Plugin defaults

Set plugin-wide defaults in

text

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

Supported defaults:

text
fontFamily
text
fontSize
text
lineSpacing
text
layout
text
showLineNumbers
text
diffIndicators
text
wordWrap
text
background
text
theme
text
fileFormat
text
fileQuality
text
fileScale
text
fileMaxWidth
text
mode

Explicit tool parameters override these defaults.

Persistent viewer URL config

Plugin-owned fallback for returned viewer links when a tool call does not pass `baseUrl`. Must be `http` or `https`, no query/hash.


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

Security config

`false`: non-loopback requests to viewer routes are denied. `true`: remote viewers are allowed if tokenized path is valid.


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

Artifact lifecycle and storage

Artifacts are stored under the temp subfolder:
text
$TMPDIR/openclaw-diffs
.
Viewer artifact metadata contains:
- random artifact ID (20 hex chars)
- random token (48 hex chars)
- text
  createdAt
  and
  text
  expiresAt
- stored
  text
  viewer.html
  path
Default artifact TTL is 30 minutes when not specified.
Maximum accepted viewer TTL is 6 hours.
Cleanup runs opportunistically after artifact creation.
Expired artifacts are deleted.
Fallback cleanup removes stale folders older than 24 hours when metadata is missing.

Viewer URL and network behavior

Viewer route:

text
/plugins/diffs/view/{artifactId}/{token}

Viewer assets:

text
/plugins/diffs/assets/viewer.js
text
/plugins/diffs/assets/viewer-runtime.js

The viewer document resolves those assets relative to the viewer URL, so an optional

text

baseUrl

path prefix is preserved for both asset requests too.

URL construction behavior:

If tool-call
text
baseUrl
is provided, it is used after strict validation.
Else if plugin
text
viewerBaseUrl
is configured, it is used.
Without either override, viewer URL defaults to loopback
text
127.0.0.1
.
If gateway bind mode is
text
custom
and
text
gateway.customBindHost
is set, that host is used.

text

baseUrl

rules:

Must be
text
http://
or
text
https://
.
Query and hash are rejected.
Origin plus optional base path is allowed.

Security model

Browser requirements for file mode

text

mode: "file"

and

text

mode: "both"

need a Chromium-compatible browser.

Resolution order:

Config

`browser.executablePath` in OpenClaw config.

Environment variables

* `OPENCLAW_BROWSER_EXECUTABLE_PATH` * `BROWSER_EXECUTABLE_PATH` * `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`

Platform fallback

Platform command/path discovery fallback.

Common failure text:

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

Fix by installing Chrome, Chromium, Edge, or Brave, or setting one of the executable path options above.

Troubleshooting

Operational guidance

Prefer
text
mode: "view"
for local interactive reviews in canvas.
Prefer
text
mode: "file"
for outbound chat channels that need an attachment.
Keep
text
allowRemoteViewer
disabled unless your deployment requires remote viewer URLs.
Set explicit short
text
ttlSeconds
for sensitive diffs.
Avoid sending secrets in diff input when not required.
If your channel compresses images aggressively (for example Telegram or WhatsApp), prefer PDF output (
text
fileFormat: "pdf"
).

OpenClaw Docs

Diffs

Quick start

Enable the plugin

Pick a mode

Disable built-in system guidance

Typical agent workflow

Call diffs

Read details

Present

Input examples

Tool input reference

Output details contract

Collapsed unchanged sections

Plugin defaults

Persistent viewer URL config

Security config

Artifact lifecycle and storage

Viewer URL and network behavior

Security model

Browser requirements for file mode

Config

Environment variables

Platform fallback

Troubleshooting

Operational guidance

note

Related