클로드 코드 한글 설정과 깨짐 해결: 증상별 점검법

Claude Code(클로드 코드)를 사용하다 보면 한글과 관련된 문제를 몇 가지 마주치게 됩니다. 영어로 답하거나, 터미널에서 글자가 깨지거나, 한글이 들어간 폴더의 파일을 찾지 못하는 식입니다. 문제마다 원인과 해결 방법이 다르므로, 이 글에서는 증상별로 나눠 정리합니다.

설정 한 줄로 해결되는 문제도 있고, 터미널이나 편집기 설정을 바꿔야 하는 문제도 있습니다. 아래 표에서 내 증상에 해당하는 행을 먼저 찾아보세요.

한국어 설정: "답해 줘"가 아니라 "설정해 줘"

Claude Code가 계속 영어로 답한다면 클로드 코드 한국어 설정 또는 클로드 코드가 영어로 답함으로 찾아오셨을 가능성이 큽니다.

"한국어로 답해 줘"라고 하면 그 대화에서는 한국어로 답합니다. 하지만 그것은 설정 파일을 건드리지 않는 단발성 요청입니다. 설정은 그대로이니 다른 대화를 열면 다시 영어로 답합니다. 답하는 언어를 정하는 것은 설정 값이기 때문입니다.

그래서 요청에 "설정"을 넣어야 합니다. "언어 설정을 한국어로 바꾸고 계속 한국어로 답해 줘"처럼 말하면 설정 파일을 고치는 작업으로 받아들입니다. Claude Code는 지침을 파일로 기록해 관리하기 때문에, 파일을 고치라는 요청인지 지금만 그렇게 해 달라는 요청인지에 따라 결과가 갈립니다.

직접 고치려면 ~/.claude/settings.json 파일을 열어 이 항목을 추가합니다.

{
  "language": "한국어"
}

파일이 없으면 새로 만들면 되고, 이미 다른 설정이 들어 있다면 그 안에 항목만 추가하면 됩니다. 설정 파일을 직접 열지 않고 Claude Code(클로드 코드)에게 요청해도 됩니다. 아래 문장을 그대로 복사해 붙여넣으세요.

~/.claude/settings.json의 language 값을 "한국어"로 추가하거나 변경해서 기본 응답 언어를 한국어로 설정해 주세요. 기존 설정은 유지해 주세요.

이 설정 하나가 Claude(클로드)의 기본 응답 언어, 음성 받아쓰기 언어, 자동으로 붙는 세션 제목의 언어를 함께 바꿉니다. 공식 문서는 "japanese", "spanish", "french" 같은 영어 이름을 예시로 보여주지만 "한국어"처럼 한국어로 적어도 동작합니다. 매번 "한국어로 답해 줘"를 붙이고 계셨다면 이 한 줄로 끝납니다.

프로젝트마다 답변 규칙을 다르게 두거나 말투와 형식까지 정하려면 CLAUDE.md가 맞습니다. 언어 하나만 바꾸려면 settings.json이 간단합니다.

글자 깨짐: /terminal-setup

한글이 네모나 뭉개진 모양, 엉뚱한 글자로 보일 때 클로드 코드 한글 깨짐이나 클로드 코드 글자 깨짐으로 찾아오셨다면 이 문제에 해당할 가능성이 큽니다. VS Code, Cursor(커서), 데빈 데스크톱의 내장 터미널에서 Claude Code를 쓸 때 주로 나타납니다.

전각 문자(wide character)

한글이 유독 터미널에서 문제가 되는 이유는 글자 한 자가 영문 두 칸 너비를 차지하기 때문입니다. 화면 위치를 칸 수로 계산하는 프로그램은 이 폭을 잘못 세면 글자가 밀리거나 겹칩니다.

공식 문서는 원인으로 터미널의 GPU 가속을 안내합니다. 터미널이 그래픽 카드로 화면을 그리는 방식인데, 한글처럼 폭이 넓은 글자를 표시할 때 문제가 생길 수 있습니다.

해결은 Claude Code 안에서 이걸 치면 됩니다.

/terminal-setup

