쓸모 쓸모연구소 · 실전 노트
제 825 호이번 주 새 글 49 편2026 · 11 · 14
클로드 사용법⁠·모델
kordoc · Claude · Codex

HWP 파일 AI로 읽기, 클로드 코드에 kordoc 연결해 표까지 변환하는 법

한글(HWP) 문서를 AI에게 넘기면 표와 서식이 사라지고 글자만 남는 경우가 많았습니다. kordoc(코독)은 HWP와 HWPX를 한컴오피스 없이 마크다운으로 바꿔 주는 무료 오픈소스 도구입니다. HWP 파일 AI로 읽기를 하려는 사람을 위해 클로드 코드와 코덱스에 연결하는 방법, 표를 정리하고 새 양식에 옮기는 요청문, 쓰기 전 주의점을 정리했습니다. 기준은 2026년 11월 저장소 안내입니다.

HWP 파일 AI로 읽기, 클로드 코드에 kordoc 연결해 표까지 변환하는 법 삽화
삽화 · 쓸모연구소

한글 파일이 AI에게 잘 안 읽히던 이유

한글 문서는 두 종류로 나뉩니다.

  • HWPX: 요즘 한글이 기본으로 저장하는 형식입니다. 압축된 폴더 안에 글자 구조가 XML이라는 사람이 읽을 수 있는 형태로 들어 있어서 AI도 비교적 쉽게 엽니다.
  • HWP: 오래 써 온 한컴 전용 이진 형식입니다. 내부가 바이트 덩어리라 일반 AI에게 그대로 주면 표와 서식은 빠지고 글자만 겨우 뽑히는 일이 많았습니다.

그래서 AI로 한글 문서를 읽는 방법도 사실상 HWPX에서만 잘 됐습니다. 공문서와 오래된 자료는 아직 HWP로 남아 있는 경우가 많아 이 차이가 업무에서 자주 걸립니다.

kordoc이 하는 일

kordoc은 MIT 라이선스의 라이브러리, 명령줄 도구, MCP 서버(클로드가 외부 도구를 쓰게 해 주는 연결 규격)를 겸하는 도구입니다. 저장소는 github.com/chrisryugj/kordoc이고, 2026년 11월 2일 기준 최신 배포 버전은 4.24.37입니다.

  • 읽을 수 있는 형식: HWP 3.x와 5.x, HWPX, HWPML, PDF, 엑셀, 워드, 파워포인트, 이미지 파일(PNG, JPG, WebP). 한컴오피스가 설치돼 있지 않아도 됩니다.
  • 합친 칸이 있는 표도 구조를 살려 마크다운이나 구조화된 데이터로 바꿉니다.
  • HWP 5.x를 HWPX로 바꾸는 변환, 마크다운에서 HWPX를 만드는 기능, 양식에 내용을 채우는 기능, 개인정보 마스킹도 들어 있습니다.
  • 스캔한 PDF나 이미지는 글자 인식(OCR)을 켜서 읽습니다.

정확도 수치는 저장소가 내세우는 측정값입니다. HWPX 2,424개 문서 안의 10,342개 표에서 표 구조가 100% 맞았고, PDF 표 구조 일치율은 98.24%라고 적혀 있습니다. 반면 스캔 이미지를 OCR로 읽은 표는 66개 중 34개(약 52%)만 구조가 맞아 텍스트 PDF보다 낮습니다. 고정된 측정용 문서로 잰 결과이고 독립 검증이 아니므로, 내 문서에서는 결과 표를 원본과 직접 대조하세요.

클로드 코드에 연결하기

준비물은 클로드 코드(또는 코덱스), Node.js 20 이상, 읽고 싶은 한글 파일입니다.

  1. 터미널에서 Node.js 버전을 확인합니다. 확인: node --version이 v20 이상으로 나옵니다.
  2. 클로드 코드에서 플러그인으로 설치합니다. 세션 안에서 아래 두 줄을 차례로 입력합니다. 설치 전 상세 화면에서 추가될 구성 요소를 읽고 진행합니다. 확인: 설치 후 /reload-plugins를 실행하라는 안내가 나올 수 있고, 그러면 따라 합니다.
명령어
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc
  1. 플러그인 대신 MCP 서버로 등록하려면 터미널에서 아래 명령을 실행합니다. 클로드 데스크톱, 클로드 코드, 커서, 코덱스 등에 한꺼번에 등록하며, 끝나면 사용하는 프로그램을 다시 시작합니다. 확인: 다시 시작한 뒤 kordoc 도구 22개를 쓸 수 있다고 안내돼 있습니다.
