클로드 코드 한글 깨짐 — 입력 밀림과 출력 깨짐 해결

클로드 코드에서 한글이 이상할 때는 두 가지를 먼저 갈라야 합니다. ① 화면에 찍힌 글자가 ?덈뀞?섏꽭?? 처럼 깨져 보이면 터미널 코드페이지 문제라 chcp 65001 로 고칩니다. ② 한글을 칠 때 자모가 흩어지거나 조합 중인 글자가 엉뚱한 자리에 뜨면 IME 조합 문제인데, 이건 원인이 클로드 코드의 화면 그리는 방식에 있어서 설정 하나로 깔끔히 끝나지 않습니다. 아래는 공식 문서와 공식 이슈 트래커에서 확인한 내용을, 윈도우 11 · Claude Code 2.1.204 · Node v24.16.0 에서 직접 값을 찍어 보며 정리한 것입니다. (2026년 9월 3일 확인)

1. 내 증상은 어느 쪽인가

이 둘은 원인도 해결책도 다릅니다. 엉뚱한 쪽을 붙잡고 있으면 시간만 버립니다.

증상	원인	고치는 곳
출력이 ?덈뀞? 같은 글자로 나온다	콘솔이 UTF-8 바이트를 cp949로 읽음	터미널 (코드페이지)
한글이 네모·물음표로만 보인다	폰트에 한글 글리프가 없음	터미널 (글꼴)
칠 때 자모가 흩어지거나 커서가 밀린다	IME 조합창이 붙을 커서가 딴 데 있음	클로드 코드 (환경변수·렌더러)
복사해서 붙이면 깨진 글자가 된다	화면은 멀쩡한데 복사 바이트가 깨짐	클로드 코드 (렌더러)

2. 출력이 깨질 때 — 코드페이지부터 본다

먼저 chcp 로 지금 콘솔이 쓰는 코드페이지를 봅니다. 65001이 UTF-8이고, 한국어 윈도우의 기본값은 949입니다.

chcp
Active code page: 65001

chcp 65001

제 PC에서 실제로 찍어 보니 현재 세션은 65001이었지만, 시스템 기본 ANSI 코드페이지는 여전히 949였습니다. 즉 터미널을 새로 열었을 때 949로 시작하는 환경이 흔합니다. 이 값은 레지스트리에서 바로 확인됩니다.

(Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage' -Name ACP).ACP
949

파워셸이라면 세션 안에서 출력 인코딩을 UTF-8로 못박아 둘 수도 있습니다.

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

💡 깨진 글자 모양으로 원인을 역추적할 수 있습니다. "안녕하세요"의 UTF-8 바이트를 cp949로 읽으면 ?덈뀞?섏꽭?? 가 되고, 반대로 cp949 바이트를 UTF-8로 읽으면 물음표 마름모(�)가 줄지어 나옵니다. 앞쪽 모양이면 콘솔이 949, 뒤쪽 모양이면 UTF-8 콘솔에 949 파일을 흘려보낸 것입니다.

여기서 한 가지 짚을 게 있습니다. 코드페이지를 949로 두고 Node로 한글을 찍은 뒤 나가는 바이트를 그대로 받아 비교해 봤더니, 65001일 때와 완전히 같은 UTF-8 바이트(EC 95 88 EB 85 95 …)였습니다. 프로그램은 항상 UTF-8로 내보내고 있고, 깨지는 지점은 콘솔이 그 바이트를 해석하는 순간이라는 뜻입니다. 그래서 이 증상은 클로드 코드 설정이 아니라 터미널 쪽에서 고치는 게 맞습니다.

3. 한글 입력이 밀릴 때 — 원인은 '그려진 커서'

이쪽이 진짜 골치입니다. 공식 이슈 트래커에 원인이 정리돼 있습니다. 클로드 코드의 터미널 UI는 키 입력을 raw 모드로 직접 읽고 커서를 글자로 그려서 표시합니다. 그런데 윈도우·맥의 IME는 진짜 커서(캐럿) 위치에 조합창을 붙입니다. 둘이 따로 놀기 때문에 조합 중인 글자가 입력줄이 아닌 화면 구석에서 만들어졌다가 완성되고 나서야 제자리에 박히는 일이 생깁니다.

공식 문서에 있는 환경 변수 중 이 지점을 직접 건드리는 것은 두 개입니다.

환경 변수	공식 문서가 설명하는 동작
CLAUDE_CODE_NATIVE_CURSOR=1	그려진 블록 대신 터미널 자신의 커서를 입력 캐럿 자리에 보여준다
CLAUDE_CODE_ACCESSIBILITY=1	네이티브 터미널 커서를 계속 보이게 하고, 반전 표시 커서를 끈다

파워셸이면 이렇게 켜 봅니다.

$env:CLAUDE_CODE_NATIVE_CURSOR = "1"
claude

매번 치기 번거로우면 설정 파일의 env 키에 넣어 두면 됩니다. 설정 파일이 어디에 있고 어느 것이 이기는지는 클로드 코드 설정 파일 위치와 우선순위 글에 정리해 뒀습니다.

{
  "env": {
    "CLAUDE_CODE_NATIVE_CURSOR": "1"
  }
}

⚠️ 이 변수들이 조합 문제를 완전히 없애 준다고는 공식 문서 어디에도 적혀 있지 않습니다. 실제로 백그라운드 에이전트 화면(claude agents)에서는 CLAUDE_CODE_NATIVE_CURSOR=1 을 켜도 조합창이 화면 왼쪽 아래에 붙더라는 보고가 이슈로 올라와 있습니다. 근본 해결은 아직 열린 이슈입니다.

4. 렌더러를 바꿔 보기 — /tui default 와 fullscreen

클로드 코드에는 화면을 그리는 방식이 두 가지 있습니다. 클래식(터미널 본화면에 그대로 출력)과 전체 화면(vim처럼 대체 화면 버퍼를 차지, 깜빡임 없음)입니다. 대화 중에 바로 바꿀 수 있습니다.

/tui              <- 지금 어느 렌더러인지 출력
/tui default      <- 클래식으로
/tui fullscreen   <- 전체 화면으로

/tui 로 바꾸면 settings.json 의 tui 키에 저장되고, 대화를 유지한 채 다시 뜹니다. 한 세션만 강제하려면 환경 변수를 씁니다. 공식 문서 기준으로 환경 변수가 설정 키보다 우선하고, 두 변수를 같이 주면 끄는 쪽이 이깁니다.

지정	결과
CLAUDE_CODE_NO_FLICKER=1	전체 화면 렌더러로 시작
CLAUDE_CODE_NO_FLICKER=0	클래식 렌더러로 시작
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1	클래식 렌더러로 시작 (전체 화면 관련 다른 지정보다 우선)
CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1	전체 화면에서 매 프레임을 전부 다시 그린다 (윈도우 터미널 잔상용)

여기서 흔한 오해 하나를 짚고 갑니다. "NO_FLICKER를 켜면 한글 입력이 해결된다"는 말이 커뮤니티에 돌지만, 공식 이슈 트래커를 열어 보면 반대 방향 보고가 더 많습니다. 전체 화면 렌더러가 켜져 있을 때 화면은 멀쩡한데 복사한 CJK 글자가 깨져 붙는다는 열린 이슈가 있고(그 글에서는 tui 를 default 로 바꾸니 해결됐다고 적혀 있습니다), NO_FLICKER를 껐다 켜도 증상이 그대로였다는 보고도 있습니다.

그러니 "무조건 켠다/끈다"가 아니라 양쪽을 다 시도해 보고 내 터미널에서 나은 쪽을 저장하는 게 맞습니다. 참고로 윈도우로 SSH 접속해서 쓰는 세션은 공식 문서 기준으로 애초에 클래식 렌더러로 시작합니다.

5. 그래도 안 되면

• 버전부터 올립니다. IME 관련 이슈는 특정 버전에서 재발한 기록이 반복적으로 올라옵니다. 올리는 방법은 클로드 코드 업데이트 명령어 글에 있습니다.
• 긴 한글은 다른 곳에서 쓰고 붙여넣습니다. 통합 이슈에도 현재의 우회책으로 이 방법이 적혀 있습니다.
• 웹 버전에서 입력합니다. 브라우저의 입력창은 IME 조합 이벤트를 그대로 받기 때문에 조합이 정상 동작합니다.
• 창 하나를 띄워 둡니다. 진짜 캐럿을 가진 다른 앱(메모장 등)이 화면에 보이면 조합이 되고, 그 창을 최소화하면 다시 깨지더라는 보고가 있습니다. 원인이 캐럿 위치라는 걸 뒷받침하는 정황입니다.

자주 묻는 질문 (FAQ)

Q. 백스페이스를 한 번 눌렀는데 단어가 통째로 지워집니다.
한글 문제는 아니지만 같이 겪는 경우가 많습니다. 윈도우에서 터미널이 백스페이스를 ^H 로 보내면 클로드 코드가 그걸 Ctrl+Backspace(앞 단어 삭제)로 읽습니다. CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0 을 주면 한 글자씩 지워집니다.

Q. 맥에서도 같은 문제가 있나요?
있습니다. 통합 이슈 자체가 macOS 환경(iTerm2, 한국어 2벌식)에서 올라온 것이고, 자모가 분리돼 보이거나 조합 중 커서 뒤 글자가 잠시 사라지는 증상이 함께 보고돼 있습니다.

Q. 코드페이지를 매번 바꾸기 귀찮습니다.
윈도우 설정의 "세계 언어 지원을 위한 Unicode UTF-8 사용" 베타 옵션을 켜면 시스템 ANSI 코드페이지 자체가 65001이 됩니다. 다만 오래된 프로그램이 영향을 받을 수 있어, 터미널에서만 chcp 65001 을 쓰는 편이 안전합니다.

Q. 설치할 때부터 한글이 깨졌습니다.
설치 단계에서 막힌 것과 인코딩 문제는 별개입니다. 설치 자체가 안 끝났다면 클로드 코드 설치 방법 글을 먼저 보세요.

마무리

정리하면 이렇습니다. 보이는 글자가 깨지면 터미널 코드페이지(chcp 65001), 치는 글자가 밀리면 클로드 코드 쪽(CLAUDE_CODE_NATIVE_CURSOR=1 과 /tui 렌더러 전환)입니다. 두 번째는 아직 열린 이슈라 설정으로 완전히 잡히지 않을 수 있으니, 급할 때는 다른 곳에서 쓰고 붙여넣는 편이 빠릅니다. 환경 변수는 버전마다 늘고 줄기 때문에, 적용 전에 공식 환경 변수 문서에서 이름이 그대로인지 한 번 확인하시길 권합니다.

---

📚 참고 출처 (2026년 9월 3일 확인 · Claude Code 2.1.204 기준)
· Claude Code — Environment variables
· Claude Code — Fullscreen rendering
· Claude Code — Settings reference
· Claude Code — Terminal configuration
· Claude Code 공식 이슈 트래커