맥에서 HWP 공문, 한글 안 사고 클로드가 표까지 읽게 하는 법

맥에서 HWP 공문, 한글 안 사고 클로드가 표까지 읽게 하는 법

학교 가정통신문이나 관공서 신청서를 받았는데 파일이 .hwp 였던 적 있으세요?
맥에서 더블클릭하면 바로 열리지 않습니다. 맥용 한글은 유료 정식판(한컴오피스 for Mac)이 따로 있어요.
공문 몇 장 보자고 사기엔 아깝고, 안 산 맥에는 열 프로그램이 없습니다.

무료 뷰어를 깔면 보이기는 해요.
그런데 클로드에게 「이 표 정리해 줘」 하려고 파일을 올리면 막힙니다.
한글 파일은 첨부 지원 목록에 없거든요. 2026년 9월 공식 도움말에 PDF·DOCX·XLSX·CSV·TXT 는 있는데 HWP·HWPX 는 빠져 있습니다.

저도 오늘 이걸 제 맥에서 처음부터 끝까지 해 봤습니다.
결론은 맥용 한글을 안 사도 됩니다. 공무원이 만든 무료 도구 하나를 클로드 데스크톱에 붙이면 돼요.
그러면 클로드가 HWP·HWPX 를 직접 읽습니다.
표까지요.

이 글은 그 절차를 제 맥에서 실제로 돌린 화면 그대로 적은 것입니다.
시험 파일은 경남교육청이 공개한 출장신청서 서식(HWPX)이에요.

한글 파일이 클로드에게 읽히기까지 — 받은 HWPX 파일, 심부름꾼 kordoc, 마크다운과 표로 바뀐 모습, 읽는 쪽 클로드까지 4단계 흐름

한글 프로그램 자리를 «변환 심부름꾼» kordoc 이 대신합니다.
파일은 내 맥 밖으로 나가지 않아요

---

1. 결론부터 — 세 줄이면 됩니다

1. 맥에 Node.js 를 깝니다(공식 사이트에서 설치 파일 하나. 아래 준비물)
2. 터미널에 한 줄을 치고 1번을 고릅니다
3. 클로드 데스크톱을 완전히 껐다가 다시 켭니다

npx -y kordoc setup

이걸로 클로드 데스크톱에 「kordoc」이 커넥터로 붙습니다.
커넥터란 클로드에 바깥 도구를 잇는 연결이에요.
그 연결 규격의 이름이 MCP 입니다.
MCP 란 «클로드가 외부 도구를 부르는 약속»이라는 뜻이에요.
이름만 알면 됩니다.

그다음부터는 채팅에서 파일 위치를 알려 주고 「표 뽑아 줘」라고 하면 돼요.

성공

설치 마법사 마지막에 Setup Complete! 상자가 뜹니다.
앱을 다시 켠 뒤 커넥터 목록에 kordoc 이 보이면 된 겁니다.

kordoc 이 뭔가요. 한글·PDF·엑셀 같은 한국 문서를 «마크다운»으로 바꿔 주는 무료 도구입니다.
마크다운이란 클로드가 가장 잘 읽는 «글자만 있는 문서 형식»이에요.
문서 지옥에서 7년 버틴 공무원이 만들었다고 소개돼 있습니다.
코드도 공개돼 있어요(MIT 라이선스).

---

2. 준비물 — 네 가지

확인할 것	왜
맥에 클로드 데스크톱 앱	내 맥의 파일을 읽는 커넥터는 데스크톱 앱에서만 붙습니다. 웹·폰은 안 돼요
Node.js 20 이상	kordoc 이 이 위에서 돕니다. 없으면 nodejs.org 에서 macOS 설치 파일(.pkg) 을 받아 더블클릭
터미널 앱	응용 프로그램 → 유틸리티 → 터미널. 한 줄만 칠 겁니다
시험용 HWP·HWPX 파일	받은 공문이 있으면 그걸로. 없으면 관공서 사이트의 공개 서식 아무거나

⚠️ Node.js 는 개발자 도구지만 설치는 다른 맥 앱과 같습니다.
2026년 9월 기준 공식 사이트의 장기 지원판은 v24.21.0 입니다. .pkg 설치 파일이 있는 걸 확인했어요.
제 맥은 v26 이 이미 깔려 있어서 그대로 썼습니다.

---

3. 따라 하기 — 5단계

Step 1. Node.js 가 있는지 봅니다

터미널을 열고 아래를 칩니다.

node -v

