> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Differenze

`diffs` è uno strumento Plugin opzionale con una breve guida di sistema integrata e una Skill associata che trasforma il contenuto delle modifiche in un artefatto diff di sola lettura per gli agenti.

Accetta alternativamente:

* testo `before` e `after`
* una `patch` unificata

Può restituire:

* un URL del visualizzatore Gateway per la presentazione su canvas
* un percorso di file renderizzato (PNG o PDF) per la consegna dei messaggi
* entrambi gli output in una sola chiamata

Quando è abilitato, il Plugin antepone una guida d'uso concisa nello spazio del prompt di sistema ed espone anche una Skill dettagliata per i casi in cui l'agente abbia bisogno di istruzioni più complete.

## Avvio rapido

<Steps>
  <Step title="Install the plugin">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins install diffs
    ```
  </Step>

  <Step title="Enable the plugin">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      plugins: {
        entries: {
          diffs: {
            enabled: true,
          },
        },
      },
    }
    ```
  </Step>

  <Step title="Pick a mode">
    <Tabs>
      <Tab title="view">
        Flussi orientati al canvas: gli agenti chiamano `diffs` con `mode: "view"` e aprono `details.viewerUrl` con `canvas present`.
      </Tab>

      <Tab title="file">
        Consegna di file in chat: gli agenti chiamano `diffs` con `mode: "file"` e inviano `details.filePath` con `message` usando `path` o `filePath`.
      </Tab>

      <Tab title="both">
        Combinato: gli agenti chiamano `diffs` con `mode: "both"` per ottenere entrambi gli artefatti in una sola chiamata.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Disabilitare la guida di sistema integrata

Se vuoi mantenere abilitato lo strumento `diffs` ma disabilitare la sua guida integrata nel prompt di sistema, imposta `plugins.entries.diffs.hooks.allowPromptInjection` su `false`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
      },
    },
  },
}
```

Questo blocca l'hook `before_prompt_build` del Plugin diffs mantenendo disponibili il Plugin, lo strumento e la Skill associata.

Se vuoi disabilitare sia la guida sia lo strumento, disabilita invece il Plugin.

## Flusso di lavoro tipico dell'agente

<Steps>
  <Step title="Call diffs">
    L'agente chiama lo strumento `diffs` con l'input.
  </Step>

  <Step title="Read details">
    L'agente legge i campi `details` dalla risposta.
  </Step>

  <Step title="Present">
    L'agente apre `details.viewerUrl` con `canvas present`, invia `details.filePath` con `message` usando `path` o `filePath`, oppure fa entrambe le cose.
  </Step>
</Steps>

## Esempi di input

<Tabs>
  <Tab title="Before and after">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "before": "# Hello\n\nOne",
      "after": "# Hello\n\nTwo",
      "path": "docs/example.md",
      "mode": "view"
    }
    ```
  </Tab>

  <Tab title="Patch">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "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"
    }
    ```
  </Tab>
</Tabs>

## Riferimento dell'input dello strumento

Tutti i campi sono opzionali, salvo diversa indicazione.

<ParamField path="before" type="string">
  Testo originale. Obbligatorio con `after` quando `patch` è omesso.
</ParamField>

<ParamField path="after" type="string">
  Testo aggiornato. Obbligatorio con `before` quando `patch` è omesso.
</ParamField>

<ParamField path="patch" type="string">
  Testo diff unificato. Mutuamente esclusivo con `before` e `after`.
</ParamField>

<ParamField path="path" type="string">
  Nome file visualizzato per la modalità before e after.
</ParamField>

<ParamField path="lang" type="string">
  Suggerimento di override della lingua per la modalità before e after. I valori sconosciuti e le lingue al di fuori del set predefinito del visualizzatore ripiegano sul testo normale, a meno che il Plugin
  Diff Viewer Language Pack non sia installato.
</ParamField>

<ParamField path="title" type="string">
  Override del titolo del visualizzatore.
</ParamField>

<ParamField path="mode" type="&#x22;view&#x22; | &#x22;file&#x22; | &#x22;both&#x22;">
  Modalità di output. Il valore predefinito è il valore predefinito del Plugin `defaults.mode`. Alias deprecato: `"image"` si comporta come `"file"` ed è ancora accettato per compatibilità all'indietro.
</ParamField>

<ParamField path="theme" type="&#x22;light&#x22; | &#x22;dark&#x22;">
  Tema del visualizzatore. Il valore predefinito è il valore predefinito del Plugin `defaults.theme`.
</ParamField>

<ParamField path="layout" type="&#x22;unified&#x22; | &#x22;split&#x22;">
  Layout del diff. Il valore predefinito è il valore predefinito del Plugin `defaults.layout`.
</ParamField>

<ParamField path="expandUnchanged" type="boolean">
  Espande le sezioni non modificate quando il contesto completo è disponibile. Opzione solo per singola chiamata (non una chiave predefinita del Plugin).
</ParamField>

<ParamField path="fileFormat" type="&#x22;png&#x22; | &#x22;pdf&#x22;">
  Formato del file renderizzato. Il valore predefinito è il valore predefinito del Plugin `defaults.fileFormat`.
</ParamField>

<ParamField path="fileQuality" type="&#x22;standard&#x22; | &#x22;hq&#x22; | &#x22;print&#x22;">
  Preset di qualità per il rendering PNG o PDF.
</ParamField>

<ParamField path="fileScale" type="number">
  Override della scala del dispositivo (`1`-`4`).
</ParamField>

<ParamField path="fileMaxWidth" type="number">
  Larghezza massima di rendering in pixel CSS (`640`-`2400`).
</ParamField>

<ParamField path="ttlSeconds" type="number" default="1800">
  TTL dell'artefatto in secondi per gli output del visualizzatore e dei file autonomi. Massimo 21600.
</ParamField>

<ParamField path="baseUrl" type="string">
  Override dell'origine dell'URL del visualizzatore. Sovrascrive `viewerBaseUrl` del Plugin. Deve essere `http` o `https`, senza query/hash.
</ParamField>

<AccordionGroup>
  <Accordion title="Legacy input aliases">
    Ancora accettati per compatibilità all'indietro:

    * `format` -> `fileFormat`
    * `imageFormat` -> `fileFormat`
    * `imageQuality` -> `fileQuality`
    * `imageScale` -> `fileScale`
    * `imageMaxWidth` -> `fileMaxWidth`
  </Accordion>

  <Accordion title="Validation and limits">
    * `before` e `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` o `after` viene rifiutato.
    * Limiti di sicurezza per i file renderizzati (si applicano a PNG e PDF):
      * `fileQuality: "standard"`: massimo 8 MP (8.000.000 pixel renderizzati).
      * `fileQuality: "hq"`: massimo 14 MP (14.000.000 pixel renderizzati).
      * `fileQuality: "print"`: massimo 24 MP (24.000.000 pixel renderizzati).
      * Anche il PDF ha un massimo di 50 pagine.
  </Accordion>
</AccordionGroup>

## Evidenziazione della sintassi

OpenClaw include l'evidenziazione della sintassi per linguaggi comuni di sorgente, configurazione e documentazione:

`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`.

Alias comuni come `js`, `ts`, `bash`, `md`, `yml`, `c++`, `dockerfile`, `rb`, `kt` e `ps1` sono normalizzati a quei linguaggi predefiniti.

Installa il Plugin Diff Viewer Language Pack per evidenziare altri linguaggi:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install clawhub:@openclaw/diffs-language-pack
```

