HWP · 설치 안내

HWP 스킬 설치 가이드

hwpx 전용 스킬의 빈틈을 채우는 공개 도구 kordoc을 클로드 데스크톱·클로드 코드에 한 번 연결해, 구형 .hwp까지 그대로 읽고 고치는 절차를 정리했습니다.

2026. 9. 19. 컴퓨터 1대당 1번 · 5분 · 무료(MIT) 3차시 부록 114~120장에서 분리
hwpx 스킬 두 개를 먼저 등록했다면, 이 페이지는 그 다음 단계입니다 hwpx 스킬 설치 가이드 ← 3차시 부록 화면 보기 ↗

01왜 따로 설치하나요 — .hwp와 .hwpx는 다릅니다

앞에서 등록한 두 스킬(korean-doc-writer-pro · new-hwpx-master)은 hwpx(XML) 전용입니다. 학교에 아직 많은 구형 .hwp(5.x 바이너리) 파일은 열지 못하므로, 데스크톱·클로드 코드에는 kordoc을 붙여 둡니다.

기존 두 스킬

hwpx 전용

  • claude.ai 웹에 .skill 업로드
  • hwpx 작성·수정 ○
  • 구형 .hwp 읽기 ✕
kordoc 이란?

현직 공무원이 만든 공개 도구

  • HWP 3.x/5.x · HWPX · PDF 읽기
  • 원본 서식 그대로 글자·표 셀만 수정
  • 마크다운 → 공문서 hwpx 생성
  • 한컴오피스 없어도 동작 · 무료
출처 · github.com/chrisryugj/kordoc (v4.14.0)
어디서 쓰나요kordoc대신 이렇게
클로드 데스크톱○ 방법 A—
클로드 코드(CLI)○ 방법 B—
claude.ai 웹✕한글에서 [다른 이름으로 저장] → hwpx 로 바꿔 첨부
한 줄 요약 웹은 hwpx로 바꿔 첨부, 데스크톱·클로드 코드는 kordoc 한 번 설치하면 .hwp를 그대로 읽고 고칩니다.

02준비물 — Node.js 하나면 됩니다

kordoc은 Node.js 위에서 돌아갑니다. 한컴오피스는 필요 없습니다. 4차시 클로드 코드 설치 때 Node를 깔았다면 이미 준비 끝입니다.

  1. Node.js가 있는지 확인

    윈도우 키 → cmd 입력 → Enter → 검은 창에 node --version 입력. v18 이상이 나오면 통과입니다.

  2. 없으면 설치 (3분)

    nodejs.org 접속 → 초록색 LTS 버튼 → 내려받은 파일 실행 → 전부 [다음] → 설치 후 cmd 창을 새로 열어 1번을 다시 확인합니다.

  3. 인터넷 연결

    처음 실행할 때 kordoc을 자동으로 내려받습니다(1~2분). 이후엔 캐시에서 바로 뜹니다.

  4. 한컴오피스는 필요 없음

    kordoc은 파일을 직접 해석하므로 한글 프로그램이 없는 PC에서도 됩니다. 설치돼 있어도 충돌 없습니다.

⚠ PowerShell(파란 창) 말고 cmd(검은 창)를 쓰세요 — 파워셸은 보안 정책 때문에 npx 실행이 막히는 경우가 있습니다.

03방법 A · 클로드 데스크톱에 연결하기

설정 파일에 다섯 줄만 붙여넣으면 끝. 스토어판·설치판 모두 같습니다. (3차시 117장)

  1. 설정 → 개발자 → [구성 편집]

    왼쪽 아래 내 이름 → 설정 → 왼쪽 메뉴 개발자(Developer) → 구성 편집 클릭. 폴더가 열리며 claude_desktop_config.json 이 표시됩니다.

  2. 메모장으로 열어 아래 내용 붙여넣기

    파일을 우클릭 → 연결 프로그램 → 메모장. 내용이 비어 있으면 통째로, 이미 "mcpServers" 가 있으면 "kordoc": { … } 부분만 그 안에 추가하고 저장합니다.

    {
  "mcpServers": {
    "kordoc": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "kordoc", "mcp"]
    }
  }
}

    💡 타이핑이 귀찮다면 cmd 창에서 npx -y kordoc setup 을 실행하세요. 마법사가 "Claude Desktop" 번호를 고르라고 묻고 위 내용을 자동으로 넣어 줍니다.

  3. 데스크톱 완전 종료 후 다시 실행

    창만 닫으면 안 됩니다. 트레이의 Claude 아이콘 우클릭 → 종료 → 다시 실행. 대화창의 도구 목록에 kordoc 이 보이면 성공.