v20 이상 숫자가 나오면 넘어갑니다.
「command not found」가 나오면 .pkg 를 깔고 터미널을 껐다 켜세요.

Step 2. 먼저 한 줄로 «읽히는지» 봅니다

설치보다 이걸 먼저 하는 이유가 있어요. 내가 받은 파일이 진짜 한글 파일인지 여기서 걸러집니다.
5장에 실패 사례가 있어요.

파일을 다운로드 폴더 안 서식 폴더에 넣었다고 칩시다.
터미널에서:

cd ~/Downloads/서식
npx kordoc 출장신청서.hwpx

처음 한 번은 kordoc 을 내려받느라 잠깐 기다립니다.
패키지가 17MB 예요.
제 맥에서는 이렇게 나왔습니다.

터미널에서 npx kordoc 출장신청서.hwpx 를 실행한 결과 — 별지 제3호서식, 출장신청서 제목과 HTML 표가 그대로 출력되고, render 명령으로 미리보기 PNG 가 만들어진 화면

출장신청서 HWPX 가 글자와 표로 풀려 나옵니다.
표는 <table> 로 시작하는 HTML 표예요

여기서 두 가지를 알 수 있습니다.

• 글은 그대로 나옵니다. 「[별지 제3호서식]」 「다음과 같이 출장을 명함.」이 원문 그대로예요
• 표는 HTML 표로 나옵니다. 결재란처럼 합쳐진 칸도 살아 있어요

HTML 표는 사람이 읽기엔 지저분합니다.
하지만 클로드는 이걸 그대로 읽어요. 그래서 이 형식이 오히려 정확합니다.

Step 3. 설치 마법사로 클로드 데스크톱에 붙입니다

npx -y kordoc setup

마법사가 뜨면서 내 맥에 깔린 AI 앱을 알아서 찾아 줍니다.
제 화면입니다.

kordoc 설치 마법사 첫 화면 — MCP 클라이언트 선택 목록에 1번 Claude Desktop 이 「감지됨」으로 표시된 터미널

1번 Claude Desktop 옆에 초록색 「감지됨」이 붙어 있으면 앱을 찾은 겁니다

1 을 치고 엔터를 누릅니다.
설정 파일을 알아서 고치고 끝나요.

kordoc 설치 마법사 완료 화면 — 번호 1 입력 후 Claude Desktop 설정 파일 경로가 표시되고 Setup Complete 상자와 도구 목록이 나온 터미널

「Setup Complete!」 아래에 «클라이언트를 재시작하면 활성화됩니다»라고 알려 줍니다

마법사가 손댄 건 설정 파일 딱 하나입니다.
이 맥에서 실제로 추가된 내용은 이거예요.

"kordoc": {
  "command": "npx",
  "args": ["-y", "kordoc", "mcp"]
}

정보

파일 위치는 ~/Library/Application Support/Claude/claude_desktop_config.json 입니다.
직접 열 일은 없어요.
마법사는 기존 내용을 그대로 두고 이 항목만 붙였습니다.
저는 실행 전에 백업해 두고 전후를 비교했어요.

Step 4. 클로드 데스크톱을 «완전히» 껐다 켭니다

창을 닫는 것으로는 안 됩니다.
클로드 앱은 메뉴 막대에 남아 있어요. ⌘Q 로 종료한 뒤 다시 엽니다.

다시 켜지면 앱이 kordoc 을 스스로 띄웁니다.
제 맥의 앱 기록에는 이렇게 남았습니다.

[kordoc] [info] Server started and connected successfully
[kordoc] [info] Message from client: method="tools/list"

성공

설정 → 커넥터 목록에 kordoc 이 보이면 된 겁니다.
안 보이면 5장의 「껐다 켰는데 안 붙어요」를 보세요.

클로드 데스크톱 설정 → 커넥터 목록 — kordoc 이 유형 «데스크톱 · 로컬 개발», 상태 체크 표시로 올라와 있는 화면

제 맥의 커넥터 목록입니다.
kordoc 옆에 «데스크톱 · 로컬 개발»이 붙어 있으면 내 맥에서 도는 도구라는 뜻이에요

Step 5. 채팅에서 시킵니다

이제 파일 «위치»를 알려 주고 시키면 됩니다.
클로드는 첨부 대신 kordoc 을 불러서 파일을 읽어요.

~/Downloads/서식/출장신청서.hwpx 를 읽고,
표에 있는 칸 이름을 전부 목록으로 정리해 줘.
빈칸은 빈칸이라고 표시하고, 없는 내용은 만들지 마.