Con il pacchetto linguistico disponibile, OpenClaw può evidenziare molti più linguaggi. Se il pacchetto non è installato, i file al di fuori dell'elenco predefinito vengono comunque visualizzati come testo semplice leggibile. Gli esempi includono 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 e file diff.

Consulta il [Plugin Diffs Language Pack](/it/plugins/reference/diffs-language-pack) per i dettagli e i [linguaggi Shiki](https://shiki.style/languages) per il catalogo upstream di linguaggi e alias di Shiki.

## Contratto dei dettagli di output

Lo strumento restituisce metadati strutturati sotto `details`.

<AccordionGroup>
  <Accordion title="Campi del visualizzatore">
    Campi condivisi per le modalità che creano un visualizzatore:

    * `artifactId`
    * `viewerUrl`
    * `viewerPath`
    * `title`
    * `expiresAt`
    * `inputKind`
    * `fileCount`
    * `mode`
    * `context` (`agentId`, `sessionId`, `messageChannel`, `agentAccountId` quando disponibile)
  </Accordion>

  <Accordion title="Campi file">
    Campi file quando viene renderizzato PNG o PDF:

    * `artifactId`
    * `expiresAt`
    * `filePath`
    * `path` (stesso valore di `filePath`, per compatibilità con lo strumento di messaggistica)
    * `fileBytes`
    * `fileFormat`
    * `fileQuality`
    * `fileScale`
    * `fileMaxWidth`
  </Accordion>

  <Accordion title="Alias di compatibilità">
    Restituiti anche per i chiamanti esistenti:

    * `format` (stesso valore di `fileFormat`)
    * `imagePath` (stesso valore di `filePath`)
    * `imageBytes` (stesso valore di `fileBytes`)
    * `imageQuality` (stesso valore di `fileQuality`)
    * `imageScale` (stesso valore di `fileScale`)
    * `imageMaxWidth` (stesso valore di `fileMaxWidth`)
  </Accordion>
</AccordionGroup>

Riepilogo del comportamento delle modalità:

| Modalità | Cosa viene restituito                                                                                                                                             |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"view"` | Solo campi del visualizzatore.                                                                                                                                    |
| `"file"` | Solo campi file, nessun artefatto del visualizzatore.                                                                                                             |
| `"both"` | Campi del visualizzatore più campi file. Se il rendering del file non riesce, il visualizzatore viene comunque restituito con `fileError` e l'alias `imageError`. |

## Sezioni invariate compresse

* Il visualizzatore può mostrare righe come `N unmodified lines`.
* I controlli di espansione su tali righe sono condizionali e non garantiti per ogni tipo di input.
* I controlli di espansione vengono visualizzati quando il diff renderizzato contiene dati di contesto espandibili, cosa tipica per input prima e dopo.
* Per molti input patch unificati, i corpi del contesto omessi non sono disponibili negli hunk della patch analizzata, quindi la riga può comparire senza controlli di espansione. Questo è il comportamento previsto.
* `expandUnchanged` si applica solo quando esiste un contesto espandibile.

## Valori predefiniti del Plugin

Imposta i valori predefiniti a livello di Plugin in `~/.openclaw/openclaw.json`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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,
          },
        },
      },
    },
  },
}
```

Valori predefiniti supportati:

* `fontFamily`
* `fontSize`
* `lineSpacing`
* `layout`
* `showLineNumbers`
* `diffIndicators`
* `wordWrap`
* `background`
* `theme`
* `fileFormat`
* `fileQuality`
* `fileScale`
* `fileMaxWidth`
* `mode`
* `ttlSeconds`

I parametri espliciti dello strumento sovrascrivono questi valori predefiniti.

### Configurazione URL persistente del visualizzatore

<ParamField path="viewerBaseUrl" type="string">
  Fallback di proprietà del Plugin per i link del visualizzatore restituiti quando una chiamata dello strumento non passa `baseUrl`. Deve essere `http` o `https`, senza query/hash.
</ParamField>

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          viewerBaseUrl: "https://gateway.example.com/openclaw",
        },
      },
    },
  },
}
```

## Configurazione di sicurezza

<ParamField path="security.allowRemoteViewer" type="boolean" default="false">
  `false`: le richieste non-loopback alle route del visualizzatore vengono negate. `true`: i visualizzatori remoti sono consentiti se il percorso tokenizzato è valido.
</ParamField>

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          security: {
            allowRemoteViewer: false,
          },
        },
      },
    },
  },
}
```

