It accepts either:<\/p>\n It can return:<\/p>\n 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.<\/p>\n “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} This blocks the diffs plugin’s If you want to disable both the guidance and the tool, disable the plugin instead.<\/p>\n Before and after:<\/p>\n “`json theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} All fields are optional unless noted:<\/p>\n Validation and limits:<\/p>\n The tool returns structured metadata under Shared fields for modes that create a viewer:<\/p>\n File fields when PNG or PDF is rendered:<\/p>\n Mode behavior summary:<\/p>\n Set plugin-wide defaults in “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} Viewer route:<\/p>\n Viewer assets:<\/p>\n URL construction behavior:<\/p>\n Viewer hardening:<\/p>\n File rendering hardening:<\/p>\n Resolution order:<\/p>\n Common failure text:<\/p>\n Fix by installing Chrome, Chromium, Edge, or Brave, or setting one of the executable path options above.<\/p>\n Input validation errors:<\/p>\ndiffs<\/code> 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.<\/p>\n\n
before<\/code> and after<\/code> text<\/li>\npatch<\/code><\/li>\n<\/ul>\n\n
Quick start<\/h2>\n
\n
diffs<\/code> with mode: \"view\"<\/code> for canvas-first flows.<\/li>\ndiffs<\/code> with mode: \"file\"<\/code> for chat file delivery flows.<\/li>\ndiffs<\/code> with mode: \"both\"<\/code> when you need both artifacts.<\/li>\n<\/ol>\nEnable the plugin<\/h2>\n
\n{
\n plugins: {
\n entries: {
\n diffs: {
\n enabled: true,
\n },
\n },
\n },
\n}<\/p>\n\n## Disable built-in system guidance\n\nIf you want to keep the `diffs` tool enabled but disable its built-in system-prompt guidance, set `plugins.entries.diffs.hooks.allowPromptInjection` to `false`:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n plugins: {\n entries: {\n diffs: {\n enabled: true,\n hooks: {\n allowPromptInjection: false,\n },\n },\n },\n },\n}\n<\/code><\/pre>\nbefore_prompt_build<\/code> hook while keeping the plugin, tool, and companion skill available.<\/p>\nTypical agent workflow<\/h2>\n
\n
diffs<\/code>.<\/li>\ndetails<\/code> fields.<\/li>\n
\n * opens details.viewerUrl<\/code> with canvas present<\/code>
\n * sends details.filePath<\/code> with message<\/code> using path<\/code> or filePath<\/code>
\n * does both<\/li>\n<\/ol>\nInput examples<\/h2>\n
\n{
\n “before”: “# HellonnOne”,
\n “after”: “# HellonnTwo”,
\n “path”: “docs\/example.md”,
\n “mode”: “view”
\n}<\/p>\n\nPatch:\n\n```json theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n "patch": "diff --git a\/src\/example.ts b\/src\/example.tsn--- a\/src\/example.tsn+++ b\/src\/example.tsn@@ -1 +1 @@n-const x = 1;n+const x = 2;n",\n "mode": "both"\n}\n<\/code><\/pre>\nTool input reference<\/h2>\n
\n
before<\/code> (string<\/code>): original text. Required with after<\/code> when patch<\/code> is omitted.<\/li>\nafter<\/code> (string<\/code>): updated text. Required with before<\/code> when patch<\/code> is omitted.<\/li>\npatch<\/code> (string<\/code>): unified diff text. Mutually exclusive with before<\/code> and after<\/code>.<\/li>\npath<\/code> (string<\/code>): display filename for before and after mode.<\/li>\nlang<\/code> (string<\/code>): language override hint for before and after mode.<\/li>\ntitle<\/code> (string<\/code>): viewer title override.<\/li>\nmode<\/code> (\"view\" | \"file\" | \"both\"<\/code>): output mode. Defaults to plugin default defaults.mode<\/code>.
\n Deprecated alias: \"image\"<\/code> behaves like \"file\"<\/code> and is still accepted for backward compatibility.<\/li>\ntheme<\/code> (\"light\" | \"dark\"<\/code>): viewer theme. Defaults to plugin default defaults.theme<\/code>.<\/li>\nlayout<\/code> (\"unified\" | \"split\"<\/code>): diff layout. Defaults to plugin default defaults.layout<\/code>.<\/li>\nexpandUnchanged<\/code> (boolean<\/code>): expand unchanged sections when full context is available. Per-call option only (not a plugin default key).<\/li>\nfileFormat<\/code> (\"png\" | \"pdf\"<\/code>): rendered file format. Defaults to plugin default defaults.fileFormat<\/code>.<\/li>\nfileQuality<\/code> (\"standard\" | \"hq\" | \"print\"<\/code>): quality preset for PNG or PDF rendering.<\/li>\nfileScale<\/code> (number<\/code>): device scale override (1<\/code>–4<\/code>).<\/li>\nfileMaxWidth<\/code> (number<\/code>): max render width in CSS pixels (640<\/code>–2400<\/code>).<\/li>\nttlSeconds<\/code> (number<\/code>): viewer artifact TTL in seconds. Default 1800, max 21600.<\/li>\nbaseUrl<\/code> (string<\/code>): viewer URL origin override. Must be http<\/code> or https<\/code>, no query\/hash.<\/li>\n<\/ul>\n\n
before<\/code> and after<\/code> each max 512 KiB.<\/li>\npatch<\/code> max 2 MiB.<\/li>\npath<\/code> max 2048 bytes.<\/li>\nlang<\/code> max 128 bytes.<\/li>\ntitle<\/code> max 1024 bytes.<\/li>\npatch<\/code> and before<\/code> or after<\/code> together are rejected.<\/li>\nfileQuality: \"standard\"<\/code>: max 8 MP (8,000,000 rendered pixels).<\/li>\nfileQuality: \"hq\"<\/code>: max 14 MP (14,000,000 rendered pixels).<\/li>\nfileQuality: \"print\"<\/code>: max 24 MP (24,000,000 rendered pixels).<\/li>\nOutput details contract<\/h2>\n
details<\/code>.<\/p>\n\n
artifactId<\/code><\/li>\nviewerUrl<\/code><\/li>\nviewerPath<\/code><\/li>\ntitle<\/code><\/li>\nexpiresAt<\/code><\/li>\ninputKind<\/code><\/li>\nfileCount<\/code><\/li>\nmode<\/code><\/li>\ncontext<\/code> (agentId<\/code>, sessionId<\/code>, messageChannel<\/code>, agentAccountId<\/code> when available)<\/li>\n<\/ul>\n\n
artifactId<\/code><\/li>\nexpiresAt<\/code><\/li>\nfilePath<\/code><\/li>\npath<\/code> (same value as filePath<\/code>, for message tool compatibility)<\/li>\nfileBytes<\/code><\/li>\nfileFormat<\/code><\/li>\nfileQuality<\/code><\/li>\nfileScale<\/code><\/li>\nfileMaxWidth<\/code><\/li>\n<\/ul>\n\n
mode: \"view\"<\/code>: viewer fields only.<\/li>\nmode: \"file\"<\/code>: file fields only, no viewer artifact.<\/li>\nmode: \"both\"<\/code>: viewer fields plus file fields. If file rendering fails, viewer still returns with fileError<\/code>.<\/li>\n<\/ul>\nCollapsed unchanged sections<\/h2>\n
\n
N unmodified lines<\/code>.<\/li>\nexpandUnchanged<\/code> applies only when expandable context exists.<\/li>\n<\/ul>\nPlugin defaults<\/h2>\n
~\/.openclaw\/openclaw.json<\/code>:<\/p>\n
\n{
\n plugins: {
\n entries: {
\n diffs: {
\n enabled: true,
\n config: {
\n defaults: {
\n fontFamily: “Fira Code”,
\n fontSize: 15,
\n lineSpacing: 1.6,
\n layout: “unified”,
\n showLineNumbers: true,
\n diffIndicators: “bars”,
\n wordWrap: true,
\n background: true,
\n theme: “dark”,
\n fileFormat: “png”,
\n fileQuality: “standard”,
\n fileScale: 2,
\n fileMaxWidth: 960,
\n mode: “both”,
\n },
\n },
\n },
\n },
\n },
\n}<\/p>\n\nSupported defaults:\n\n* `fontFamily`\n* `fontSize`\n* `lineSpacing`\n* `layout`\n* `showLineNumbers`\n* `diffIndicators`\n* `wordWrap`\n* `background`\n* `theme`\n* `fileFormat`\n* `fileQuality`\n* `fileScale`\n* `fileMaxWidth`\n* `mode`\n\nExplicit tool parameters override these defaults.\n\n## Security config\n\n* `security.allowRemoteViewer` (`boolean`, default `false`)\n * `false`: non-loopback requests to viewer routes are denied.\n * `true`: remote viewers are allowed if tokenized path is valid.\n\nExample:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n plugins: {\n entries: {\n diffs: {\n enabled: true,\n config: {\n security: {\n allowRemoteViewer: false,\n },\n },\n },\n },\n },\n}\n<\/code><\/pre>\nArtifact lifecycle and storage<\/h2>\n
\n
$TMPDIR\/openclaw-diffs<\/code>.<\/li>\ncreatedAt<\/code> and expiresAt<\/code><\/li>\nviewer.html<\/code> path<\/li>\nViewer URL and network behavior<\/h2>\n
\n
\/plugins\/diffs\/view\/{artifactId}\/{token}<\/code><\/li>\n<\/ul>\n\n
\/plugins\/diffs\/assets\/viewer.js<\/code><\/li>\n\/plugins\/diffs\/assets\/viewer-runtime.js<\/code><\/li>\n<\/ul>\n\n
baseUrl<\/code> is provided, it is used after strict validation.<\/li>\nbaseUrl<\/code>, viewer URL defaults to loopback 127.0.0.1<\/code>.<\/li>\ncustom<\/code> and gateway.customBindHost<\/code> is set, that host is used.<\/li>\n<\/ul>\nbaseUrl<\/code> rules:<\/p>\n\n
http:\/\/<\/code> or https:\/\/<\/code>.<\/li>\nSecurity model<\/h2>\n
\n
default-src 'none'<\/code><\/li>\nconnect-src<\/code><\/li>\n429 Too Many Requests<\/code>)<\/li>\n<\/ul>\n\n
http:\/\/127.0.0.1\/plugins\/diffs\/assets\/*<\/code> are allowed.<\/li>\nBrowser requirements for file mode<\/h2>\n
mode: \"file\"<\/code> and mode: \"both\"<\/code> need a Chromium-compatible browser.<\/p>\n\n
browser.executablePath<\/code> in OpenClaw config.<\/li>\n
\n * OPENCLAW_BROWSER_EXECUTABLE_PATH<\/code>
\n * BROWSER_EXECUTABLE_PATH<\/code>
\n * PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH<\/code><\/li>\n\n
Diff PNG\/PDF rendering requires a Chromium-compatible browser...<\/code><\/li>\n<\/ul>\nTroubleshooting<\/h2>\n
\n