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

openclaw plugins install diffs

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

# 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

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

# Tool input reference

All fields are optional unless noted.

# Output details contract

The tool returns structured metadata under details.

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
• Plugins
• Tools overview