## Ciclo di vita e archiviazione degli artefatti

* Gli artefatti sono archiviati nella sottocartella temporanea: `$TMPDIR/openclaw-diffs`.
* I metadati dell'artefatto del visualizzatore contengono:
  * ID artefatto casuale (20 caratteri esadecimali)
  * token casuale (48 caratteri esadecimali)
  * `createdAt` ed `expiresAt`
  * percorso `viewer.html` archiviato
* La TTL predefinita dell'artefatto è di 30 minuti quando non specificata.
* La TTL massima accettata per il visualizzatore è di 6 ore.
* La pulizia viene eseguita in modo opportunistico dopo la creazione dell'artefatto.
* Gli artefatti scaduti vengono eliminati.
* La pulizia di fallback rimuove le cartelle obsolete più vecchie di 24 ore quando mancano i metadati.

## URL del visualizzatore e comportamento di rete

Route del visualizzatore:

* `/plugins/diffs/view/{artifactId}/{token}`

Asset del visualizzatore:

* `/plugins/diffs/assets/viewer.js`
* `/plugins/diffs/assets/viewer-runtime.js`
* `/plugins/diffs-language-pack/assets/viewer.js` quando il diff usa una lingua del Diff Viewer Language Pack

Il documento del visualizzatore risolve questi asset in modo relativo all'URL del visualizzatore, quindi un prefisso di percorso `baseUrl` facoltativo viene preservato anche per entrambe le richieste di asset.

Comportamento di costruzione dell'URL:

* Se viene fornito `baseUrl` della tool-call, viene usato dopo una validazione rigorosa.
* Altrimenti, se è configurato `viewerBaseUrl` del Plugin, viene usato.
* Senza nessuna delle due sostituzioni, l'URL del visualizzatore usa per impostazione predefinita il loopback `127.0.0.1`.
* Se la modalità di bind del Gateway è `custom` e `gateway.customBindHost` è impostato, viene usato quell'host.

Regole di `baseUrl`:

* Deve essere `http://` o `https://`.
* Query e hash vengono rifiutati.
* Sono consentiti origin più percorso base facoltativo.

## Modello di sicurezza

