- name
- hwp-batch-convert
- description
- Batch-convert 한컴 한글 문서(HWP/HWPX) to PDF, HWPX, DOCX, ODT, HTML, RTF, TXT, and image formats on Windows using HWP COM automation. Use when the user asks for 이 폴더 hwp 전부 pdf로 바꿔줘, hwp/hwpx/doc/pdf 일괄 변환, 한글문서 일괄 처리, 폴더 단위 변환, 여러 한글 파일을 다른 형식으로 내보내기, or wants a Korean-friendly batch conversion/report flow. 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가 핵심이 아니면 다른 문서 스킬/도구를 우선 고려한다.