Differenze

diffs è uno strumento opzionale di un plugin incluso che trasforma un testo precedente/successivo o una patch unificata in un artefatto diff di sola lettura. Anteposta inoltre brevi indicazioni per l’agente al prompt di sistema e include una skill complementare con istruzioni più complete. Input: testo before + after, oppure una patch unificata (opzioni mutuamente esclusive). Output: un URL del visualizzatore del Gateway per la presentazione su canvas, un percorso di file PNG/PDF sottoposto a rendering per la consegna tramite messaggio, oppure entrambi.

Avvio rapido

Installare il plugin

openclaw plugins install diffs

Abilitare il plugin

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

Scegliere una modalità

view
file
both

Flussi che privilegiano il canvas: gli agenti chiamano diffs con mode: "view" e aprono details.viewerUrl con canvas present.

Consegna di file in chat: gli agenti chiamano diffs con mode: "file" e inviano details.filePath con message usando path o filePath.

Modalità combinata (predefinita): gli agenti chiamano diffs con mode: "both" per ottenere entrambi gli artefatti con una sola chiamata.

Disabilitare le indicazioni di sistema integrate

Per mantenere lo strumento ma rimuovere le indicazioni anteposte al prompt di sistema, impostare plugins.entries.diffs.hooks.allowPromptInjection su false:

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

Questa impostazione blocca l’hook before_prompt_build del plugin, mantenendo disponibili lo strumento e la skill. Per disabilitare sia le indicazioni sia lo strumento, disabilitare invece il plugin.

Riferimento per l’input dello strumento

Tutti i campi sono facoltativi, salvo diversa indicazione.

string

Testo originale. Obbligatorio con after quando patch viene omesso.

string

Testo aggiornato. Obbligatorio con before quando patch viene omesso.

string

Testo del diff unificato. Mutuamente esclusivo con before e after.

string

Nome file visualizzato per la modalità precedente/successivo.

string

Indicazione per ignorare la lingua rilevata nella modalità precedente/successivo. I valori sconosciuti e le lingue non incluse nel gruppo predefinito del visualizzatore ricorrono al testo normale, a meno che non sia installato il plugin Diff Viewer Language Pack.

string

Titolo alternativo del visualizzatore.

"view" | "file" | "both"

Modalità di output. Il valore predefinito è quello del plugin defaults.mode (both). Alias deprecato: "image" si comporta in modo identico a "file".

"light" | "dark"

Tema del visualizzatore. Il valore predefinito è quello del plugin defaults.theme.

"unified" | "split"

Layout del diff. Il valore predefinito è quello del plugin defaults.layout.

boolean

Espande le sezioni invariate quando è disponibile il contesto completo. Opzione disponibile solo per singola chiamata (non è una chiave predefinita del plugin).

"png" | "pdf"

Formato del file sottoposto a rendering. Il valore predefinito è quello del plugin defaults.fileFormat.

"standard" | "hq" | "print"

Preimpostazione di qualità per il rendering PNG/PDF.

number

Valore alternativo per la scala del dispositivo (1-4).

number

Larghezza massima di rendering in pixel CSS (640-2400).

number

predefinito:"1800"

TTL dell’artefatto in secondi per il visualizzatore e gli output di file autonomi. Valore massimo: 21600.

string

Origine alternativa dell’URL del visualizzatore. Sostituisce il valore viewerBaseUrl del plugin. Deve essere http o https, senza query/hash.

Convalida e limiti

before/after: massimo 512 KiB ciascuno.
patch: massimo 2 MiB.
path: massimo 2048 byte.
lang: massimo 128 byte.
title: massimo 1024 byte.
Limite di complessità della patch: massimo 128 file e 120000 righe totali.
patch insieme a before/after viene rifiutato.
Limiti di sicurezza dei file sottoposti a rendering (PNG e PDF):
- fileQuality: "standard": massimo 8 MP (8,000,000 pixel sottoposti a rendering).
- fileQuality: "hq": massimo 14 MP.
- fileQuality: "print": massimo 24 MP.
- Anche i PDF sono limitati a 50 pagine.