클로드 데스크톱 채팅 — 출장신청서.hwpx 를 읽으라는 프롬프트에 «2개의 통합 사용됨» 표시 뒤, 결재·협조란, 출장자 명단(직급·성명·출장목적·출장기간·출장지·서명또는날인), 이동사항 칸 이름을 빈칸 표시와 함께 정리한 답

실제로 보낸 결과입니다. «2개의 통합 사용됨»이 kordoc 을 부른 흔적이에요.
표 위의 「[별지 제3호서식]」까지 본문 그대로 읽었습니다

클로드가 받는 건 Step 2 에서 본 것과 같은 글입니다.
제가 클로드 대신 kordoc 에 직접 물어봐서 확인했어요.
맨 위에 이런 머리말이 붙어 옵니다.

[포맷: HWPX | 페이지: 1 | 제목: 별지 제1호서식 | 작성자: user]

[별지 제3호서식]
**출장신청서**

여기서 재미있는 걸 하나 잡았습니다. 파일 속성의 제목은 「별지 제1호서식」이에요.
그런데 본문은 「별지 제3호서식」입니다.
다른 서식을 복사해 고쳐 쓴 흔적이죠.
관공서 서식엔 이런 게 흔해요.

그래서 프롬프트에 「본문 기준으로」 한마디를 넣는 게 좋습니다.
속성만 보고 답하면 서식 번호부터 틀려요.

모양이 궁금하면 그림으로도 뽑힙니다. 한글 프로그램 없이도요.

npx kordoc render 출장신청서.hwpx --format png -d 미리보기

kordoc render 로 뽑은 출장신청서 미리보기 — 별지 제3호서식, 결재·협조란, 직급·성명·출장목적·출장기간·출장지·서명 칸이 있는 표가 원본 조판대로 그려진 이미지

한글 프로그램 없이 뽑은 미리보기입니다.
결재란 칸 나눔까지 원본과 같아요

같은 파일을 한컴 무료 뷰어로 연 화면과 나란히 놓으면 이렇습니다.

한컴 오피스 HWP 뷰어로 연 출장신청서.hwpx — 별지 제3호서식 제목과 결재·협조란 표가 보이는 맥 화면

뷰어는 «보는» 것까지만 해 줍니다.
클로드에게 «읽히는» 건 별개예요

---

4. 어떤 방식을 고를까

kordoc 하나로 세 가지 길이 있습니다.
갈리는 건 «누가 명령을 치느냐»뿐이에요.

세 갈래 비교 — A 터미널 한 줄로 직접 변환, B 클로드 데스크톱 커넥터로 클로드가 직접 읽음(추천), C 클로드 코드 플러그인으로 폴더째 일괄 처리

이 글의 독자에겐 B 입니다.
한 번만 볼 파일이면 A 로 충분해요

	A. 터미널 한 줄	B. 데스크톱 커넥터	C. 클로드 코드 플러그인
하는 일	파일을 글로 바꿔 화면에 출력	클로드가 파일을 직접 읽음	폴더째 일괄 변환·작성
설치	없음	마법사 한 번	플러그인 설치
클로드에 넣는 법	결과를 복사해 붙임	파일 위치만 말함	자동
맞는 사람	한 번만 볼 때	공문이 자주 오는 분	터미널이 익숙한 분
추천	처음 시험용	추천	이 글 독자에겐 과함

B 를 고르는 이유는 하나예요. 파일을 사람이 옮기지 않아도 됩니다. A 는 매번 복사해 붙여야 해요.
표가 길면 붙이다 잘리고요.

---

5. 막히면 — 증상별 원인과 해결

「지원하지 않는 파일 형식입니다」가 나와요 받은 파일이 진짜 한글 파일이 아닐 수 있습니다. 저도 이 글을 쓰며 두 번 당했어요.
관공서 링크로 받은 .hwp 가 실은 로그인 안내 웹페이지였습니다.
크기가 438바이트, 3.5KB 였어요.
kordoc 은 확장자가 아니라 내용물을 봅니다.
그래서 이런 파일을 바로 거절해요.
파일이 몇 KB 면 의심하고 브라우저에서 다시 받으세요.

껐다 켰는데 커넥터에 안 보여요 앱이 완전히 종료되지 않은 경우가 가장 흔합니다.
메뉴 막대에 클로드 아이콘이 남아 있으면 종료된 게 아니에요. ⌘Q 로 끄고 다시 켜세요.
그래도 안 되면 npx -y kordoc setup 을 한 번 더 돌립니다.
「감지됨」이 붙는지 보세요.

