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

Tools

Diferencias

diffs es una herramienta opcional de un plugin incluido que convierte texto anterior/posterior o un parche unificado en un artefacto de diferencias de solo lectura. También antepone instrucciones breves para el agente al prompt del sistema e incluye una Skill complementaria con instrucciones más completas.

Entrada: texto before + after, o un patch unificado (mutuamente excluyentes).

Salida: una URL del visor del Gateway para su presentación en el lienzo, una ruta de archivo PNG/PDF renderizado para su entrega mediante mensajes, o ambas.

Inicio rápido

  • Instalar el plugin

    bash
    openclaw plugins install diffs

  • Habilitar el plugin

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

  • Elegir un modo

    view

    Flujos centrados en el lienzo: los agentes llaman a diffs con mode: "view" y abren details.viewerUrl con canvas present.

    file

    Entrega de archivos por chat: los agentes llaman a diffs con mode: "file" y envían details.filePath con message mediante path o filePath.

    both

    Combinado (predeterminado): los agentes llaman a diffs con mode: "both" para obtener ambos artefactos en una sola llamada.

    • Deshabilitar las instrucciones integradas del sistema

    Para conservar la herramienta, pero eliminar las instrucciones antepuestas al prompt del sistema, establezca plugins.entries.diffs.hooks.allowPromptInjection en false:

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

    Esto bloquea el hook before_prompt_build del plugin, pero mantiene disponibles la herramienta y la Skill. Para deshabilitar tanto las instrucciones como la herramienta, deshabilite el plugin.

    Referencia de entrada de la herramienta

    Todos los campos son opcionales, salvo que se indique lo contrario.

    beforestring

    Texto original. Obligatorio junto con after cuando se omite patch.

    afterstring

    Texto actualizado. Obligatorio junto con before cuando se omite patch.

    patchstring

    Texto de diferencias unificado. Mutuamente excluyente con before y after.

    pathstring

    Nombre de archivo mostrado para el modo anterior/posterior.

    langstring

    Indicación de idioma que anula el valor predeterminado para el modo anterior/posterior. Los valores desconocidos y los idiomas que no pertenecen al conjunto predeterminado del visor recurren a texto sin formato, a menos que esté instalado el plugin Diff Viewer Language Pack.

    titlestring

    Título del visor que anula el valor predeterminado.

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

    Modo de salida. El valor predeterminado es el del plugin defaults.mode (both). Alias obsoleto: "image" se comporta de forma idéntica a "file".

    theme"light" | "dark"

    Tema del visor. El valor predeterminado es el del plugin defaults.theme.

    layout"unified" | "split"

    Diseño de las diferencias. El valor predeterminado es el del plugin defaults.layout.

    expandUnchangedboolean

    Expande las secciones sin cambios cuando está disponible el contexto completo. Opción disponible solo por llamada (no es una clave predeterminada del plugin).

    fileFormat"png" | "pdf"

    Formato del archivo renderizado. El valor predeterminado es el del plugin defaults.fileFormat.

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

    Preajuste de calidad para la renderización en PNG/PDF.

    fileScalenumber

    Escala del dispositivo que anula el valor predeterminado (1-4).

    fileMaxWidthnumber

    Anchura máxima de renderización en píxeles CSS (640-2400).

    ttlSecondsnumberdefault: 1800

    TTL del artefacto en segundos para las salidas del visor y de archivos independientes. Máximo: 21600.

    baseUrlstring

    Origen de la URL del visor que anula el valor predeterminado. Anula el valor viewerBaseUrl del plugin. Debe ser http o https, sin consulta ni hash.

    Validación y límites
    • before/after: máximo de 512 KiB cada uno.
    • patch: máximo de 2 MiB.
    • path: máximo de 2048 bytes.
    • lang: máximo de 128 bytes.
    • title: máximo de 1024 bytes.
    • Límite de complejidad del parche: máximo de 128 archivos y 120000 líneas en total.
    • Se rechaza patch junto con before/after.
    • Límites de seguridad de los archivos renderizados (PNG y PDF):
      • fileQuality: "standard": máximo de 8 MP (8,000,000 píxeles renderizados).
      • fileQuality: "hq": máximo de 14 MP.
      • fileQuality: "print": máximo de 24 MP.
      • El PDF también tiene un límite de 50 páginas.

    Resaltado de sintaxis

    Idiomas integrados:

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

    Los alias habituales (js, ts, bash, md, yml, c++, dockerfile, rb, kt, ps1, etc.) se normalizan a esos idiomas.

    Instale el plugin Diff Viewer Language Pack para disponer de más idiomas (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 y más):

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

    Sin el paquete, los idiomas no compatibles se siguen renderizando como texto sin formato legible. Consulte plugin Diffs Language Pack e idiomas de Shiki para ver el catálogo del proyecto de origen.

    Contrato de detalles de salida

    Todos los resultados correctos incluyen changed: una entrada anterior/posterior idéntica devuelve false sin crear ningún artefacto; los resultados renderizados devuelven true.

    Campos del visor (modos view y both)
    • changed
    • artifactId
    • viewerUrl
    • viewerPath
    • title
    • expiresAt
    • inputKind
    • fileCount
    • mode
    • context (agentId, sessionId, messageChannel, agentAccountId cuando estén disponibles)
    Campos de archivo (modos file y both)
    • changed
    • artifactId
    • expiresAt
    • filePath
    • path (el mismo valor que filePath, para mantener la compatibilidad con la herramienta de mensajes)
    • fileBytes
    • fileFormat
    • fileQuality
    • fileScale
    • fileMaxWidth
    Modo Devuelve
    "view" Solo campos del visor.
    "file" Solo campos de archivo, sin artefacto del visor.
    "both" Campos del visor y campos de archivo. Si falla la renderización del archivo, el visor se sigue devolviendo con fileError.

    Secciones sin cambios contraídas

    El visor muestra filas como N unmodified lines. Los controles para expandir solo aparecen cuando las diferencias renderizadas contienen datos de contexto expandibles (algo habitual con entradas anterior/posterior). Muchos parches unificados omiten los cuerpos de contexto de sus fragmentos, por lo que la fila puede aparecer sin un control para expandir; es el comportamiento esperado, no un error. expandUnchanged solo se aplica cuando existe contexto expandible.

    Los parches que afectan a más de un archivo comienzan con una tarjeta de resumen de los archivos modificados: recuentos totales de +N / -N, recuentos por archivo, insignias de archivos añadidos/eliminados/renombrados y enlaces de anclaje para ir a cada archivo. Los archivos PNG/PDF renderizados conservan los recuentos del encabezado de cada archivo, pero omiten los controles interactivos para cambiar de vista, ya que no funcionan en un archivo estático.

    Valores predeterminados del plugin

    Establezca los valores predeterminados del plugin en ~/.openclaw/openclaw.json:

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

    Claves defaults compatibles: fontFamily, fontSize, lineSpacing, layout, showLineNumbers, diffIndicators, wordWrap, background, theme, fileFormat, fileQuality, fileScale, fileMaxWidth, mode, ttlSeconds. Los parámetros explícitos de la llamada a la herramienta anulan estos valores.

    Configuración persistente de la URL del visor

    viewerBaseUrlstring

    Alternativa propiedad del plugin para los enlaces del visor devueltos cuando una llamada a la herramienta no proporciona baseUrl. Debe ser http o https, sin consulta ni hash.

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

    Configuración de seguridad

    security.allowRemoteViewerbooleandefault: false

    false: se deniegan las solicitudes que no proceden de la interfaz de bucle invertido dirigidas a las rutas del visor. true: se permiten los visores remotos si la ruta con token es válida.

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

    Ciclo de vida y almacenamiento de los artefactos

    • El HTML y los metadatos del visor se almacenan en la base de datos compartida state/openclaw.sqlite, dentro del espacio de nombres de blobs del plugin Diffs. El HTML se comprime con gzip; SQLite almacena únicamente un hash SHA-256 del token aleatorio de la URL, no el token en sí.
    • Los archivos PNG/PDF renderizados siguen siendo materializaciones temporales en $TMPDIR/openclaw-diffs, porque la entrega mediante canales requiere una ruta de archivo. SQLite gestiona sus metadatos de caducidad; no se escriben archivos JSON auxiliares.
    • TTL predeterminado de los artefactos: 30 minutos. TTL máximo aceptado: 6 horas.
    • La limpieza se ejecuta de forma oportunista después de cada llamada de creación de artefactos. Primero se eliminan las filas caducadas de SQLite y, después, cualquier directorio PNG/PDF correspondiente.
    • Un barrido de respaldo elimina las carpetas temporales sin filas asociadas que tengan más de 24 horas. Las cachés heredadas meta.json, file-meta.json y viewer.html no se importan ni se leen.

    URL del visor y comportamiento de red

    Ruta del visor: /plugins/diffs/view/{artifactId}/{token}

    Recursos del visor:

    • /plugins/diffs/assets/viewer.js
    • /plugins/diffs/assets/viewer-runtime.js
    • /plugins/diffs-language-pack/assets/viewer.js (solo cuando el diff utiliza un idioma del paquete de idiomas)

    El documento del visor resuelve estos recursos con respecto a la URL del visor, por lo que un prefijo de ruta opcional baseUrl también se aplica a las solicitudes de recursos.

    Orden de resolución de URL: baseUrl de la llamada a la herramienta (tras una validación estricta) -> viewerBaseUrl del plugin -> valor predeterminado de bucle invertido 127.0.0.1. Si el modo de enlace del Gateway es custom y se ha establecido gateway.customBindHost, se utiliza ese host en lugar del bucle invertido.

    Reglas de baseUrl: debe ser http:// o https://; se rechazan la consulta y el hash; se permite el origen con una ruta base opcional.

    Modelo de seguridad

    Refuerzo del visor
    • Solo bucle invertido de forma predeterminada.
    • Rutas del visor con tokens y validación estricta de los patrones de ID y token.
    • CSP de la respuesta del visor: default-src 'none'; scripts y recursos únicamente del propio origen; sin connect-src salientes.
    • Limitación de intentos fallidos remotos cuando el acceso remoto está habilitado: 40 fallos en 60 segundos activan un bloqueo de 60 segundos (429 Too Many Requests).
    Refuerzo de la renderización de archivos
    • El enrutamiento de solicitudes del navegador para capturas de pantalla se deniega de forma predeterminada.
    • Solo se permiten recursos locales del visor procedentes de 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

  • Alternativa de la plataforma

    Rutas de instalación habituales y búsquedas de PATH para Chrome, Chromium, Edge y Brave.

    • Texto de error habitual: Diff PNG/PDF rendering requires a Chromium-compatible browser.... Para solucionarlo, instale Chrome, Chromium, Edge o Brave, o establezca una de las opciones de ruta del ejecutable indicadas 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: ... -- utilice un origen http(s) con una ruta opcional, sin consulta ni hash.
    • {field} exceeds maximum size (...) -- reduzca el tamaño de la carga útil.
    • Rechazo de un parche grande -- reduzca el número de archivos del parche o el total de líneas.
    Accesibilidad del visor
    • La URL del visor se resuelve como 127.0.0.1 de forma predeterminada.
    • Para el acceso remoto, establezca viewerBaseUrl en el plugin, pase baseUrl en cada llamada o utilice gateway.bind=custom con gateway.customBindHost.
    • Si gateway.trustedProxies incluye el bucle invertido para un proxy del mismo host (por ejemplo, Tailscale Serve), las solicitudes directas al visor mediante el bucle invertido sin encabezados de IP del cliente reenviados se cierran de forma segura por diseño.
    • Para esa topología de proxy, se recomienda mode: "file"/"both" para un archivo adjunto, o habilitar intencionadamente security.allowRemoteViewer junto con viewerBaseUrl en el plugin/un baseUrl del proxy para obtener un enlace compartible del visor.
    • Habilite security.allowRemoteViewer únicamente cuando se pretenda permitir el acceso externo al visor.
    La fila de líneas sin modificar no tiene botón de expansión

    Es lo esperado para una entrada de parche que carece de contexto ampliable; no se trata de un fallo del visor.

    Artefacto no encontrado
    • El artefacto ha caducado debido al TTL.
    • El token o la ruta han cambiado.
    • La limpieza ha eliminado datos obsoletos.

    Orientación operativa

    • Se recomienda mode: "view" para revisiones interactivas locales en el lienzo.
    • Se recomienda mode: "file" para canales de chat salientes que necesiten un archivo adjunto.
    • Mantenga allowRemoteViewer deshabilitado, salvo que el despliegue requiera URL remotas del visor.
    • Establezca un ttlSeconds corto y explícito para diffs sensibles.
    • Evite enviar secretos en la entrada del diff cuando no sea necesario.
    • Si el canal comprime las imágenes de forma agresiva (por ejemplo, Telegram o WhatsApp), se recomienda la salida PDF (fileFormat: "pdf").

    Contenido relacionado

    Was this useful?
    On this page

    On this page