차이점

diffs는 짧은 내장 시스템 가이드와 동반 Skills를 제공하는 선택적 Plugin 도구로, 변경 내용을 에이전트용 읽기 전용 diff 아티팩트로 변환합니다.

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

• before 및 after 텍스트
• 통합 patch

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

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

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

# 빠른 시작

openclaw plugins install diffs

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

# 내장 시스템 가이드 비활성화

diffs 도구는 활성화된 상태로 유지하되 내장 시스템 프롬프트 가이드를 비활성화하려면 plugins.entries.diffs.hooks.allowPromptInjection을 false로 설정합니다.

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

이렇게 하면 diffs Plugin의 before_prompt_build 훅은 차단되지만 Plugin, 도구, 동반 Skills는 계속 사용할 수 있습니다.

가이드와 도구를 모두 비활성화하려면 대신 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"
}

# 도구 입력 참조

별도 표시가 없는 한 모든 필드는 선택 사항입니다.

# 출력 details 계약

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

모드 동작 요약:

# 접힌 변경되지 않은 섹션

• 뷰어는 N unmodified lines 같은 행을 표시할 수 있습니다.
• 해당 행의 확장 컨트롤은 조건부이며 모든 입력 종류에서 보장되지는 않습니다.
• 렌더링된 diff에 확장 가능한 컨텍스트 데이터가 있을 때 확장 컨트롤이 표시되며, 이는 before/after 입력에서 일반적입니다.
• 많은 통합 패치 입력에서는 생략된 컨텍스트 본문을 파싱된 패치 헝크에서 사용할 수 없으므로, 확장 컨트롤 없이 행이 표시될 수 있습니다. 이는 예상된 동작입니다.
• expandUnchanged는 확장 가능한 컨텍스트가 있을 때만 적용됩니다.

# Plugin 기본값

~/.openclaw/openclaw.json에서 Plugin 전체 기본값을 설정합니다.

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

지원되는 기본값:

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

명시적 도구 매개변수는 이 기본값을 오버라이드합니다.

# 영구 뷰어 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시간입니다.
• 정리는 아티팩트 생성 후 기회가 있을 때 실행됩니다.
• 만료된 아티팩트는 삭제됩니다.
• fallback 정리는 메타데이터가 없을 때 24시간보다 오래된 오래된 폴더를 제거합니다.

# 뷰어 URL 및 네트워크 동작

뷰어 경로:

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

뷰어 애셋:

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

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

URL 구성 동작:

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

baseUrl 규칙:

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

# 보안 모델

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

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
• 도구 개요