Diffs

diffs es una herramienta de complemento opcional con una guía del sistema integrada breve y una habilidad complementaria que convierte el contenido de cambios en un artefacto de diffs de solo lectura para agentes.

Acepta cualquiera:

texto before y after
un patch unificado

Puede devolver:

una URL de visor de puerta de enlace para la presentación en el lienzo
una ruta de archivo renderizada (PNG o PDF) para la entrega de mensajes
ambas salidas en una sola llamada

Cuando está habilitado, el complemento antepone una guía de uso concisa en el espacio del prompt del sistema y también expone una habilidad detallada para los casos en los que el agente necesita instrucciones más completas.

Inicio rápido

Instalar el complemento
Ventana de terminal
```
openclaw plugins install diffs
```

Habilitar el complemento

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

Elegir un modo
Flujos con prioridad de lienzo (Canvas): los agentes llaman a diffs con mode: "view" y abren details.viewerUrl con canvas present.

Deshabilitar la guía del sistema integrada

Si desea mantener la herramienta diffs habilitada pero desactivar su guía del sistema integrada, establezca plugins.entries.diffs.hooks.allowPromptInjection en false:

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

Esto bloquea el gancho (hook) before_prompt_build del complemento de diffs, manteniendo el complemento, la herramienta y la habilidad complementaria disponibles.

Si desea deshabilitar tanto la guía como la herramienta, deshabilite el complemento en su lugar.

Flujo de trabajo típico del agente

Llamar a diffs
El agente llama a la herramienta diffs con la entrada.
Leer detalles
El agente lee los campos details de la respuesta.
Presentar
El agente abre details.viewerUrl con canvas present, envía details.filePath con message usando path o filePath, o hace ambas cosas.

Ejemplos de entrada

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

Referencia de entrada de la herramienta

Todos los campos son opcionales a menos que se indique lo contrario.

Texto original. Obligatorio con `after` cuando se omite `patch`. Texto actualizado. Obligatorio con `before` cuando se omite `patch`. Texto diff unificado. Mutuamente excluyente con `before` y `after`. Nombre de archivo para mostrar en el modo antes y después. Sugerencia de anulación de idioma para el modo antes y después. Los valores desconocidos vuelven al texto sin formato. Anulación del título del visor. Modo de salida. Por defecto, predeterminado del complemento `defaults.mode`. Alias obsoleto: `"image"` se comporta como `"file"` y aún se acepta por compatibilidad con versiones anteriores. Tema del visor. Por defecto, predeterminado del complemento `defaults.theme`. Diseño del diff. Por defecto, predeterminado del complemento `defaults.layout`. Expandir secciones sin cambios cuando el contexto completo esté disponible. Opción solo por llamada (no una clave predeterminada del complemento). Formato de archivo renderizado. Por defecto, predeterminado del complemento `defaults.fileFormat`. Ajuste preestablecido de calidad para el renderizado de PNG o PDF. Anulación de escala del dispositivo (`1`-`4`). Ancho máximo de renderizado en píxeles CSS (`640`-`2400`). TTL del artefacto en segundos para la salida del visor y de archivos independientes. Máximo 21600. Anulación del origen de la URL del visor. Anula el complemento `viewerBaseUrl`. Debe ser `http` o `https`, sin consulta/hash.

Alias de entrada heredados

Todavía se aceptan por compatibilidad con versiones anteriores:

format -> fileFormat
imageFormat -> fileFormat
imageQuality -> fileQuality
imageScale -> fileScale
imageMaxWidth -> fileMaxWidth

Validación y límites

before y after con un máximo de 512 KiB cada uno.
patch con un máximo de 2 MiB.
path con un máximo de 2048 bytes.
lang con un máximo de 128 bytes.
title con un máximo de 1024 bytes.
Límite de complejidad del parche: máximo de 128 archivos y 120000 líneas en total.
patch y before o after juntos se rechazan.
Límites de seguridad de archivos renderizados (aplican a PNG y PDF):
- fileQuality: "standard": máximo de 8 MP (8,000,000 píxeles renderizados).
- fileQuality: "hq": máximo de 14 MP (14,000,000 píxeles renderizados).
- fileQuality: "print": máximo de 24 MP (24,000,000 píxeles renderizados).
- PDF también tiene un máximo de 50 páginas.

