Diffs

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:

• before and after text
• a unified 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

Disable built-in system guidance

If you want to keep the diffs tool enabled but disable its built-in system-prompt guidance, set plugins.entries.diffs.hooks.allowPromptInjection to false:

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

This blocks the diffs plugin's 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

Input examples

Tool input reference

All fields are optional unless noted.

- `format` -> `fileFormat`
- `imageFormat` -> `fileFormat`
- `imageQuality` -> `fileQuality`
- `imageScale` -> `fileScale`
- `imageMaxWidth` -> `fileMaxWidth`

Output details contract

The tool returns structured metadata under details.

- `artifactId`
- `viewerUrl`
- `viewerPath`
- `title`
- `expiresAt`
- `inputKind`
- `fileCount`
- `mode`
- `context` (`agentId`, `sessionId`, `messageChannel`, `agentAccountId` when available)

- `artifactId`
- `expiresAt`
- `filePath`
- `path` (same value as `filePath`, for message tool compatibility)
- `fileBytes`
- `fileFormat`
- `fileQuality`
- `fileScale`
- `fileMaxWidth`

- `format` (same value as `fileFormat`)
- `imagePath` (same value as `filePath`)
- `imageBytes` (same value as `fileBytes`)
- `imageQuality` (same value as `fileQuality`)
- `imageScale` (same value as `fileScale`)
- `imageMaxWidth` (same value as `fileMaxWidth`)

Mode behavior summary:

Collapsed unchanged sections

• The viewer can show rows like 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.
• expandUnchanged applies only when expandable context exists.

Plugin defaults

Set plugin-wide defaults in ~/.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",
          },
        },
      },
    },
  },
}

Supported defaults:

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

Explicit tool parameters override these defaults.

Persistent viewer URL config

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

Security config

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

Artifact lifecycle and storage

• Artifacts are stored under the temp subfolder: $TMPDIR/openclaw-diffs.
• Viewer artifact metadata contains:
  • random artifact ID (20 hex chars)
  • random token (48 hex chars)
  • createdAt and expiresAt
  • stored 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:

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

Viewer assets:

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

The viewer document resolves those assets relative to the viewer URL, so an optional baseUrl path prefix is preserved for both asset requests too.

URL construction behavior:

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

baseUrl rules:

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

Security model

Browser requirements for file mode

mode: "file" and mode: "both" need a Chromium-compatible browser.

Resolution order:

Common failure 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 mode: "view" for local interactive reviews in canvas.
• Prefer mode: "file" for outbound chat channels that need an attachment.
• Keep allowRemoteViewer disabled unless your deployment requires remote viewer URLs.
• Set explicit short 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 (fileFormat: "pdf").

Related

• [Browser](/docs/openclaw-docs/tools/browser
• [Plugins](/docs/openclaw-docs/tools/plugin
• [Tools overview](/docs/openclaw-docs/tools