마법사는 15개 도구라는데 목록엔 17개예요 안내문이 조금 낡았습니다.
제가 서버에 직접 물어보니 17개가 나왔어요.
마법사 안내에 없는 표 추출 도구 두 개가 더 있습니다.
어느 쪽이든 문서 읽기·표 뽑기는 다 들어 있어요.

처음 실행이 한참 걸려요 첫 실행 때 kordoc 을 내려받습니다.
17MB 예요.
두 번째부터는 바로 뜹니다.

표 안에 있던 이미지가 안 보여요 글자만 나오고 이미지는 자리 표시만 남습니다.
교육청 보도자료 HWP 로 시험해 봤어요.
기관 로고가 image_001.jpg 라는 자리로만 나왔습니다.
로고·도장은 그러려니 하시면 됩니다.

스캔한 PDF 라 글자가 안 나와요 스캔본은 글자층이 없습니다.
kordoc 에 내장 OCR(글자 인식) 옵션이 있어요(--ocr).
첫 사용 때 모델 18MB 를 받는다고 문서에 적혀 있습니다.
저는 이번엔 시험하지 않았어요.

비밀번호 걸린 문서예요 --password 옵션이 있다고 공식 문서에 적혀 있습니다.
직접 해 보진 않았습니다.

주의

kordoc 은 내 맥 안에서만 돕니다. 파일을 어디로 보내지 않아요.
하지만 클로드가 «읽은» 내용은 다른 대화처럼 앤트로픽 서버로 갑니다.
주민번호·계좌가 든 민원 서류라면 그 부분을 지운 뒤 시키세요.
kordoc 에 개인정보 가리기 기능(redact)도 있지만 이번엔 시험하지 않았습니다.

•••

6. 자주 묻는 것

Q. 한컴오피스 맥 버전을 사면 해결되나요? A. «보고 고치는» 건 됩니다.
하지만 클로드가 읽는 문제는 그대로예요.
첨부 지원 목록에 HWP 가 없는 건 프로그램을 사도 안 바뀝니다.
보기만 할 거면 앱스토어의 무료 뷰어로 충분해요.
클로드에게 읽히려면 이 글의 방법이 필요합니다.

Q. 옛날 .hwp 도 되나요? A. 제가 시험한 건 HWPX 세 개와 HWP 5.x 보도자료 하나입니다.
넷 다 됐어요.
더 오래된 HWP 3.x 는 문서상 지원한다고 돼 있습니다.
직접 해 보진 않았어요.

Q. 클로드 웹(claude.ai)에서도 되나요? A. 안 됩니다.
내 맥의 파일을 읽는 커넥터는 데스크톱 앱 전용이에요.
웹·아이폰에서는 여전히 첨부만 됩니다.

Q. 거꾸로 클로드가 한글 파일을 만들어 줄 수도 있나요? A. kordoc 에 마크다운을 HWPX 로 만드는 도구가 있습니다.
공문서 서식까지 낸다고 돼 있어요.
이번 글에선 «읽기»만 다뤘습니다.
만들기는 시험하지 않았어요.

Q. 윈도우도 같은가요? A. 공식 문서는 맥·윈도우·리눅스 공용이라고 합니다.
저는 맥에서만 해 봤어요.

---

7. 다음 단계

커넥터를 하나 붙였습니다.
이제 클로드에게 «없는 내용을 만들지 말라»는 안전장치를 같이 챙기면 좋아요.
서식 번호처럼 사소한 데서 틀리거든요.

• 프롬프트마다 붙이는 세 줄 → 모든 프롬프트에 넣어야 할 안전장치 3줄 — 추측 금지·없으면 없다고·근거 명시
• 민원 서류를 넣기 전에 → 클로드에 넣으면 안 되는 것 + 3초 판단 프레임
• 표를 뽑은 다음 무엇을 시킬지 → 클로드에게 일 시키는 법 — 역할·맥락·목표·형식 네 기둥

---

이 글의 터미널·변환·미리보기 화면은 2026년 9월 25일 제 맥에서 직접 찍은 것입니다(클로드 데스크톱 2.9939, kordoc 4.15.3, Node v26).
시험 파일은 경남교육청 공개 게시판의 서식 HWPX 세 개와 전남고흥교육지원청 보도자료 HWP 입니다.
kordoc 은 갱신이 잦아 도구 이름과 개수는 바뀔 수 있습니다.