클로드 코드 한글 깨짐 해결: 입력 밀림부터 설정까지 증상별 정리

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

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

한국어 응답: settings.json 한 줄

Claude Code가 계속 영어로 답한다면 클로드 코드 한국어 설정 또는 클로드 코드가 영어로 답함으로 찾아오셨을 가능성이 큽니다. 이 문제는 설정 파일에 한 줄만 추가하면 해결됩니다. ~/.claude/settings.json 파일을 열어 이 항목을 추가합니다.

{
  "language": "한국어"
}

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

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

Claude Code가 파일을 수정할 권한을 가지고 있고 변경을 승인하면 같은 설정을 넣어 줍니다. 권한 요청이 나오거나 파일을 직접 확인하고 싶다면 위 JSON을 수동으로 추가하면 됩니다.

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

프로젝트마다 다르게 하고 싶거나 더 세밀한 지시가 필요하면 CLAUDE.md에 적는 방법도 있습니다. 다만 단순히 언어만 바꿀 목적이라면 설정 쪽이 간단합니다.

글자 깨짐: /terminal-setup

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

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

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

/terminal-setup

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

참고로 /terminal-setup은 이것만 하지 않습니다. Shift+Enter로 줄바꿈이 되게 하는 키 설정도 같이 넣어 줍니다. 한 번은 실행해 두시는 편이 좋습니다. 단, tmux나 screen 안이 아니라 터미널 본체에서 실행해야 합니다. 터미널 본체의 설정 파일에 써야 하기 때문입니다.

또 다른 문제로, VS Code 확장의 질문 카드에서 한글이 그럴듯해 보이지만 틀린 글자로 깨지는 사례도 보고돼 있습니다. 클로드 코드 VS Code 한글 깨짐으로 찾아왔는데 터미널이 아니라 질문 카드에서만 문제가 생긴다면 이 버그에 해당합니다. 터미널 GPU 문제와는 다르며, 아직 해결되지 않았습니다.

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

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

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

한글 경로: 파일 검색 실패

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

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

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

한글 자판: 단축키 미작동

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

해결은 간단합니다. 단축키를 누르기 전에 한영 전환으로 영문 상태를 만드세요. 근본 해결은 아니지만 지금 당장 되게 하는 방법입니다. 중요한 건 이게 여러분이 뭘 잘못한 게 아니라는 점입니다. 단축키가 안 먹으면 대개 자기 설정을 의심하게 되는데, 이 경우는 알려진 문제입니다.

한글 패치: 필요 없음

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

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