Evidenziazione della sintassi

Linguaggi integrati: javascript, typescript, tsx, jsx, json, markdown, yaml, css, html, sh, python, go, rust, java, c, cpp, csharp, php, sql, docker, ruby, swift, kotlin, r, dart, lua, powershell, xml e toml. Gli alias comuni (js, ts, bash, md, yml, c++, dockerfile, rb, kt, ps1 e così via) vengono normalizzati in questi linguaggi. Installare il plugin Diff Viewer Language Pack per ulteriori linguaggi (Astro, Vue, Svelte, MDX, GraphQL, Terraform/HCL, Nix, Clojure, Elixir, Haskell, OCaml, Scala, Zig, Solidity, Verilog/VHDL, Fortran, MATLAB, LaTeX, Mermaid, Sass/Less/SCSS, Nginx, Apache, CSV, dotenv, INI, diff e altri):

openclaw plugins install clawhub:@openclaw/diffs-language-pack

Senza il pacchetto, i linguaggi non supportati vengono comunque visualizzati come testo normale leggibile. Consultare il plugin Diffs Language Pack e i linguaggi Shiki per il catalogo upstream.

Contratto dei dettagli di output

Tutti i risultati riusciti includono changed: un input precedente/successivo identico restituisce false senza creare un artefatto; i risultati sottoposti a rendering restituiscono true.

Campi del visualizzatore (modalità view e both)

changed
artifactId
viewerUrl
viewerPath
title
expiresAt
inputKind
fileCount
mode
context (agentId, sessionId, messageChannel, agentAccountId quando disponibili)

Campi del file (modalità file e both)

changed
artifactId
expiresAt
filePath
path (stesso valore di filePath, per la compatibilità con lo strumento per i messaggi)
fileBytes
fileFormat
fileQuality
fileScale
fileMaxWidth

Modalità	Restituisce
`"view"`	Solo i campi del visualizzatore.
`"file"`	Solo i campi del file, senza alcun artefatto del visualizzatore.
`"both"`	I campi del visualizzatore e quelli del file. Se il rendering del file non riesce, il visualizzatore viene comunque restituito con `fileError`.

Sezioni invariate compresse

Il visualizzatore mostra righe come N unmodified lines. I controlli di espansione vengono visualizzati solo quando il diff sottoposto a rendering dispone di dati contestuali espandibili (in genere per l’input precedente/successivo). Molte patch unificate omettono i corpi del contesto nei rispettivi hunk, quindi la riga può essere visualizzata senza un controllo di espansione: è il comportamento previsto, non un bug. expandUnchanged si applica solo quando esiste un contesto espandibile.

Navigazione tra più file

Le patch che interessano più di un file iniziano con una scheda riepilogativa dei file modificati: conteggi totali di +N / -N, conteggi per file, badge per file aggiunti/eliminati/rinominati e link di ancoraggio per passare direttamente a ciascun file. I file PNG/PDF sottoposti a rendering mantengono i conteggi nelle intestazioni dei singoli file, ma omettono i selettori interattivi della visualizzazione, poiché in un file statico non sono operativi.

Valori predefiniti del plugin

Impostare i valori predefiniti per l’intero plugin 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",
            ttlSeconds: 21600,
          },
        },
      },
    },
  },
}

Chiavi defaults supportate: fontFamily, fontSize, lineSpacing, layout, showLineNumbers, diffIndicators, wordWrap, background, theme, fileFormat, fileQuality, fileScale, fileMaxWidth, mode, ttlSeconds. I parametri espliciti della chiamata allo strumento hanno la precedenza su questi valori.

Configurazione persistente dell’URL del visualizzatore

string

Valore di ripiego gestito dal plugin per i link del visualizzatore restituiti quando una chiamata allo strumento non passa baseUrl. Deve essere http o https, senza query/hash.

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

