Unterschiede

diffs ist ein optionales Plugin-Tool mit kurzer integrierter Systemanleitung und einer begleitenden Skill, die Änderungsinhalte in ein schreibgeschütztes Diff-Artefakt für Agenten umwandelt.

Es akzeptiert entweder:

• Text für before und after
• einen vereinheitlichten patch

Es kann zurückgeben:

• eine Gateway-Viewer-URL für die Canvas-Darstellung
• einen gerenderten Dateipfad (PNG oder PDF) für die Nachrichtenzustellung
• beide Ausgaben in einem Aufruf

Wenn aktiviert, stellt das Plugin dem System-Prompt-Bereich eine knappe Nutzungsanleitung voran und stellt außerdem eine ausführliche Skill für Fälle bereit, in denen der Agent vollständigere Anweisungen benötigt.

# Schnellstart

openclaw plugins install diffs

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

# Integrierte Systemanleitung deaktivieren

Wenn Sie das Tool diffs aktiviert lassen, aber seine integrierte System-Prompt-Anleitung deaktivieren möchten, setzen Sie plugins.entries.diffs.hooks.allowPromptInjection auf false:

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

Dadurch wird der Hook before_prompt_build des diffs-Plugins blockiert, während Plugin, Tool und begleitende Skill verfügbar bleiben.

Wenn Sie sowohl die Anleitung als auch das Tool deaktivieren möchten, deaktivieren Sie stattdessen das Plugin.

# Typischer Agenten-Workflow

# Eingabebeispiele

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

# Referenz für Tool-Eingaben

Alle Felder sind optional, sofern nicht anders angegeben.

# Vertrag für Ausgabedetails

Das Tool gibt strukturierte Metadaten unter details zurück.

Zusammenfassung des Modusverhaltens:

# Eingeklappte unveränderte Abschnitte

• Der Viewer kann Zeilen wie N unmodified lines anzeigen.
• Erweiterungssteuerelemente in diesen Zeilen sind bedingt und nicht für jede Eingabeart garantiert.
• Erweiterungssteuerelemente erscheinen, wenn der gerenderte Diff erweiterbare Kontextdaten enthält, was für Vorher-Nachher-Eingaben typisch ist.
• Bei vielen vereinheitlichten Patch-Eingaben sind ausgelassene Kontextkörper in den geparsten Patch-Hunks nicht verfügbar, sodass die Zeile ohne Erweiterungssteuerelemente erscheinen kann. Dies ist erwartetes Verhalten.
• expandUnchanged gilt nur, wenn erweiterbarer Kontext vorhanden ist.

# Plugin-Standardeinstellungen

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

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

Unterstützte Standardeinstellungen:

• fontFamily
• fontSize
• lineSpacing
• layout
• showLineNumbers
• diffIndicators
• wordWrap
• background
• theme
• fileFormat
• fileQuality
• fileScale
• fileMaxWidth
• mode

Explizite Tool-Parameter überschreiben diese Standardeinstellungen.

# Persistente Viewer-URL-Konfiguration

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

# Sicherheitskonfiguration

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

# Artefakt-Lebenszyklus und Speicherung

• Artefakte werden im temporären Unterordner gespeichert: $TMPDIR/openclaw-diffs.
• Viewer-Artefaktmetadaten enthalten:
  • zufällige Artefakt-ID (20 Hex-Zeichen)
  • zufälliges Token (48 Hex-Zeichen)
  • createdAt und expiresAt
  • gespeicherter Pfad viewer.html
• Die Standard-Artefakt-TTL beträgt 30 Minuten, wenn nicht angegeben.
• Die maximal akzeptierte Viewer-TTL beträgt 6 Stunden.
• Die Bereinigung wird nach der Artefakterstellung opportunistisch ausgeführt.
• Abgelaufene Artefakte werden gelöscht.
• Die Fallback-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-Assets:

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js

Das Viewer-Dokument löst diese Assets relativ zur Viewer-URL auf, sodass ein optionales baseUrl-Pfadpräfix auch für beide Asset-Anfragen erhalten bleibt.

Verhalten bei der URL-Erstellung:

• Wenn baseUrl im Tool-Aufruf angegeben ist, wird es nach strenger Validierung verwendet.
• Andernfalls wird, wenn Plugin viewerBaseUrl konfiguriert ist, dieser Wert verwendet.
• Ohne eine der beiden Überschreibungen verwendet die Viewer-URL standardmäßig loopback 127.0.0.1.
• Wenn der Gateway-Bindemodus custom ist und gateway.customBindHost gesetzt ist, wird dieser Host verwendet.

baseUrl-Regeln:

• Muss http:// oder https:// sein.
• Query und Hash werden abgelehnt.
• Ursprung plus optionaler Basispfad ist erlaubt.

# Sicherheitsmodell

# Browser-Anforderungen für den Dateimodus

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

Auflösungsreihenfolge:

Häufiger Fehlertext:

• 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 ausführbaren Pfad festlegen.

# Fehlerbehebung

# Betriebliche Hinweise

• Bevorzugen Sie mode: "view" für lokale interaktive Reviews im Canvas.
• Bevorzugen Sie mode: "file" für ausgehende Chat-Kanäle, die einen Anhang benötigen.
• Lassen Sie allowRemoteViewer deaktiviert, sofern Ihre Bereitstellung keine Remote-Viewer-URLs erfordert.
• Legen Sie explizit kurze ttlSeconds für sensible Diffs fest.
• Vermeiden Sie es, Secrets in Diff-Eingaben zu senden, wenn dies nicht erforderlich ist.
• Wenn Ihr Kanal Bilder stark komprimiert (zum Beispiel Telegram oder WhatsApp), bevorzugen Sie PDF-Ausgabe (fileFormat: "pdf").

# Verwandt

• Browser
• Plugins
• Tools-Übersicht