Claude Code에서도 한글이 깨집니다

Codex에서 한글이 깨지는 문제는 이미 잘 알려져 있습니다. 클라우드 샌드박스의 로케일 설정 때문이었죠. 그런데 Claude Code는 로컬에서 실행되니까 괜찮을 거라 생각하기 쉽습니다.

결론부터 말하면, Claude Code에서도 한글 깨짐이 발생합니다. 다만 원인이 완전히 다릅니다.

Codex vs Claude Code — 한글 깨짐의 근본 차이

두 도구의 아키텍처가 다르기 때문에 한글 문제의 양상도 다릅니다.

항목	Codex	Claude Code
실행 환경	클라우드 샌드박스 (컨테이너)	로컬 터미널 (내 컴퓨터)
로케일	강제 C.UTF-8 / en_US.UTF-8	시스템 로케일 상속
주요 원인	샌드박스 로케일 고정 + 레거시 인코딩 충돌	Rust 바이트 경계 분할 버그
EUC-KR 파일	UTF-8로 간주해서 깨짐	로컬 도구가 처리하므로 정상
해결 난이도	사용자가 사전 변환 필요	Anthropic 측 패치 대상

Codex는 환경 자체가 한글에 불리합니다. 반면 Claude Code는 내 컴퓨터에서 돌아가므로 로케일 문제는 없지만, 모델 출력 스트리밍 과정에서 한글이 깨지는 별도 버그가 있습니다.

Claude Code 한글 깨짐의 실제 원인

Rust 바이트 경계 분할 (U+FFFD 치환)

Claude Code는 Rust로 만들어져 있습니다. 한글 한 글자는 UTF-8에서 3바이트를 차지하는데, 스트리밍 출력 시 JSON 청크가 바이트 단위로 잘리면서 멀티바이트 문자가 중간에 끊기는 문제가 발생합니다. 이때 한글이 U+FFFD(�)로 치환됩니다.

2026년 4월에 이 문제의 주요 수정이 이루어졌지만, 간헐적으로 재발한다는 보고가 있습니다.

macOS 한글 폴더명 정규화 문제

macOS는 파일시스템에서 유니코드 NFD(분해형)를 사용합니다. "한글"이라는 폴더명이 NFD로 저장되면, NFC(조합형)를 기대하는 Claude Code 내부 매칭 로직과 충돌할 수 있습니다.

Windows 한글 사용자명 경로

Windows에서 사용자 이름이 한글인 경우(예: C:\Users\김철수\), Claude Code가 경로를 처리하다 크래시가 발생하는 사례도 보고되었습니다.

Glob 패턴에서 한글 매칭 실패

Claude Code의 파일 검색(Glob) 기능이 한글·CJK 문자를 포함한 와일드카드 패턴을 제대로 처리하지 못하는 버그도 확인되었습니다.

지금 바로 할 수 있는 해결법

터미널 UTF-8 확인

Claude Code는 시스템 로케일을 상속하므로, 터미널이 UTF-8인지 확인하는 게 첫 번째입니다.

[code lang="bash"]

macOS / Linux

echo $LANG

ko_KR.UTF-8 또는 en_US.UTF-8이면 정상

설정되어 있지 않다면

export LANG=ko_KR.UTF-8 export LC_ALL=ko_KR.UTF-8 [/code]

한글 폴더명 회피 (macOS)

프로젝트 폴더명에 한글을 쓰고 있다면, 영문으로 변경하는 것이 안전합니다. NFD/NFC 정규화 문제를 근본적으로 피할 수 있습니다.

Windows 사용자명이 한글인 경우

영문 사용자 계정을 별도로 만들거나, USERPROFILE 환경 변수를 영문 경로로 오버라이드하는 방법이 있습니다.

Claude Code 최신 버전 유지

U+FFFD 치환 버그는 2026년 4월 패치에서 주요 수정이 이루어졌습니다. 항상 최신 버전을 사용하세요.

[code lang="bash"]

업데이트 확인

claude --version

npm으로 설치한 경우

npm update -g @anthropic-ai/claude-code [/code]

Codex 사용자가 Claude Code로 넘어올 때 알아야 할 것

Codex에서 한글 때문에 고생했던 분이라면 좋은 소식이 있습니다.

• EUC-KR/CP949 레거시 파일: Codex는 무조건 UTF-8로 읽어서 깨졌지만, Claude Code는 로컬 도구(iconv 등)가 그대로 동작하므로 별도 변환이 필요 없습니다
• 한글 변수명/주석: Codex 샌드박스에서는 로케일 문제로 불안정했지만, Claude Code는 로컬 실행이라 대부분 정상 동작합니다
• 파일 I/O: Codex는 샌드박스 안에서 파일을 읽고 쓰므로 인코딩 제어가 어려웠지만, Claude Code는 내 시스템의 파일시스템을 직접 사용합니다

다만 스트리밍 출력에서의 간헐적 깨짐은 Codex에 없던 Claude Code 고유의 문제이므로, 이 부분은 주의가 필요합니다.

Claude Code 한글 관련 GitHub 이슈 현황

2026년 5월 기준, Claude Code 저장소에 보고된 한글·CJK 관련 주요 이슈입니다.

이슈	내용	상태
#55949	OTEL 텔레메트리에서 한글 값 누락	Open
#55588	Glob 도구가 한글 와일드카드 매칭 실패	Open
#55508	pptx/docx 미리보기에서 한글 깨짐 (macOS)	Open
#55388	대화 검색(Cmd+F)에서 CJK 문자열 검색 불가	Open

아직 열려 있는 이슈가 대부분이지만, Anthropic이 활발하게 대응하고 있어 점진적으로 개선되고 있습니다.

Claude Code 한글 깨짐, 정리하면

Claude Code의 한글 문제는 Codex와 근본 원인이 다릅니다. Codex는 클라우드 샌드박스 로케일이 원인이라 사용자가 사전 변환을 해야 했지만, Claude Code는 로컬 실행이라 대부분 정상 동작합니다. 다만 Rust 스트리밍 버그, macOS NFD 정규화, Windows 한글 경로 등 별도 이슈가 있으므로 위의 해결법을 적용해 두면 대부분의 문제를 피할 수 있습니다.