Configurazione di sicurezza

boolean

predefinito:"false"

false: le richieste non loopback alle route del visualizzatore vengono negate. true: i visualizzatori remoti sono consentiti se il percorso con token è valido.

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

Ciclo di vita e archiviazione degli artefatti

Gli artefatti si trovano in $TMPDIR/openclaw-diffs.
I metadati del visualizzatore memorizzano un ID artefatto casuale di 20 caratteri esadecimali, un token casuale di 48 caratteri esadecimali, createdAt/expiresAt e il percorso viewer.html memorizzato.
TTL predefinito degli artefatti: 30 minuti. TTL massimo accettato: 6 ore.
La pulizia viene eseguita in modo opportunistico dopo ogni chiamata di creazione di un artefatto; gli artefatti scaduti vengono eliminati.
La scansione di ripiego rimuove le cartelle obsolete più vecchie di 24 ore quando mancano i metadati.

Comportamento dell’URL del visualizzatore e della rete

Route del visualizzatore: /plugins/diffs/view/{artifactId}/{token} Risorse del visualizzatore:

/plugins/diffs/assets/viewer.js
/plugins/diffs/assets/viewer-runtime.js
/plugins/diffs-language-pack/assets/viewer.js (solo quando il diff usa la lingua di un language pack)

Il documento del visualizzatore risolve queste risorse rispetto all’URL del visualizzatore, quindi anche un prefisso di percorso facoltativo baseUrl viene applicato alle richieste delle risorse. Ordine di risoluzione dell’URL: baseUrl della chiamata allo strumento (dopo una convalida rigorosa) -> viewerBaseUrl del Plugin -> valore predefinito di loopback 127.0.0.1. Se la modalità di associazione del Gateway è custom ed è impostato gateway.customBindHost, viene usato tale host anziché il loopback. Regole di baseUrl: deve essere http:// o https://; query e hash vengono rifiutati; sono consentiti un’origine e un percorso base facoltativo.

Modello di sicurezza

Protezione del visualizzatore

Per impostazione predefinita, solo loopback.
Percorsi del visualizzatore con token e convalida rigorosa dei formati di ID e token.
CSP della risposta del visualizzatore: default-src 'none'; script e risorse solo dall’origine stessa; nessuna richiesta connect-src in uscita.
Limitazione dei tentativi remoti non riusciti quando è abilitato l’accesso remoto: 40 errori in 60 secondi attivano un blocco di 60 secondi (429 Too Many Requests).

Protezione del rendering dei file

L’instradamento delle richieste del browser per gli screenshot nega tutto per impostazione predefinita.
Sono consentite solo le risorse locali del visualizzatore provenienti da http://127.0.0.1/plugins/diffs/assets/*.
Le richieste di rete esterne vengono bloccate.

Requisiti del browser per la modalità file

mode: "file" e mode: "both" richiedono un browser compatibile con Chromium. Ordine di risoluzione:

Configurazione

browser.executablePath nella configurazione di OpenClaw.

Variabili d'ambiente

OPENCLAW_BROWSER_EXECUTABLE_PATH
BROWSER_EXECUTABLE_PATH
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH

Fallback della piattaforma

Percorsi di installazione comuni e ricerche PATH per Chrome, Chromium, Edge e Brave.

Testo di errore comune: Diff PNG/PDF rendering requires a Chromium-compatible browser.... Per risolvere, installare Chrome, Chromium, Edge o Brave oppure impostare una delle opzioni del percorso dell’eseguibile indicate sopra.

Risoluzione dei problemi

Errori di convalida dell'input

Provide patch or both before and after text. — includere sia before sia after oppure fornire patch.
Provide either patch or before/after input, not both. — non combinare modalità di input diverse.
Invalid baseUrl: ... — usare un’origine http(s) con un percorso facoltativo, senza query/hash.
{field} exceeds maximum size (...) — ridurre le dimensioni del payload.
Rifiuto di una patch di grandi dimensioni — ridurre il numero di file della patch o il totale delle righe.