이 명령이 편집기 설정의 terminal.integrated.gpuAcceleration을 "off"로 바꿉니다. 바꾼 뒤 편집기 창을 다시 불러오면 적용됩니다. 직접 바꾸셔도 됩니다. 편집기 설정에서 그 항목을 찾아 off로 두면 같습니다. 되돌리려면 "auto"로 바꾸고 창을 다시 불러오면 됩니다.

이 명령은 Shift+Enter 줄바꿈 키 설정도 같이 넣어 주니 한 번은 실행해 두시는 편이 좋습니다.

그런데 화면이 아니라 글자 자체가 바뀌는 경우가 있습니다. 추천이 추첸이 되는 식으로, 읽히기는 하는데 뜻이 없는 단어가 섞입니다. 앞의 GPU 문제와 달리 터미널을 바꿔도 그대로입니다.

이건 2026년 8월에 원인이 밝혀졌습니다. Claude Code가 화면에 선택지를 띄우거나 할 일 목록을 만들 때는 그 내용을 값으로 정리해 넘기는데, 이때 한글을 글자 그대로 쓰지 않고 한 같은 코드값으로 쓸 때가 있습니다. 그 코드값을 틀리게 적는 것이 원인입니다. 한 자리만 틀려도 다른 글자가 되고, 틀린 결과도 멀쩡한 한글이라 아무 시스템도 걸러내지 못합니다. 공식 저장소의 비교 실험에서는 코드값으로 쓴 실행이 전부 깨졌습니다.

판별은 쉽습니다. 네모나 물음표로 보이면 화면 문제, 읽히는데 뜻이 없으면 이 문제입니다.

겪는 분과 안 겪는 분이 갈립니다. 코드값으로 쓸지 말지 자체가 그때그때 다르고, 개발사 쪽에서 세 번 돌려도 재현되지 않은 기록이 남아 있습니다. 한 번도 못 보셨다면 운이 좋은 쪽이지 설정이 다른 게 아닙니다.

공식 수정본은 아직 없습니다. 대신 이슈에 우회책이 제안돼 있고, 해 볼 만합니다. CLAUDE.md에 아래 한 줄을 넣습니다.

Always write Korean (and other non-ASCII) strings in tool-call parameters
as literal UTF-8; never as \uXXXX unicode escapes.

「넘기는 값에 한글을 쓸 때는 코드값이 아니라 글자 그대로 쓰라」는 지시입니다. 원인이 「코드값을 쓸 때 틀린다」였으니 아예 안 쓰게 만든다는 발상입니다. 넣은 뒤에는 새 세션을 여세요. 실행 중인 세션은 이미 읽은 CLAUDE.md로 돌고 있어 반영되지 않습니다.

다만 이 우회책은 제안자의 실험 외에 아직 독립 확인이 없고, 공식 수정도 아닙니다. 지시문 한 줄이라 잘못돼도 잃을 게 없으니 넣어 두시되, 한글이 중요한 작업은 결과를 한 번 읽어 보시는 편이 좋습니다.

윈도우 인코딩: 네모와 물음표는 원인이 다르다

네모(□)와 물음표(?)를 한 묶음으로 보면 엉뚱한 데를 고치게 됩니다. 네모는 글꼴에 그 글자가 없을 때, 물음표는 인코딩이 어긋났을 때 나옵니다. 같은 터미널의 다른 프로그램에서도 깨지는지, 다른 터미널에서는 보이는지 먼저 비교해 보세요. 그 프로그램에서만 깨진다면 글꼴 쪽입니다.

인코딩 쪽이라면 한 가지 주의할 것이 있습니다. 인터넷에는 chcp 65001로 콘솔을 UTF-8로 바꾸라는 안내가 많은데, Claude Code에서는 이게 역효과일 수 있습니다. 콘솔 코드 페이지는 프로그램마다 따로 갖는 값이 아니라 콘솔 전체가 공유하는 값이라, 작업 중에 이 값이 바뀌면 그 뒤 출력이 깨집니다. 공식 저장소에 이 문제가 열린 채로 올라와 있습니다.

그래서 세션 도중에 코드 페이지를 바꾸지 않는 편이 낫습니다. 바꿔야 한다면 Claude Code를 시작하기 전에 바꾸고, 바꾼 뒤 새로 여세요. 파일이 깨져 저장되는 경우는 또 다른 문제이고, PowerShell 스크립트와 배치 파일에서 각각 열린 이슈가 있습니다.