<AccordionGroup>
  <Accordion title="Irrigidimento del visualizzatore">
    * Solo loopback per impostazione predefinita.
    * Percorsi del visualizzatore tokenizzati con validazione rigorosa di ID e token.
    * CSP della risposta del visualizzatore:
      * `default-src 'none'`
      * script e asset solo da self
      * nessun `connect-src` in uscita
    * Throttling dei miss remoti quando l'accesso remoto è abilitato:
      * 40 errori ogni 60 secondi
      * lockout di 60 secondi (`429 Too Many Requests`)
  </Accordion>

  <Accordion title="Irrigidimento del rendering dei file">
    * L'instradamento delle richieste del browser per screenshot è deny-by-default.
    * Sono consentiti solo asset locali del visualizzatore da `http://127.0.0.1/plugins/diffs/assets/*`.
    * Le richieste di rete esterne sono bloccate.
  </Accordion>
</AccordionGroup>

## Requisiti del browser per la modalità file

`mode: "file"` e `mode: "both"` richiedono un browser compatibile con Chromium.

Ordine di risoluzione:

<Steps>
  <Step title="Configurazione">
    `browser.executablePath` nella configurazione di OpenClaw.
  </Step>

  <Step title="Variabili d'ambiente">
    * `OPENCLAW_BROWSER_EXECUTABLE_PATH`
    * `BROWSER_EXECUTABLE_PATH`
    * `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`
  </Step>

  <Step title="Fallback piattaforma">
    Fallback di rilevamento di comando/percorso della piattaforma.
  </Step>
</Steps>

Testo di errore comune:

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

Correggi installando Chrome, Chromium, Edge o Brave, oppure impostando una delle opzioni di percorso dell'eseguibile sopra indicate.

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Errori di validazione dell'input">
    * `Provide patch or both before and after text.` — includi sia `before` sia `after`, oppure fornisci `patch`.
    * `Provide either patch or before/after input, not both.` — non mescolare le modalità di input.
    * `Invalid baseUrl: ...` — usa un origin `http(s)` con percorso facoltativo, senza query/hash.
    * `{field} exceeds maximum size (...)` — riduci la dimensione del payload.
    * Rifiuto di patch di grandi dimensioni — riduci il numero di file della patch o le righe totali.
  </Accordion>

  <Accordion title="Accessibilità del visualizzatore">
    * L'URL del visualizzatore si risolve in `127.0.0.1` per impostazione predefinita.
    * Per scenari di accesso remoto:
      * imposta `viewerBaseUrl` del Plugin, oppure
      * passa `baseUrl` per ogni tool call, oppure
      * usa `gateway.bind=custom` e `gateway.customBindHost`
    * Se `gateway.trustedProxies` include loopback per un proxy sullo stesso host (ad esempio Tailscale Serve), le richieste raw al visualizzatore su loopback senza intestazioni client-IP inoltrate falliscono chiuse per progettazione.
    * Per quella topologia proxy:
      * preferisci `mode: "file"` o `mode: "both"` quando ti serve solo un allegato, oppure
      * abilita intenzionalmente `security.allowRemoteViewer` e imposta `viewerBaseUrl` del Plugin o passa un `baseUrl` proxy/pubblico quando ti serve un URL del visualizzatore condivisibile
    * Abilita `security.allowRemoteViewer` solo quando intendi consentire l'accesso esterno al visualizzatore.
  </Accordion>

  <Accordion title="La riga delle righe non modificate non ha pulsante di espansione">
    Questo può accadere per l'input patch quando la patch non contiene contesto espandibile. È previsto e non indica un errore del visualizzatore.
  </Accordion>

  <Accordion title="Artefatto non trovato">
    * Artefatto scaduto a causa della TTL.
    * Token o percorso modificato.
    * La pulizia ha rimosso dati obsoleti.
  </Accordion>
</AccordionGroup>

## Indicazioni operative

* Preferisci `mode: "view"` per revisioni interattive locali nel canvas.
* Preferisci `mode: "file"` per canali chat in uscita che richiedono un allegato.
* Mantieni `allowRemoteViewer` disabilitato salvo che il tuo deployment richieda URL del visualizzatore remoti.
* Imposta `ttlSeconds` brevi espliciti per diff sensibili.
* Evita di inviare segreti nell'input del diff quando non necessario.
* Se il tuo canale comprime le immagini in modo aggressivo (ad esempio Telegram o WhatsApp), preferisci l'output PDF (`fileFormat: "pdf"`).

<Note>
  Motore di rendering dei diff basato su [Diffs](https://diffs.com).
</Note>

## Correlati

* [Browser](/it/tools/browser)
* [Plugin](/it/tools/plugin)
* [Panoramica degli strumenti](/it/tools)