Contrato de detalles de salida

La herramienta devuelve metadatos estructurados bajo details.

Campos del visor

Campos compartidos para los modos que crean un visor:

artifactId
viewerUrl
viewerPath
title
expiresAt
inputKind
fileCount
mode
context (agentId, sessionId, messageChannel, agentAccountId cuando estén disponibles)

Campos de archivo

Campos de archivo cuando se representa PNG o PDF:

artifactId
expiresAt
filePath
path (mismo valor que filePath, para compatibilidad con la herramienta de mensajes)
fileBytes
fileFormat
fileQuality
fileScale
fileMaxWidth

Alias de compatibilidad

También se devuelve para los llamadores existentes:

format (mismo valor que fileFormat)
imagePath (mismo valor que filePath)
imageBytes (mismo valor que fileBytes)
imageQuality (mismo valor que fileQuality)
imageScale (mismo valor que fileScale)
imageMaxWidth (mismo valor que fileMaxWidth)

Resumen del comportamiento del modo:

Modo	Lo que se devuelve
`"view"`	Solo campos del visor.
`"file"`	Solo campos de archivo, sin artefacto del visor.
`"both"`	Campos del visor más campos de archivo. Si la representación del archivo falla, el visor aún se devuelve con el alias `fileError` y `imageError`.

Secciones sin cambios colapsadas

El visor puede mostrar filas como N unmodified lines.
Los controles de expansión en esas filas son condicionales y no se garantizan para cada tipo de entrada.
Los controles de expansión aparecen cuando el diff representado tiene datos de contexto expandibles, lo cual es típico para la entrada antes y después.
Para muchas entradas de parches unificados, los cuerpos de contexto omitidos no están disponibles en los fragmentos de parche analizados, por lo que la fila puede aparecer sin controles de expansión. Este es un comportamiento esperado.
expandUnchanged se aplica solo cuando existe contexto expandible.

Valores predeterminados del complemento

Establezca los valores predeterminados de todo el complemento en ~/.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,
          },
        },
      },
    },
  },
}

Valores predeterminados compatibles:

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

Los parámetros explícitos de la herramienta anulan estos valores predeterminados.

Configuración de URL del visor persistente

Alternativa propia del complemento para los enlaces del visor devueltos cuando una llamada a la herramienta no pasa `baseUrl`. Debe ser `http` o `https`, sin consulta/hash.

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

Configuración de seguridad

`false`: se deniegan las solicitudes que no son de bucle local a las rutas del visor. `true`: se permiten visores remotos si la ruta con token es válida.

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

Ciclo de vida y almacenamiento de artefactos

Los artefactos se almacenan en la subcarpeta temp: $TMPDIR/openclaw-diffs.
Los metadatos del artefacto del visor contienen:
- ID de artefacto aleatorio (20 caracteres hexadecimales)
- token aleatorio (48 caracteres hexadecimales)
- createdAt y expiresAt
- ruta viewer.html almacenada
El TTL predeterminado del artefacto es de 30 minutos cuando no se especifica.
El TTL máximo aceptado para el visor es de 6 horas.
La limpieza se ejecuta de manera oportunista después de la creación del artefacto.
Los artefactos caducados se eliminan.
La limpieza de respaldo elimina las carpetas obsoletas de más de 24 horas cuando faltan los metadatos.

URL del visor y comportamiento de red

Ruta del visor:

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

Activos del visor:

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

El documento del visor resuelve esos activos en relación con la URL del visor, por lo que también se conserva un prefijo de ruta baseUrl opcional para ambas solicitudes de activos.

Comportamiento de construcción de URL:

Si se proporciona baseUrl en la llamada a la herramienta, se usa después de una validación estricta.
De lo contrario, si el complemento viewerBaseUrl está configurado, se usa.
Sin ninguna anulación, la URL del visor predeterminada es el bucle local 127.0.0.1.
Si el modo de enlace de la puerta de enlace es custom y se establece gateway.customBindHost, se usa ese host.