한글 입력: 화면 겹침과 표시 오류

한글을 입력할 때 후보 창이 입력 영역을 덮거나 화면이 밀린다면 클로드 코드 한글 입력 안 됨이나 클로드 코드 IME로 찾아오셨을 수 있습니다. 이건 Claude Code보다 터미널 프로그램 쪽 문제인 경우가 많습니다. 공식 저장소에는 윈도우 터미널에서 입력기(IME) 후보 창이 입력 영역을 덮는 사례, 젯브레인스 계열 편집기에서 한중일 문자를 드래그할 때 강조 표시가 어긋나는 사례가 올라와 있습니다. 뒤쪽은 그 터미널에서만 재현됩니다.

그래서 첫 번째 시도는 터미널을 바꿔 보는 것입니다. 편집기 내장 터미널을 쓰고 계셨다면 맥의 기본 터미널이나 윈도우 터미널처럼 독립된 터미널에서 열어 보세요. 증상이 사라진다면 원인이 편집기 쪽이라는 뜻입니다.

한글 경로: 파일 검색 실패

파일은 분명히 있는데 파일을 찾을 수 없습니다가 나오고, 클로드 코드 한글파일이나 클로드 코드 한글 경로를 찾아보셨다면 이 항목일 가능성이 높습니다. 공식 저장소에는 윈도우에서 경로에 한글이 들어 있으면 파일 검색이 "파일을 찾을 수 없습니다"를 반환하는 버그가 올라와 있습니다. 한국어로 설정된 윈도우 환경에서 재현됐고, 작업 폴더 경로에 한글이 있을 때 발생합니다.

아직 열려 있는 이슈입니다. 고쳐지기 전까지는 우회하는 수밖에 없습니다. 우회 방법은 작업 폴더 경로에서 한글을 빼는 것입니다. 예를 들어 바탕화면의 "내 프로젝트" 폴더 대신 C:\projects 같은 영문 경로로 옮기면 됩니다. 번거롭지만 지금으로선 이게 확실합니다.

애초에 개발 관련 폴더는 영문 경로로 만들어 두는 편이 안전합니다. Claude Code만의 문제가 아니라 터미널을 쓰는 도구 전반에서 한글 경로는 종종 말썽을 일으킵니다.

한글 자판: 단축키 미작동

한글 자판에서 단축키가 안 먹는다면 클로드 코드 한글 단축키 안 됨이나 클로드 코드 Ctrl+V 안 됨으로 찾아보셨을 수 있습니다. 의외로 겪는 분이 많은데 원인을 모르고 넘어가기 쉬운 항목입니다. 한글 입력 상태에서 Ctrl 조합 단축키가 동작하지 않는 경우가 있습니다. 공식 저장소에 맥의 두벌식 한글 입력기를 쓸 때 Ctrl+V 같은 단축키가 안 먹는다는 보고가 있습니다. 영문 입력 상태로 바꾸면 정상 동작한다고 적혀 있습니다.

해결은 간단합니다. 단축키를 누르기 전에 한영 전환으로 영문 상태를 만드세요. 근본 해결은 아니지만 지금 당장 되게 하는 방법이고, 설정을 잘못하신 게 아니라 알려진 문제입니다.

한글 패치: 필요 없음

클로드 코드 한글 패치나 클로드 코드 한국어 패치를 검색하셨다면, 그런 건 없고 필요하지도 않습니다. Claude Code는 처음부터 한국어를 지원합니다. 공식 문서도 한국어판이 따로 제공됩니다.

한국어로 쓰기 위해 하실 일은 앞에서 다룬 설정 한 줄이 전부입니다. 어딘가에서 받아 덮어써야 하는 한글 패치 파일 같은 건 존재하지 않습니다. 출처가 불분명한 파일을 받아 설치하라는 안내가 있다면 따르지 마세요.

한글 문제를 잡았다면 다음은 설정 파일 자체입니다. 방금 만진 settings.json 옆에는 Claude에게 프로젝트 규칙을 알려 주는 파일이 하나 더 있는데, 무엇을 적고 무엇을 적지 않을지는 CLAUDE.md 작성법과 위치에 정리했습니다. Claude Code를 이제 막 열어 보신 거라면 클로드, 코워크, 클로드 코드 차이부터 보시는 편이 순서가 맞습니다.