Accessibilità del visualizzatore

Per impostazione predefinita, l’URL del visualizzatore viene risolto in 127.0.0.1.
Per l’accesso remoto, impostare viewerBaseUrl del Plugin, passare baseUrl a ogni chiamata oppure usare gateway.bind=custom con gateway.customBindHost.
Se gateway.trustedProxies include il loopback per un proxy sullo stesso host (ad esempio Tailscale Serve), le richieste dirette al visualizzatore tramite loopback prive di intestazioni inoltrate con l’IP del client vengono rifiutate per impostazione predefinita, come previsto.
Per questa topologia proxy, è preferibile usare mode: "file"/"both" per un allegato oppure abilitare intenzionalmente security.allowRemoteViewer insieme a viewerBaseUrl del Plugin/un baseUrl del proxy per ottenere un link condivisibile al visualizzatore.
Abilitare security.allowRemoteViewer solo quando si intende consentire l’accesso esterno al visualizzatore.

La riga delle righe non modificate non presenta alcun pulsante di espansione

Comportamento previsto per un input patch privo di contesto espandibile; non si tratta di un errore del visualizzatore.

Artefatto non trovato

L’artefatto è scaduto a causa del TTL.
Il token o il percorso è cambiato.
La pulizia ha rimosso i dati obsoleti.

Indicazioni operative

Preferire mode: "view" per le revisioni interattive locali nel canvas.
Preferire mode: "file" per i canali di chat in uscita che richiedono un allegato.
Mantenere allowRemoteViewer disabilitato, a meno che la distribuzione non richieda URL remoti del visualizzatore.
Impostare esplicitamente un ttlSeconds breve per i diff sensibili.
Evitare di inviare segreti nell’input del diff quando non è necessario.
Se il canale comprime le immagini in modo aggressivo (ad esempio Telegram o WhatsApp), preferire l’output PDF (fileFormat: "pdf").

Motore di rendering dei diff basato su Diffs.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Avvio rapido

Disabilitare le indicazioni di sistema integrate

Riferimento per l’input dello strumento

Evidenziazione della sintassi

Contratto dei dettagli di output

Sezioni invariate compresse

Navigazione tra più file

Valori predefiniti del plugin

Configurazione persistente dell’URL del visualizzatore

Configurazione di sicurezza

Ciclo di vita e archiviazione degli artefatti

Comportamento dell’URL del visualizzatore e della rete

Modello di sicurezza

Requisiti del browser per la modalità file

Risoluzione dei problemi

Indicazioni operative

Argomenti correlati

​Avvio rapido

​Disabilitare le indicazioni di sistema integrate

​Riferimento per l’input dello strumento

​Evidenziazione della sintassi

​Contratto dei dettagli di output

​Sezioni invariate compresse

​Navigazione tra più file

​Valori predefiniti del plugin

​Configurazione persistente dell’URL del visualizzatore

​Configurazione di sicurezza

​Ciclo di vita e archiviazione degli artefatti

​Comportamento dell’URL del visualizzatore e della rete

​Modello di sicurezza

​Requisiti del browser per la modalità file

​Risoluzione dei problemi

​Indicazioni operative

​Argomenti correlati

Avvio rapido

Disabilitare le indicazioni di sistema integrate

Riferimento per l’input dello strumento

Evidenziazione della sintassi

Contratto dei dettagli di output

Sezioni invariate compresse

Navigazione tra più file

Valori predefiniti del plugin

Configurazione persistente dell’URL del visualizzatore

Configurazione di sicurezza

Ciclo di vita e archiviazione degli artefatti

Comportamento dell’URL del visualizzatore e della rete

Modello di sicurezza

Requisiti del browser per la modalità file

Risoluzione dei problemi

Indicazioni operative

Argomenti correlati