명령어
npx -y kordoc setup
  1. 연결을 확인합니다. 클로드 코드에서 /mcp를 입력합니다(플러그인 설치라면 /plugin의 Installed 목록도 봅니다). 확인: 목록에 kordoc이 보입니다.

클로드에게 "kordoc 설치해 줘"라고 한마디 맡겨도 연결됩니다. 이때는 클로드가 실행하려는 명령을 승인하기 전에 위의 저장소 주소와 맞는지 눈으로 확인합니다.

한글 파일 맡기기

연결이 끝나면 파일 경로를 알려 주고 자연어로 요청합니다. 요청문 예시는 다음과 같습니다.

프롬프트
~/Documents/공문.hwp 안의 표를 모두 찾아서 마크다운 표로 정리해 줘.
프롬프트
~/Documents/공문.hwp 내용을 ~/Documents/새양식.hwpx 형식에 맞춰 옮겨서 새 파일로 만들어 줘.
프롬프트
~/Documents/명단.xlsx의 각 행을 ~/Documents/상장양식.hwpx에 서식 그대로 채워서 한 장씩 만들어 줘.

세 번째처럼 엑셀 명단 수만큼 서식을 반복해 채우는 작업도 양식 채우기 기능으로 시도할 수 있습니다. 한 번에 모든 파일을 맡기기보다 파일 한두 개로 결과를 확인한 뒤 늘립니다.

클로드를 거치지 않고 터미널에서 직접 변환할 수도 있습니다. 설치 없이 npx로 실행합니다.

명령어
npx kordoc 문서.hwpx -o 문서.md
npx kordoc to-hwpx 문서.hwp -o 문서.hwpx

첫 줄은 한글 문서를 마크다운으로, 둘째 줄은 옛 HWP를 HWPX로 바꿉니다.

쓰기 전에 알아 둘 점

  • 변환 결과 표가 원본과 같은지 직접 대조합니다. 특히 중첩된 표와 스캔 문서는 오류가 생길 수 있습니다.
  • 공문서에는 이름, 주민번호, 연락처 같은 개인정보가 들어 있을 수 있습니다. 변환은 내 컴퓨터에서 이뤄지지만, 변환한 내용을 클로드나 코덱스에 보내면 그 서비스로 전달됩니다. 민감한 문서는 개인정보 마스킹 기능으로 가린 뒤 맡깁니다.
  • 변환 도구의 버전이 자주 올라가는 프로젝트입니다. 명령과 도구 수는 저장소 README를 기준으로 확인합니다.

지우기와 막힐 때

  • 플러그인을 지우려면 /plugin의 Installed 탭에서 kordoc을 선택해 Uninstall을 고르거나 터미널에서 claude plugin uninstall kordoc@kordoc를 실행합니다.
  • MCP로 등록했다면 claude mcp list로 이름을 확인한 뒤 claude mcp remove 이름으로 지웁니다.
  • 도구가 보이지 않는다: 프로그램을 완전히 종료했다가 다시 시작합니다. Node.js가 20 미만이면 업데이트합니다.
  • 스캔한 PDF가 비어서 나온다: npx kordoc 스캔본.pdf --ocr -o 스캔본.md처럼 OCR 옵션을 줍니다.

자주 묻는 질문

HWP와 HWPX는 무엇이 다른가요?

HWPX는 압축된 XML 구조라 열어서 글자와 표 구조를 읽을 수 있는 형식이고, HWP는 한컴 전용 이진 형식입니다. 둘 다 한글 프로그램에서 열리지만 AI가 읽을 때는 HWPX가 훨씬 쉽습니다. kordoc은 두 형식을 모두 읽습니다.

kordoc은 무료인가요?

MIT 라이선스의 오픈소스라 도구 자체는 무료입니다. 다만 클로드 코드나 코덱스 사용량은 그대로 듭니다. 라이선스와 조건은 저장소에서 확인합니다.

한컴오피스가 없어도 HWP를 읽을 수 있나요?

읽을 수 있습니다. kordoc은 HWP 파일 구조를 직접 풀어서 읽기 때문에 한컴오피스가 설치돼 있지 않아도 됩니다. 변환 결과는 원본과 같은 모양이라는 보장은 없으니 중요한 문서는 대조해 봅니다.

변환한 표가 원본과 달라 보이면 어떻게 하나요?

원본과 한 칸씩 대조한 뒤 틀린 부분을 클로드에게 짚어 다시 시키거나 직접 고칩니다. 문서가 스캔 이미지라면 OCR 정확도가 낮을 수 있으니 텍스트가 살아 있는 원본 파일로 다시 시도합니다.

이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.

원본 영상 보러가기 ↗