폴더를 열었더니 HWP 파일이 200개 들어 있습니다. 이걸 전부 LLM에 읽혀서 검색 가능한 자료로 만들어야 하는데, 하나씩 열어서 복사하다가는 이번 주가 다 갑니다. 이럴 때 터미널 창에 명령어 한 줄을 치고 커피를 한 잔 타 오면 변환이 끝나 있다면 어떨까요.
kordoc의 CLI가 바로 그런 도구입니다. 이 글은 kordoc 입문 시리즈 2편입니다. 전체 그림이 궁금하시면 먼저 [kordoc 설치부터 사용법까지, HWP·PDF를 AI가 읽게 만드는 MCP 완전 가이드](필라글 링크)를 보고 오셔도 좋습니다. 여기서는 명령어 하나하나를 실제로 어떤 상황에 쓰는지 매뉴얼처럼 풀어 보겠습니다. 처음 보는 옵션이 나와도 따라올 수 있게 가장 쉬운 것부터 순서대로 가겠습니다.
시작하기 전에 확인할 두 가지
준비물은 Node.js뿐입니다. 공식 문서 기준으로 20 이상이 필요하고, macOS와 리눅스, 윈도우 모두 지원합니다. 터미널에서 버전부터 확인하세요.
node -v20보다 낮은 숫자가 나오면 Node.js를 먼저 올려야 합니다. 그다음이 반가운 부분인데, CLI만 쓸 거라면 설치 과정이 아예 없습니다. 모든 명령어 앞에 npx를 붙이면 필요한 패키지를 알아서 받아 실행합니다.
두 번째로 알아 둘 것은 처음 실행할 때 약간 기다린다는 점입니다. npx가 패키지를 내려받고 PDF 처리용 의존 패키지도 함께 설치하기 때문입니다. 첫 실행이 느려도 멈춘 게 아니니 당황하지 마세요. 두 번째부터는 훨씬 빠릅니다. 같은 명령을 자주 쓰실 거라면 npm install -g kordoc으로 전역 설치를 해 두는 방법도 있습니다. 그러면 앞의 npx를 빼고 kordoc 보고서.hwp처럼 바로 칠 수 있습니다.
파일 하나를 변환해 보기
가장 단순한 형태부터 해 봅시다. 변환하려는 파일이 있는 폴더에서 이렇게 칩니다.
npx kordoc 사업계획서.hwpx아무 옵션도 주지 않으면 변환 결과가 터미널 화면에 그대로 출력됩니다. 문서가 제대로 읽히는지 눈으로 먼저 확인하고 싶을 때 쓰기 좋습니다. 표가 마크다운 표로 복원됐는지, 제목 위계가 살아 있는지를 이 화면에서 바로 볼 수 있습니다.
결과를 파일로 저장하려면 -o 옵션을 붙입니다.
npx kordoc 보고서.hwp -o 보고서.md여기서 한 가지 챙겨 볼 것이 있습니다. 문서 안에 그림이 있으면 저장 위치 옆에 images라는 폴더가 생기고, 그 안에 문서 이름으로 된 하위 폴더가 만들어집니다. 위 명령이라면 images/보고서/ 안에 그림 파일들과 manifest.json이 들어갑니다. 이 목록 파일에는 이미지 이름과 형식, 크기, 원본 안에서의 경로가 적혀 있어서 나중에 그림만 따로 처리할 때 유용합니다. 같은 폴더에 여러 문서를 변환해도 문서 이름별로 폴더가 갈라지기 때문에 서로 덮어쓰지 않습니다.
그림 형식은 확장자보다 manifest.json의 형식 값을 믿으라고 문서에 안내되어 있습니다. 파일 맨 앞 바이트로 확인한 값이라 확장자가 어긋나 있는 경우에도 정확하다는 뜻입니다. (여기에 본인이 변환한 HWP 원본과 결과 마크다운 비교 캡처를 한 장 넣으시면 좋습니다.)
폴더째 한 번에 변환하기
처음에 말씀드린 200개 파일 문제로 돌아가 봅시다. 여러 파일을 한 번에 바꿀 때는 별표 패턴과 출력 폴더 옵션 -d를 같이 씁니다.
npx kordoc *.pdf -d ./변환결과/-o는 파일 하나의 저장 이름을 정하는 옵션이고, -d는 결과물이 모일 폴더를 정하는 옵션입니다. 여러 파일을 처리할 때는 반드시 -d를 써야 한다고 기억해 두세요.
파일이 많으면 병렬 처리를 켤 수 있습니다.
npx kordoc *.pdf --jobs 4 -d ./변환결과/--jobs 4는 변환 프로세스를 네 개 띄워 파일 단위로 나눠 처리한다는 뜻입니다. 다만 주의할 점이 몇 가지 있습니다. 프로세스 수만큼 메모리를 더 쓰고, 파일이 작을 때는 오히려 더 느려질 수 있다고 문서에 적혀 있습니다. 병렬 처리를 쓰려면 확장자를 뺀 파일 이름이 서로 달라야 하는 제약도 있습니다. 보고서.hwp와 보고서.pdf가 같은 폴더에 있으면 결과 파일 이름이 겹치기 때문입니다. 또 중간에 한두 개가 실패해도 나머지는 계속 진행하고, 마지막에 종료 코드만 실패로 남깁니다. 200개를 돌리다 137번째에서 멈춰 버리는 일은 없으니 안심하셔도 됩니다.
성능 욕심을 내기 전에는 --jobs 2 정도로 시작해서 내 컴퓨터가 버티는 선을 확인해 보시길 권합니다. 특히 OCR이 섞여 있으면 OCR이 자체적으로 CPU 스레드를 쓰기 때문에, 프로세스 수를 높게 잡을수록 오히려 컴퓨터가 버거워질 수 있습니다.
필요한 쪽만 골라서 읽기
300쪽짜리 보고서에서 요약 부분만 필요하다면 전체를 변환할 이유가 없습니다. --pages 옵션으로 쪽 범위를 지정합니다.
npx kordoc 보고서.hwpx --pages 1-3범위는 하이픈으로 이어도 되고, 쉼표로 나열해도 됩니다. 1쪽과 3쪽, 5쪽에서 7쪽을 함께 보려면 1,3,5-7처럼 씁니다. PDF와 한컴으로 저장한 파일은 실제 쪽 기준으로 나뉘는데, 한컴이 저장할 때 남기는 조판 정보가 없는 파일은 섹션 단위로 근사해서 나눈다고 합니다. 그러니 쪽 번호가 눈으로 보던 것과 한두 쪽 어긋날 수 있다는 점은 알고 계세요.
엑셀은 시트 하나가 한 쪽이고, 파워포인트는 슬라이드 하나가 한 쪽입니다. 반대로 워드 파일은 쪽을 나누지 않아 쪽 정보가 아예 나오지 않습니다.
출력 형식을 바꾸는 방법
기본 출력은 마크다운이지만, 용도에 따라 형식을 바꿀 수 있습니다. 프로그램에서 이어 받아 처리할 거라면 JSON이 편합니다.
npx kordoc 검토서.hwpx --format jsonJSON에는 본문 블록 구조와 쪽별 마크다운, 제목과 작성자 같은 메타데이터가 함께 담깁니다. 자동화 스크립트에서 결과를 읽어 후처리하는 경우에 쓰세요.
RAG를 만든다면 청크 형식이 핵심입니다.
npx kordoc 검토서.pdf --format chunks문서를 글자 수로 뚝뚝 자르는 대신 제목 위계를 따라가며 잘라서, 각 청크에 “어느 장 어느 절에 속한 내용인지”를 경로 형태로 달아 줍니다. 표는 독립 청크로 분리됩니다. 이 청크가 검색 품질에 어떤 차이를 만드는지는 시리즈 5편에서 따로 깊게 다룹니다.
표 때문에 고민이라면 표 출력 방식을 고를 수 있습니다. 기본은 병합 셀이 있으면 HTML 표를 섞어 쓰는 방식인데, 모든 표를 마크다운 파이프 표로 통일하고 싶다면 --table-format gfm 옵션을 줍니다. 반대로 모든 표를 HTML로 내보내려면 --html-tables를 씁니다. 표 구조가 복잡한 공문서일수록 HTML이 구조를 더 잘 보존하지만, 사람이 읽기에는 파이프 표가 훨씬 편합니다. 용도에 따라 골라 쓰세요.
글 위주로 깔끔하게만 받고 싶을 때는 --plain이 있습니다. 그림 자리 표시와 링크 주소, 밑줄과 굵게 같은 장식을 걷어 내고 제목과 목록, 표 구조만 남깁니다. 요약용으로 LLM에 넣을 때 토큰을 아끼는 용도로 좋습니다. 이미지 처리가 필요 없으면 --no-images로 그림 바이트를 생략해 속도도 높일 수 있습니다.
스캔한 PDF는 OCR 옵션으로
문서를 스캔해서 만든 PDF는 글자층이 없습니다. 눈에는 글씨인데 파일 안에서는 그냥 사진이라는 뜻입니다. 이런 파일을 그냥 변환하면 실패 메시지가 나옵니다. 이때 OCR 옵션을 켭니다.
npx kordoc 스캔본.pdf --ocrkordoc의 OCR은 외부 서비스에 파일을 보내지 않고 내 컴퓨터에서 로컬로 돌아갑니다. API 키도 필요 없습니다. 처음 쓸 때 한국어 인식 모델을 약 18MB 내려받고, 이후에는 그 모델을 계속 씁니다. 기본 동작은 글자층이 없거나 깨진 쪽만 골라 읽는 것이고, 모든 쪽을 강제로 읽히고 싶다면 --ocr-force를 씁니다.
인터넷이 막힌 환경이라면 모델 상태를 먼저 확인하세요.
npx kordoc models --status폐쇄망에서는 모델 파일을 밖에서 내보내 안에서 가져오는 방법도 문서에 안내되어 있습니다. 회사 문서를 외부로 내보낼 수 없는 환경이라면 KORDOC_OFFLINE=1 환경 변수로 외부 통신을 아예 막아 둔 상태에서 쓰시면 됩니다. OCR 옵션이 더 필요한 분들은 5편에서 모델 선택과 손글씨 인식까지 정리해 두었으니 거기서 이어 보세요.
암호가 걸렸거나 표가 꼬일 때
변환하다 막히는 경우는 크게 두 가지로 나뉩니다. 파일이 아예 안 열리거나, 열리는데 결과가 이상하거나입니다.
열기 암호가 걸린 문서는 --password 옵션으로 해결합니다.
npx kordoc 잠긴문서.hwpx --password '암호'HWPX와 HWP 3.x, 5.x에서 동작합니다. 다만 한컴의 문서보안(DRM)이 걸린 파일은 이 옵션으로도 열 수 없습니다. 회사 보안 솔루션이 걸린 문서가 이 경우일 수 있으니, 열리지 않는다면 암호 문제인지 DRM 문제인지부터 구분해야 합니다.
결과가 이상한 쪽은 대부분 PDF 표입니다. 2단으로 편집된 시험지나 안내문처럼 테두리 상자가 많은 문서에서는 상자가 표로 잘못 인식되어 읽기 순서가 뒤집힐 수 있습니다. 이럴 때는 표 감지를 끄는 옵션이 해결책이 됩니다.
npx kordoc 시험지.pdf --no-tables머리글과 바닥글이 본문 사이사이에 끼어 나오는 경우도 있는데, 3쪽 이상 PDF에서는 반복되는 머리글과 바닥글을 기본으로 지웁니다. 지우지 않고 그대로 보고 싶다면 --no-header-footer 옵션을 쓰세요.
실패했을 때 에러 읽는 법
스크립트에서 kordoc을 호출한다면 이 부분을 꼭 읽어 두세요. 변환에 실패하면 kordoc은 어떤 출력 형식이든 표준 출력에 정해진 JSON을 내보내고 종료 코드 1로 끝납니다. 모양은 이렇습니다.
{ "success": false, "fileType": "hwpx", "file": "보고서.hwpx", "error": "암호화된 문서입니다 …", "code": "ENCRYPTED" }핵심은 code 값입니다. 사람이 읽는 error 문구는 바뀔 수 있어서 계약에 포함되지 않고, 기계가 판단할 때는 code를 기준으로 분기하라고 안내되어 있습니다. 자주 만나게 될 값은 이 정도입니다. ENCRYPTED는 열기 암호가 필요하거나 암호가 틀렸다는 뜻이고, DRM_PROTECTED는 한컴 문서보안 때문에 열 수 없다는 뜻입니다. IMAGE_BASED_PDF는 글자층이 없는 스캔 PDF라서 --ocr이 필요하다는 뜻이고, CORRUPTED는 파일이 손상되어 복구할 수 없다는 뜻입니다. UNSUPPORTED_FORMAT은 지원하지 않는 형식, FILE_NOT_FOUND는 경로가 틀렸다는 뜻입니다.
실제로 쓸 때는 이런 흐름이 됩니다. 변환 결과의 code가 IMAGE_BASED_PDF이면 같은 파일을 --ocr 옵션으로 한 번 더 돌리고, ENCRYPTED이면 목록에 올려 사람에게 암호를 물어보는 식입니다. 실패는 언제나 success가 false인 객체이기 때문에 성공 출력과 헷갈리지 않고, 여러 파일을 한꺼번에 돌릴 때는 실패마다 한 줄씩 나옵니다. 실패한 파일 목록만 따로 모아 두기가 쉽다는 뜻입니다.
폴더를 감시하면서 자동으로 변환하기
매일 문서가 들어오는 업무라면 사람이 명령을 칠 필요조차 없습니다. 감시 모드를 켜 두면 됩니다.
npx kordoc watch ./수신함 -d ./변환결과수신함 폴더에 파일이 떨어지면 자동으로 변환해 결과 폴더에 저장하고, 하위 폴더 구조도 그대로 유지합니다. 변환이 끝났을 때 다른 시스템에 알리고 싶다면 웹훅 주소를 붙일 수 있습니다.
npx kordoc watch ./문서 --webhook https://api/hook공유 폴더에 올라오는 문서를 자동으로 마크다운화해서 사내 검색이나 LLM 파이프라인에 넣는 식의 구성에 쓸 수 있습니다. 다만 이 명령은 터미널 창을 닫으면 같이 종료되므로, 실제로 상시 운영하려면 서비스로 등록하는 작업이 따로 필요합니다.
읽기 말고 쓰기 명령도 맛보기
kordoc의 CLI는 변환만 하는 게 아닙니다. 같은 npx kordoc 뒤에 붙는 다른 명령들이 있습니다. 어떤 게 있는지만 짧게 소개하겠습니다.
양식에 값을 채우는 fill, 마크다운을 공문서 형태의 HWPX로 만드는 generate, 원본 서식을 지키면서 고친 내용만 반영하는 patch, 두 문서의 차이를 찾는 compare가 있습니다. 또 문서에서 개인정보를 찾아 가려 주는 redact, 공문서 표기법을 검사하는 lint도 있습니다. 이 명령들은 사용법을 한 번에 이해하기 어려우니 시리즈 4편에서 예제 파일로 하나씩 해 보겠습니다. 지금은 “CLI 하나로 읽기부터 쓰기까지 된다”는 사실만 기억해 두시면 충분합니다.
하나만 덧붙이면, 이 명령 목록이 한눈에 외워지지 않는 게 정상입니다. npx kordoc --help를 치면 쓸 수 있는 옵션이 나오니, 모르는 것이 생기면 이 도움말부터 열어 보세요.
마무리, 이것만 기억하세요
오늘 다룬 내용을 한 줄로 줄이면 이렇습니다. npx kordoc 파일명으로 화면에서 먼저 확인하고, -o로 저장하고, 여러 개면 -d로 폴더에 모읍니다. 쪽이 길면 --pages로 줄이고, 스캔본이면 --ocr을 켭니다. 표가 꼬이면 --no-tables나 표 형식 옵션을 바꿔 보고, 자동화에서는 실패 JSON의 code 값으로 분기합니다.
처음부터 옵션을 다 외울 필요는 없습니다. 가진 문서 하나로 기본 명령을 돌려 보고, 결과가 마음에 안 드는 부분이 보일 때 해당 옵션을 찾아 붙이는 방식이 가장 빠르게 익숙해지는 길입니다. 터미널이 낯선 분도 이 정도 명령어만 있으면 HWP 수작업에서 벗어날 수 있습니다.