- name
- hwp-batch-convert
- description
- Batch-convert 한컴 한글 문서(HWP/HWPX) on Windows into PDF and other export formats with a Korean-friendly automation workflow. Use when the user asks for 이 폴더 hwp 전부 pdf로 바꿔줘, hwp/hwpx/doc/pdf 일괄 변환, 한글문서 일괄 처리, 폴더 단위 변환, 여러 한글 파일을 다른 형식으로 내보내기, or wants plan-only / mock / real conversion runs with machine-readable reports. Supports HWP/HWPX to PDF, HWPX, DOCX, ODT, HTML, RTF, TXT, PNG, JPG, BMP, and GIF, plus optional automatic approval of known 한글 보안 확인 팝업. Prefer this skill for Windows environments with Hancom HWP installed; do not use it for non-HWP document families unless the task is explicitly about HWP/HWPX conversion.
Hwp Batch Convert
Use this skill for Windows 기반 한글(HWP/HWPX) 문서 일괄 변환.
Current scope:
- 폴더 단위 일괄 변환
- 파일 여러 개 일괄 변환
- HWP/HWPX → PDF 기본 변환
- HWP/HWPX → HWPX/DOCX/ODT/HTML/RTF/TXT/PNG/JPG/BMP/GIF 변환
- 동일 형식 자동 건너뜀
- 출력 파일명 충돌 시 자동 번호 부여
- 작업 계획만 확인하는
--plan-only - OpenClaw 상위 레이어 연동용
--json,--report-json - 한글 보안 확인 팝업 자동 허용용
--auto-allow-dialogs - 로컬 UI 검증용
--self-test-dialog-handler - 테스트용
--mode mock
Source basis
This skill reuses the design of the local/source repo:
tmp/HwpMate- upstream:
https://github.com/twbeatles/HwpMate
Main logic origin:
hwpmate/services/hwp_converter.pyhwpmate/services/task_planner.pyhwpmate/constants.pyhwpmate/path_utils.py
If you need the mapping details or reuse rationale, read:
references/hwpmate-reuse-notes.md
If you need the popup whitelist / safety details, read:
references/auto-allow-dialogs.md
Quick start
같은 폴더에 PDF 출력:
python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\contracts" --format PDF --same-location별도 출력 폴더로 변환:
python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\hwp" --format PDF --output-dir "C:\docs\pdf" --auto-allow-dialogs여러 파일 한 번에 변환:
python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\a.hwp" "C:\docs\b.hwpx" --format DOCX --output-dir "C:\docs\docx"실제 변환 없이 계획만 확인:
python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\hwp" --format PDF --output-dir "C:\docs\pdf" --plan-only --json테스트용 모의 변환:
python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\sample" --format PDF --output-dir "C:\docs\out" --mode mock --jsonMain script
scripts/hwp_batch_convert.py
Parameters:
sources...: 입력 파일/폴더 경로 하나 이상--format: 출력 형식 (PDF,HWPX,DOCX,ODT,HTML,RTF,TXT,PNG,JPG,BMP,GIF,HWP)--same-location: 원본과 같은 폴더에 출력--output-dir: 출력 루트 폴더--include-sub: 하위 폴더 포함(기본값)--no-include-sub: 하위 폴더 제외--overwrite: 같은 이름 출력 허용--plan-only: 실제 변환 없이 작업 계획만 생성--mode real|mock: 실변환 또는 모의 변환--auto-allow-dialogs: 제목한글, 본문에접근하려는 시도, 버튼모두 허용/허용조건을 모두 만족하는 보안 팝업만 자동 클릭--json: stdout JSON 출력--report-json: 결과 JSON 파일 저장--self-test-dialog-handler: 로컬 테스트용 샘플한글창을 띄워 자동 클릭 로직만 검증
Recommended workflow
- 사용자 요청이 폴더/여러 파일 기반 HWP/HWPX 변환인지 확인한다.
- 출력 형식이 명시되지 않았으면 보통
PDF를 기본 제안으로 사용한다. - 먼저
--plan-only --json으로 대상/건너뜀/출력 경로를 확인한다. - 환경이 Windows + 한글 설치 + pywin32 가능하면
--mode real로 실행한다. - 환경 검증이 먼저 필요하면
--mode mock으로 경로/출력 구조만 검증한다. - 필요하면
--report-json으로 결과 파일을 남긴다.
Operational notes
- 이 스킬은 사실상 Windows 전용이다.
- 실변환(
--mode real)은 한컴 한글 설치와 pywin32가 필요하다. --auto-allow-dialogs는 화이트리스트 방식이다. 제목이한글이고, 본문에접근하려는 시도가 있으며, 버튼이모두 허용또는허용인 경우에만 클릭한다.- 위 조건에 맞지 않는 다른 팝업은 자동으로 건드리지 않는다. 감지되더라도 클릭 없이 이벤트만 남기거나 무시한다.
- 자동 허용 기록은 stdout JSON/
--report-json의auto_dialog_*필드와auto_dialog_events배열에서 확인한다. - 한글 COM 자동화가 실패하면
--mode mock으로 스킬/경로 로직만 먼저 검증하고, 이후 환경 문제를 분리 진단한다. - 여러 폴더를 동시에 입력하면서
--output-dir를 쓰면, 파일명 충돌 가능성이 있으니 결과 경로를 확인한다. - 기본 입력 확장자는
.hwp,.hwpx만 대상으로 한다. - 사용자 요청이 DOCX/PDF 일반 문서 처리 중심이고 HWP가 핵심이 아니면 다른 문서 스킬/도구를 우선 고려한다.