04방법 B · 클로드 코드(CLI)에 연결하기

둘 중 하나만 해도 되고, 둘 다 해도 됩니다. 새 세션을 시작해야 적용됩니다. (3차시 118장)

  1. MCP 도구로 등록 (권장) — 🖥 cmd 창에서

    cmd 창(검은 창)을 열고 아래 한 줄을 그대로 입력합니다.

    claude mcp add --scope user kordoc -- cmd /c npx -y kordoc mcp

    확인: claude mcp list → kordoc … ✔ Connected

    • 모든 프로젝트에서 공통으로 쓰려고 --scope user 를 붙였습니다.
    • Git Bash에서 실행하면 /c 가 C:/ 로 바뀌어 깨집니다 → 반드시 cmd에서.
    • 삭제: claude mcp remove kordoc -s user

  2. 스킬(플러그인)로 등록 — 💬 클로드 코드 대화창 안에서

    두 줄을 차례로 입력합니다.

    /plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc

    확인: /plugin → 설치됨 목록에 kordoc

    • .hwp/.hwpx 를 말하거나 공문서 생성을 부탁하면 스킬이 자동 활성화됩니다.
    • 내부에서 npx -y kordoc 을 호출하므로 Node.js만 있으면 됩니다.
    • hwpx 스킬 가이드의 .skill 업로드와는 다른 경로(터미널용)입니다.
구분하세요 — 🖥 cmd 창에서 하는 "터미널 명령"과 💬 클로드 코드 안에서 하는 "/슬래시 명령". 1번은 cmd, 2번은 클로드 코드 안입니다.

05설치 확인 — 이렇게 부탁하면 됩니다

파일 경로만 알려 주면 끝. 첨부 대신 "어디에 있는 파일"인지 말합니다. 데스크톱은 파일을 끌어다 놓아도 됩니다. (3차시 119장)

나클로드
"C:\연수\2027 사업계획서.hwp 읽어서 표만 정리해 줘""kordoc parse_document 로 읽었습니다 — 표 3개, 병합 셀 포함 그대로 정리했어요."
"2번 표 '담당자' 칸을 홍길동으로 바꿔서 저장해 줘""patch_document 로 원본 서식은 그대로 두고 1곳만 고쳐 …patched.hwp 로 저장했습니다."
💡 자주 쓰는 도구(17개 중) — parse_document 읽기 · patch_document 서식 보존 수정 · fill_form 양식 빈칸 채우기 · generate_document 공문서 생성 · compare_documents 신구대조표. 원본은 건드리지 않고 …patched.hwp 로 따로 저장되니 안심하고 시켜 보세요. 한글로 열어 결과를 확인합니다.

06막힐 때 체크리스트 · 출처

증상해결
'npx'은(는) 내부 또는 외부 명령… 이 아닙니다Node.js가 없거나, 설치 직후 예전 cmd 창을 그대로 쓴 경우. 설치 후 cmd 창을 새로 여세요.
파워셸에서 npx.ps1 … 보안 오류(PSSecurityException)파워셸 기본 보안 정책 때문. 파란 창을 닫고 검은 cmd 창에서 같은 명령을 실행하면 됩니다.
도구 목록에 kordoc이 안 보여요앱을 트레이에서 완전히 종료한 뒤 재실행. JSON의 쉼표·따옴표 짝이 맞는지, 클로드 코드는 새 세션인지 확인.
파일이 안 읽혀요 (UNSUPPORTED_FORMAT)크기가 0~1KB면 빈 껍데기 파일. 한컴 DRM·배포용 보안문서는 불가. 암호 문서는 --password 옵션 필요.
출처 — github.com/chrisryugj/kordoc (MIT, v4.14.0) · npm "kordoc" · 설치 검증: 윈도우 11 + Node 24, 데스크톱·클로드 코드 양쪽에서 실제 .hwp 읽기·수정 확인 (2026. 9. 19.)
한컴 공식 GitHub는 왜 안 쓰나 — github.com/hancom-io 에는 개발자용 C++ 라이브러리(hwpx-owpml-model, 2023년 이후 갱신 없음)만 있고 클로드에 바로 붙는 도구가 없어, 가장 활발한 공개 도구인 kordoc을 채택했습니다.