차이점

diffs는 짧은 내장 시스템 지침과 변경 내용을 에이전트용 읽기 전용 diff 아티팩트로 변환하는 동반 skill이 있는 선택적 Plugin 도구입니다.

다음 중 하나를 받을 수 있습니다.

• before 및 after 텍스트
• 통합 patch

다음을 반환할 수 있습니다.

• 캔버스 표시용 Gateway 뷰어 URL
• 메시지 전달용 렌더링된 파일 경로(PNG 또는 PDF)
• 한 번의 호출에서 두 출력 모두

활성화하면 Plugin은 간결한 사용 지침을 시스템 프롬프트 공간 앞에 추가하고, 에이전트에 더 자세한 지침이 필요한 경우를 위해 상세 skill도 노출합니다.

빠른 시작

openclaw plugins install diffs

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

내장 시스템 지침 비활성화

diffs 도구는 활성화한 상태로 유지하되 내장 시스템 프롬프트 지침을 비활성화하려면 plugins.entries.diffs.hooks.allowPromptInjection을 false로 설정하세요.

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

이렇게 하면 Plugin, 도구, 동반 skill은 계속 사용할 수 있는 상태로 두면서 diffs Plugin의 before_prompt_build 훅을 차단합니다.

지침과 도구를 모두 비활성화하려면 대신 Plugin을 비활성화하세요.

일반적인 에이전트 워크플로

입력 예시

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

도구 입력 참조

명시된 경우를 제외하고 모든 필드는 선택 사항입니다.

구문 강조

OpenClaw에는 일반적인 소스, 구성, 문서 언어에 대한 구문 강조가 포함되어 있습니다.

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

js, ts, bash, md, yml, c++, dockerfile, rb, kt, ps1 같은 일반적인 별칭은 해당 기본 언어로 정규화됩니다.

Diff Viewer Language Pack Plugin을 설치하여 다른 언어를 강조 표시하세요.

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

언어 팩을 사용할 수 있으면 OpenClaw는 훨씬 더 많은 언어를 강조 표시할 수 있습니다. 팩이 설치되어 있지 않아도 기본 목록 밖의 파일은 읽기 쉬운 일반 텍스트로 계속 렌더링됩니다. 예로는 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 파일이 있습니다.

자세한 내용은 Diffs Language Pack Plugin을, Shiki의 업스트림 언어 및 별칭 카탈로그는 Shiki languages를 참고하세요.

출력 세부 정보 계약

이 도구는 details 아래에 구조화된 메타데이터를 반환합니다.

모드 동작 요약:

접힌 변경 없는 섹션

• 뷰어는 N unmodified lines 같은 행을 표시할 수 있습니다.
• 해당 행의 펼치기 컨트롤은 조건부이며 모든 입력 종류에서 보장되지는 않습니다.
• 펼치기 컨트롤은 렌더링된 diff에 펼칠 수 있는 컨텍스트 데이터가 있을 때 표시되며, 이는 before 및 after 입력에서 일반적입니다.
• 많은 unified patch 입력의 경우 생략된 컨텍스트 본문은 파싱된 패치 hunk에서 사용할 수 없으므로, 행이 펼치기 컨트롤 없이 나타날 수 있습니다. 이는 예상된 동작입니다.
• expandUnchanged는 펼칠 수 있는 컨텍스트가 있을 때만 적용됩니다.

Plugin 기본값

Plugin 전체 기본값을 ~/.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,          },        },      },    },  },}

지원되는 기본값:

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

명시적인 도구 매개변수는 이러한 기본값을 재정의합니다.

영구 뷰어 URL 구성

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

보안 구성

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

아티팩트 수명 주기 및 스토리지

• 아티팩트는 임시 하위 폴더 $TMPDIR/openclaw-diffs 아래에 저장됩니다.
• 뷰어 아티팩트 메타데이터에는 다음이 포함됩니다.
  • 무작위 아티팩트 ID(16진수 20자)
  • 무작위 토큰(16진수 48자)
  • createdAt 및 expiresAt
  • 저장된 viewer.html 경로
• 지정하지 않으면 기본 아티팩트 TTL은 30분입니다.
• 허용되는 최대 뷰어 TTL은 6시간입니다.
• 정리는 아티팩트 생성 후 기회가 있을 때 실행됩니다.
• 만료된 아티팩트는 삭제됩니다.
• 메타데이터가 없으면 대체 정리가 24시간보다 오래된 오래된 폴더를 제거합니다.

뷰어 URL 및 네트워크 동작

뷰어 라우트:

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

뷰어 애셋:

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js
• diff가 Diff Viewer Language Pack의 언어를 사용할 때 /plugins/diffs-language-pack/assets/viewer.js

뷰어 문서는 해당 애셋을 뷰어 URL 기준 상대 경로로 확인하므로, 선택적 baseUrl 경로 접두사는 두 애셋 요청 모두에도 보존됩니다.

URL 구성 동작:

• 도구 호출 baseUrl이 제공되면 엄격한 검증 후 사용됩니다.
• 그렇지 않고 Plugin viewerBaseUrl이 구성되어 있으면 사용됩니다.
• 두 재정의가 모두 없으면 뷰어 URL은 기본적으로 loopback 127.0.0.1을 사용합니다.
• Gateway 바인드 모드가 custom이고 gateway.customBindHost가 설정되어 있으면 해당 호스트가 사용됩니다.

baseUrl 규칙:

• http:// 또는 https://여야 합니다.
• 쿼리와 해시는 거부됩니다.
• Origin과 선택적 기본 경로가 허용됩니다.

보안 모델

파일 모드의 브라우저 요구 사항

mode: "file" 및 mode: "both"에는 Chromium 호환 브라우저가 필요합니다.

확인 순서:

일반적인 실패 문구:

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

Chrome, Chromium, Edge 또는 Brave를 설치하거나 위의 실행 파일 경로 옵션 중 하나를 설정하여 해결하세요.

문제 해결

운영 지침

• 캔버스의 로컬 대화형 리뷰에는 mode: "view"를 선호하세요.
• 첨부 파일이 필요한 아웃바운드 채팅 채널에는 mode: "file"을 선호하세요.
• 배포에 원격 뷰어 URL이 필요하지 않으면 allowRemoteViewer를 비활성화 상태로 유지하세요.
• 민감한 diff에는 명시적으로 짧은 ttlSeconds를 설정하세요.
• 필요하지 않을 때는 diff 입력에 비밀 정보를 보내지 마세요.
• 채널이 이미지를 강하게 압축하는 경우(예: Telegram 또는 WhatsApp), PDF 출력(fileFormat: "pdf")을 선호하세요.

관련 항목

• 브라우저
• Plugins
• 도구 개요