Reglas de baseUrl:

Debe ser http:// o https://.
Se rechazan la consulta y el hash.
Se permite el origen más una ruta base opcional.

Modelo de seguridad

Endurecimiento del visor

Solo bucle local (loopback) de forma predeterminada.
Rutas del visor tokenizadas con validación estricta de ID y token.
CSP de respuesta del visor:
- default-src 'none'
- scripts y activos solo desde el propio origen (self)
- sin connect-src saliente
Limitación de fallos remotos cuando el acceso remoto está habilitado:
- 40 fallos por 60 segundos
- bloqueo de 60 segundos (429 Too Many Requests)

Endurecimiento del renderizado de archivos

El enrutamiento de solicitudes del navegador para capturas de pantalla es de denegación predeterminada.
Solo se permiten los activos locales del visor desde http://127.0.0.1/plugins/diffs/assets/*.
Las solicitudes de red externas están bloqueadas.

Requisitos del navegador para el modo de archivo

mode: "file" y mode: "both" necesitan un navegador compatible con Chromium.

Orden de resolución:

Configuración
browser.executablePath en la configuración de OpenClaw.
Variables de entorno
- OPENCLAW_BROWSER_EXECUTABLE_PATH
- BROWSER_EXECUTABLE_PATH
- PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
Respaldo de plataforma
Respaldo de descubrimiento de comando/ruta de plataforma.

Texto de fallo común:

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

Solución: instale Chrome, Chromium, Edge o Brave, o configure una de las opciones de ruta ejecutable mencionadas anteriormente.

Solución de problemas

Errores de validación de entrada

Provide patch or both before and after text. — incluya tanto before como after, o proporcione patch.
Provide either patch or before/after input, not both. — no mezcle modos de entrada.
Invalid baseUrl: ... — use el origen http(s) con una ruta opcional, sin consulta/hash.
{field} exceeds maximum size (...) — reduzca el tamaño de la carga útil.
Rechazo de parche grande — reduzca la cantidad de archivos de parche o el total de líneas.

Accesibilidad del visor

La URL del visor se resuelve a 127.0.0.1 de forma predeterminada.
Para escenarios de acceso remoto, puede:
- configurar el viewerBaseUrl del complemento, o
- pasar baseUrl por cada llamada a la herramienta, o
- usar gateway.bind=custom y gateway.customBindHost
Si gateway.trustedProxies incluye loopback para un proxy del mismo host (por ejemplo, Tailscale Serve), las solicitudes de visor de loopback sin encabezados de IP de cliente reenviados fallan cerradas por diseño.
Para esa topología de proxy:
- prefiera mode: "file" o mode: "both" cuando solo necesite un archivo adjunto, o
- habilite intencionalmente security.allowRemoteViewer y configure el viewerBaseUrl del complemento o pase un baseUrl proxy/público cuando necesite una URL de visor compartible
Habilite security.allowRemoteViewer solo cuando pretenda acceso externo al visor.

La fila de líneas sin modificar no tiene botón de expansión

Esto puede ocurrir para la entrada de parche cuando el parche no lleva contexto expandible. Esto es esperado y no indica un fallo del visor.

Artefacto no encontrado

El artefacto expiró debido al TTL.
El token o la ruta cambiaron.
La limpieza eliminó datos obsoletos.

Guía operacional

Prefiera mode: "view" para revisiones interactivas locales en el lienzo.
Prefiera mode: "file" para canales de chat salientes que necesiten un archivo adjunto.
Mantenga allowRemoteViewer deshabilitado a menos que su implementación requiera URLs de visor remotas.
Establezca ttlSeconds cortos explícitos para diffs confidenciales.
Evite enviar secretos en la entrada de diffs cuando no sea necesario.
Si su canal comprime las imágenes de forma agresiva (por ejemplo, Telegram o WhatsApp), prefiera la salida en PDF (fileFormat: "pdf").