OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Differenzen

diffs ist ein optionales gebündeltes Plugin-Tool, das Vorher-/Nachher-Text oder einen Unified Patch in ein schreibgeschütztes Diff-Artefakt umwandelt. Es stellt dem System-Prompt außerdem kurze Anweisungen für den Agenten voran und enthält ein begleitendes Skill mit ausführlicheren Anweisungen.

Eingabe: before- und after-Text oder ein Unified patch (gegenseitig ausschließend).

Ausgabe: eine Gateway-Viewer-URL für die Canvas-Darstellung, ein gerenderter PNG-/PDF-Dateipfad für die Nachrichtenzustellung oder beides.

Schnellstart

  • Plugin installieren

    bash
    openclaw plugins install diffs

  • Plugin aktivieren

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

  • Modus auswählen

    view

    Canvas-orientierte Abläufe: Agenten rufen diffs mit mode: "view" auf und öffnen details.viewerUrl mit canvas present.

    file

    Dateizustellung im Chat: Agenten rufen diffs mit mode: "file" auf und senden details.filePath mit message unter Verwendung von path oder filePath.

    both

    Kombiniert (Standard): Agenten rufen diffs mit mode: "both" auf, um beide Artefakte mit einem einzigen Aufruf zu erhalten.

    • Integrierte Systemanweisungen deaktivieren

    Um das Tool beizubehalten, aber die vorangestellten System-Prompt-Anweisungen zu entfernen, setzen Sie plugins.entries.diffs.hooks.allowPromptInjection auf false:

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

    Dadurch wird der Hook before_prompt_build des Plugins blockiert, während das Tool und das Skill verfügbar bleiben. Um sowohl die Anweisungen als auch das Tool zu deaktivieren, deaktivieren Sie stattdessen das Plugin.

    Referenz der Tool-Eingaben

    Alle Felder sind optional, sofern nicht anders angegeben.

    beforestring

    Ursprünglicher Text. Zusammen mit after erforderlich, wenn patch weggelassen wird.

    afterstring

    Aktualisierter Text. Zusammen mit before erforderlich, wenn patch weggelassen wird.

    patchstring

    Unified-Diff-Text. Schließt sich gegenseitig mit before und after aus.

    pathstring

    Angezeigter Dateiname für den Vorher-/Nachher-Modus.

    langstring

    Hinweis zum Überschreiben der Sprache für den Vorher-/Nachher-Modus. Unbekannte Werte und Sprachen außerhalb des standardmäßigen Viewer-Satzes fallen auf einfachen Text zurück, sofern das Diff Viewer Language Pack Plugin nicht installiert ist.

    titlestring

    Überschreibung des Viewer-Titels.

    mode"view" | "file" | "both"

    Ausgabemodus. Verwendet standardmäßig den Plugin-Standardwert defaults.mode (both). Veralteter Alias: "image" verhält sich identisch zu "file".

    theme"light" | "dark"

    Viewer-Design. Verwendet standardmäßig den Plugin-Standardwert defaults.theme.

    layout"unified" | "split"

    Diff-Layout. Verwendet standardmäßig den Plugin-Standardwert defaults.layout.

    expandUnchangedboolean

    Unveränderte Abschnitte erweitern, wenn der vollständige Kontext verfügbar ist. Nur eine Option pro Aufruf (kein Plugin-Standardschlüssel).

    fileFormat"png" | "pdf"

    Gerendertes Dateiformat. Verwendet standardmäßig den Plugin-Standardwert defaults.fileFormat.

    fileQuality"standard" | "hq" | "print"

    Qualitätsvoreinstellung für das PNG-/PDF-Rendering.

    fileScalenumber

    Überschreibung des Geräteskalierungsfaktors (1-4).

    fileMaxWidthnumber

    Maximale Renderbreite in CSS-Pixeln (640-2400).

    ttlSecondsnumberdefault: 1800

    Artefakt-TTL in Sekunden für Viewer- und eigenständige Dateiausgaben. Maximal 21600.

    baseUrlstring

    Überschreibung des Ursprungs der Viewer-URL. Überschreibt das Plugin-Feld viewerBaseUrl. Muss http oder https sein, ohne Abfragezeichenfolge/Hash.

    Validierung und Grenzwerte
    • before/after: jeweils maximal 512 KiB.
    • patch: maximal 2 MiB.
    • path: maximal 2048 Byte.
    • lang: maximal 128 Byte.
    • title: maximal 1024 Byte.
    • Obergrenze für die Patch-Komplexität: maximal 128 Dateien und insgesamt 120000 Zeilen.
    • patch zusammen mit before/after wird abgelehnt.
    • Sicherheitsgrenzwerte für gerenderte Dateien (PNG und PDF):
      • fileQuality: "standard": maximal 8 MP (8,000,000 gerenderte Pixel).
      • fileQuality: "hq": maximal 14 MP.
      • fileQuality: "print": maximal 24 MP.
      • PDF ist außerdem auf 50 Seiten begrenzt.

    Syntaxhervorhebung

    Integrierte Sprachen:

    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 und toml.

    Gängige Aliase (js, ts, bash, md, yml, c++, dockerfile, rb, kt, ps1 usw.) werden auf diese Sprachen normalisiert.

    Installieren Sie das Diff Viewer Language Pack Plugin für weitere Sprachen (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 und weitere):

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

    Ohne das Paket werden nicht unterstützte Sprachen weiterhin als lesbarer einfacher Text gerendert. Im Diffs Language Pack Plugin und unter Shiki-Sprachen finden Sie den Upstream-Katalog.

    Vertrag für Ausgabedetails

    Alle erfolgreichen Ergebnisse enthalten changed: Bei identischer Vorher-/Nachher-Eingabe wird false zurückgegeben, ohne ein Artefakt zu erstellen; gerenderte Ergebnisse geben true zurück.

    Viewer-Felder (Modi view und both)
    • changed
    • artifactId
    • viewerUrl
    • viewerPath
    • title
    • expiresAt
    • inputKind
    • fileCount
    • mode
    • context (agentId, sessionId, messageChannel, agentAccountId, sofern verfügbar)
    Dateifelder (Modi file und both)
    • changed
    • artifactId
    • expiresAt
    • filePath
    • path (derselbe Wert wie filePath, zur Kompatibilität mit dem Nachrichten-Tool)
    • fileBytes
    • fileFormat
    • fileQuality
    • fileScale
    • fileMaxWidth
    Modus Rückgabe
    "view" Nur Viewer-Felder.
    "file" Nur Dateifelder, kein Viewer-Artefakt.
    "both" Viewer-Felder plus Dateifelder. Wenn das Datei-Rendering fehlschlägt, wird der Viewer dennoch mit fileError zurückgegeben.

    Eingeklappte unveränderte Abschnitte

    Der Viewer zeigt Zeilen wie N unmodified lines an. Steuerelemente zum Erweitern erscheinen nur, wenn der gerenderte Diff erweiterbare Kontextdaten enthält (typischerweise bei Vorher-/Nachher-Eingaben). Bei vielen vereinheitlichten Patches fehlen die Kontextinhalte in den Hunks, sodass die Zeile ohne Steuerelement zum Erweitern erscheinen kann – dies ist erwartetes Verhalten und kein Fehler. expandUnchanged gilt nur, wenn erweiterbarer Kontext vorhanden ist.

    Patches, die mehr als eine Datei betreffen, beginnen mit einer Übersichtskarte der geänderten Dateien: Gesamtzahlen für +N / -N, Zahlen pro Datei, Kennzeichnungen für hinzugefügte/gelöschte/umbenannte Dateien und Ankerlinks, die direkt zu den einzelnen Dateien führen. Gerenderte PNG-/PDF-Dateien behalten die Zahlen in den Kopfzeilen der einzelnen Dateien bei, lassen jedoch die interaktiven Ansichtsumschalter weg, da diese in einer statischen Datei funktionslose Steuerelemente wären.

    Plugin-Standardeinstellungen

    Legen Sie Plugin-weite Standardeinstellungen in ~/.openclaw/openclaw.json fest:

    json5
    {  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,          },        },      },    },  },}

    Unterstützte defaults-Schlüssel: fontFamily, fontSize, lineSpacing, layout, showLineNumbers, diffIndicators, wordWrap, background, theme, fileFormat, fileQuality, fileScale, fileMaxWidth, mode, ttlSeconds. Explizite Parameter eines Tool-Aufrufs überschreiben diese Einstellungen.

    Konfiguration der persistenten Viewer-URL

    viewerBaseUrlstring

    Plugin-eigener Rückfallwert für zurückgegebene Viewer-Links, wenn bei einem Tool-Aufruf kein baseUrl übergeben wird. Muss http oder https verwenden, ohne Abfrageparameter oder Fragment.

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

    Sicherheitskonfiguration

    security.allowRemoteViewerbooleandefault: false

    false: Nicht-Loopback-Anfragen an Viewer-Routen werden abgelehnt. true: Remote-Viewer sind zulässig, wenn der tokenisierte Pfad gültig ist.

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

    Lebenszyklus und Speicherung von Artefakten

    • Artefakte befinden sich unter $TMPDIR/openclaw-diffs.
    • Die Viewer-Metadaten speichern eine zufällige Artefakt-ID mit 20 Hexadezimalzeichen, ein zufälliges Token mit 48 Hexadezimalzeichen, createdAt/expiresAt und den gespeicherten Pfad zu viewer.html.
    • Standard-TTL für Artefakte: 30 Minuten. Maximal akzeptierte TTL: 6 Stunden.
    • Die Bereinigung wird nach jedem Aufruf zum Erstellen eines Artefakts opportunistisch ausgeführt; abgelaufene Artefakte werden gelöscht.
    • Eine ersatzweise Bereinigung entfernt veraltete Ordner, die älter als 24 Stunden sind, wenn Metadaten fehlen.

    Viewer-URL und Netzwerkverhalten

    Viewer-Route: /plugins/diffs/view/{artifactId}/{token}

    Viewer-Ressourcen:

    • /plugins/diffs/assets/viewer.js
    • /plugins/diffs/assets/viewer-runtime.js
    • /plugins/diffs-language-pack/assets/viewer.js (nur wenn der Diff eine Sprache aus einem Sprachpaket verwendet)

    Das Viewer-Dokument löst diese Ressourcen relativ zur Viewer-URL auf, sodass ein optionales baseUrl-Pfadpräfix auch für Ressourcenanfragen übernommen wird.

    Reihenfolge der URL-Auflösung: baseUrl des Tool-Aufrufs (nach strenger Validierung) -> Plugin-viewerBaseUrl -> standardmäßig Loopback 127.0.0.1. Wenn der Gateway-Bindungsmodus custom ist und gateway.customBindHost festgelegt wurde, wird dieser Host anstelle von Loopback verwendet.

    Regeln für baseUrl: Muss http:// oder https:// verwenden; Abfrageparameter und Fragmente werden abgelehnt; Ursprung plus optionaler Basispfad ist zulässig.

    Sicherheitsmodell

    Absicherung des Viewers
    • Standardmäßig nur Loopback.
    • Tokenisierte Viewer-Pfade mit strenger Validierung der ID- und Token-Muster.
    • CSP der Viewer-Antwort: default-src 'none'; Skripte/Ressourcen nur vom eigenen Ursprung; kein ausgehendes connect-src.
    • Drosselung fehlgeschlagener Remote-Zugriffe bei aktiviertem Remote-Zugriff: 40 Fehlschläge innerhalb von 60 Sekunden lösen eine 60-sekündige Sperre aus (429 Too Many Requests).
    Absicherung der Dateidarstellung
    • Das Routing von Browseranfragen für Screenshots verweigert standardmäßig alle Anfragen.
    • Nur lokale Viewer-Ressourcen unter http://127.0.0.1/plugins/diffs/assets/* sind zulässig.
    • Externe Netzwerkanfragen werden blockiert.

    Browseranforderungen für den Dateimodus

    mode: "file" und mode: "both" benötigen einen Chromium-kompatiblen Browser.

    Auflösungsreihenfolge:

  • Konfiguration

    browser.executablePath in der OpenClaw-Konfiguration.

  • Umgebungsvariablen

    • OPENCLAW_BROWSER_EXECUTABLE_PATH
    • BROWSER_EXECUTABLE_PATH
    • PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH

  • Plattform-Fallback

    Übliche Installationspfade und PATH-Suchvorgänge für Chrome, Chromium, Edge und Brave.

    • Häufige Fehlermeldung: Diff PNG/PDF rendering requires a Chromium-compatible browser.... Beheben Sie dies, indem Sie Chrome, Chromium, Edge oder Brave installieren oder eine der oben genannten Optionen für den Pfad zur ausführbaren Datei festlegen.

    Fehlerbehebung

    Eingabevalidierungsfehler
    • Provide patch or both before and after text. -- Geben Sie sowohl before als auch after an oder stellen Sie patch bereit.
    • Provide either patch or before/after input, not both. -- Mischen Sie die Eingabemodi nicht.
    • Invalid baseUrl: ... -- Verwenden Sie einen http(s)-Ursprung mit optionalem Pfad, aber ohne Abfrageparameter oder Fragment.
    • {field} exceeds maximum size (...) -- Reduzieren Sie die Größe der Nutzdaten.
    • Ablehnung eines großen Patches -- Reduzieren Sie die Anzahl der Patch-Dateien oder die Gesamtzahl der Zeilen.
    Zugänglichkeit des Viewers
    • Die Viewer-URL wird standardmäßig zu 127.0.0.1 aufgelöst.
    • Legen Sie für den Remotezugriff entweder im Plugin viewerBaseUrl fest, übergeben Sie bei jedem Aufruf baseUrl oder verwenden Sie gateway.bind=custom mit gateway.customBindHost.
    • Wenn gateway.trustedProxies die Loopback-Adresse für einen Proxy auf demselben Host enthält (beispielsweise Tailscale Serve), schlagen direkte Loopback-Viewer-Anfragen ohne weitergeleitete Client-IP-Header standardmäßig sicher fehl.
    • Verwenden Sie für diese Proxy-Topologie vorzugsweise mode: "file"/"both" für einen Anhang oder aktivieren Sie gezielt security.allowRemoteViewer zusammen mit viewerBaseUrl im Plugin beziehungsweise einer Proxy-baseUrl, um einen teilbaren Viewer-Link bereitzustellen.
    • Aktivieren Sie security.allowRemoteViewer nur, wenn externer Viewer-Zugriff vorgesehen ist.
    Zeile mit unveränderten Zeilen hat keine Schaltfläche zum Aufklappen

    Erwartetes Verhalten bei Patch-Eingaben ohne aufklappbaren Kontext; kein Fehler des Viewers.

    Artefakt nicht gefunden
    • Das Artefakt ist aufgrund der TTL abgelaufen.
    • Token oder Pfad wurde geändert.
    • Bei der Bereinigung wurden veraltete Daten entfernt.

    Betriebshinweise

    • Verwenden Sie für lokale interaktive Überprüfungen im Canvas vorzugsweise mode: "view".
    • Verwenden Sie für ausgehende Chat-Kanäle, die einen Anhang benötigen, vorzugsweise mode: "file".
    • Lassen Sie allowRemoteViewer deaktiviert, sofern Ihre Bereitstellung keine URLs für den Remote-Viewer erfordert.
    • Legen Sie für vertrauliche Diffs einen expliziten kurzen Wert für ttlSeconds fest.
    • Vermeiden Sie es, Geheimnisse in der Diff-Eingabe zu senden, wenn dies nicht erforderlich ist.
    • Wenn Ihr Kanal Bilder stark komprimiert (beispielsweise Telegram oder WhatsApp), verwenden Sie vorzugsweise die PDF-Ausgabe (fileFormat: "pdf").

    Verwandte Themen

    Was this useful?
    On this page

    On this page