codex 한글 깨짐, 프롬프트 문제가 아니라 터미널 인코딩부터 봐야 했습니다

codex 한글 깨짐은 대부분 모델이 한국어를 못 읽어서가 아니라, 터미널 출력·Git 경로 표시·실행 환경 로케일이 UTF-8로 맞지 않아서 생깁니다. 저는 Codex로 블로그 자동화 스크립트와 한국어 파일명을 다루다가 ����, \355\225\234 같은 출력이 섞여서 한참 돌아갔고, 결론은 프롬프트 수정이 아니라 환경 고정이었습니다.

터미널에서 UTF-8 점검 명령어를 먼저 실행해 보세요.

특히 Windows PowerShell, WSL, Git Bash, Warp 터미널을 오가며 AI 코딩 에이전트를 쓰는 분이면 같은 코드를 보고도 한쪽에서는 정상, 다른 쪽에서는 깨지는 상황을 자주 만납니다. 아래 순서대로 확인하면 대개 10분 안에 원인을 좁힐 수 있습니다.

제가 실제로 막힌 셋업

제 작업 흐름은 Warp 터미널에서 Codex와 Claude Code를 번갈아 쓰고, 결과물은 Git으로 커밋한 뒤 WordPress 자동 발행 파이프라인에 넘기는 방식입니다. 문제는 한국어 제목으로 만든 파일, 예를 들면 글감_요약_초안.md가 Codex 응답에서는 멀쩡한데 git status나 테스트 로그에서는 깨져 보인다는 점이었습니다.

처음에는 “한국어로만 답해줘”, “UTF-8로 저장해줘” 같은 프롬프트를 붙였습니다. 효과가 없는 건 아니지만 근본 해결은 아니었습니다. 이미 터미널이나 Git이 다른 방식으로 보여주고 있으면 에이전트가 아무리 잘 써도 화면에서 망가져 보입니다.

1차 확인: 터미널이 UTF-8인지 보기

가장 먼저 현재 셸의 인코딩을 확인했습니다. macOS나 Linux, WSL에서는 아래처럼 봅니다.

locale
printf '한글 테스트\n'

LANG, LC_ALL이 비어 있거나 C로만 잡혀 있으면 한국어 출력이 흔들릴 수 있습니다. 제 기준으로는 아래처럼 고정했을 때 Codex 출력과 스크립트 로그가 안정적이었습니다.

export LANG=ko_KR.UTF-8
export LC_ALL=ko_KR.UTF-8
export PYTHONIOENCODING=utf-8

Windows PowerShell에서는 먼저 코드 페이지를 확인합니다.

chcp

깨진다면 임시로 아래를 적용해 볼 수 있습니다.

chcp 65001
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()

다만 PowerShell 프로필, 터미널 앱, 폰트까지 같이 얽히는 경우가 있어서 저는 장기적으로는 WSL 또는 Warp의 UTF-8 환경을 더 선호합니다.

2차 확인: Git이 파일명을 이상하게 보여주는 경우

한국어 파일명이 \355\225\234\352\270\200.md처럼 보이면 Git 설정 문제일 가능성이 큽니다. 이건 파일이 깨진 게 아니라 Git이 비ASCII 경로를 따옴표와 이스케이프 형태로 보여주는 경우가 많습니다.

git config --global core.quotepath false
git status

이 한 줄로 git status, git diff --name-only에서 한국어 경로가 바로 읽히는 경우가 많았습니다. Codex에게 “파일명이 깨졌다”고 계속 고치게 시키기 전에 꼭 확인할 값입니다.

어디를 먼저 고칠지 비교

구체적인 예: 한국어 마크다운 파일 생성이 깨질 때

가상의 예로, Codex에게 아래 작업을 맡겼다고 해보겠습니다.

"워드프레스 글 초안을 posts/코덱스_한글_테스트.md 파일로 만들고, 제목과 FAQ를 한국어로 작성해줘."

파일 내용은 정상인데 터미널에서 파일명이 깨져 보인다면, 에이전트에게 다시 생성시키기보다 아래 순서가 낫습니다.

printf '한글 테스트\n'
git config --global core.quotepath false
git status
python -c "print('한글 테스트')"

여기서 printf부터 깨지면 터미널 문제, git status만 이상하면 Git 문제, Python만 깨지면 런타임 문제로 좁힐 수 있습니다. 이 분리가 안 되면 AI 에이전트가 엉뚱한 파일을 다시 쓰거나, 정상 파일을 “복구”한다며 오히려 망가뜨릴 수 있습니다.

이 방법이 특히 맞는 사람

터미널 중심으로 AI 코딩 에이전트를 쓰는 빌더

Claude Code, Codex, Gemini CLI류의 작업을 터미널에서 돌리고 한국어 문서, 블로그 초안, README, 커밋 메시지를 자주 만드는 분에게 우선 추천합니다. IDE 화면에서는 정상인데 CI 로그나 터미널에서만 깨지는 경우도 이 방식으로 원인을 나눌 수 있습니다.

한국어 파일명과 자동화 파이프라인을 같이 쓰는 사람

Notion에서 글감을 정리하고, n8n이나 자체 스크립트로 WordPress에 넘기고, 중간 결과를 Git에 남기는 흐름이라면 인코딩을 초반에 고정해야 합니다. 자동화는 한 번 깨진 문자열을 여러 단계로 복사하기 때문에 뒤에서 고치기가 더 어렵습니다.

자주 하는 실수

가장 흔한 실수는 깨진 화면을 보고 바로 “모델이 한글을 못한다”고 판단하는 겁니다. Codex, Claude Code, Cursor 모두 한국어 텍스트 자체를 다루는 능력보다, 내 로컬 환경이 어떤 바이트를 어떤 문자로 해석하는지가 더 큰 변수일 때가 많았습니다.

또 하나는 모든 설정을 한 번에 바꾸는 것입니다. 터미널, Git, Python, Node 설정을 동시에 고치면 무엇이 해결책이었는지 모릅니다. 한 단계씩 바꾸고 같은 문장으로 재현해야 다음 프로젝트에서도 재사용할 수 있습니다.

FAQ

codex 한글 깨짐이 프롬프트로 해결되나요?

일부는 완화됩니다. 예를 들어 “UTF-8로 저장”이라고 지시하면 파일 작성 방식이 더 명확해질 수 있습니다. 하지만 터미널 로케일이나 Git 표시 설정이 문제라면 프롬프트만으로는 해결되지 않습니다.

한글 파일명을 안 쓰는 게 더 안전한가요?

팀 개발이나 CI/CD가 복잡하면 영문 파일명이 더 안전합니다. 다만 개인 블로그 자동화나 콘텐츠 파이프라인에서는 한국어 파일명이 편할 때도 있으니, 최소한 Git과 터미널이 UTF-8로 일관되게 보이도록 맞춰두면 됩니다.

Warp 터미널을 쓰면 자동으로 해결되나요?

Warp 자체가 보기 좋은 터미널인 건 맞지만, 셸의 LANG, WSL 설정, Git 설정까지 대신 고쳐주지는 않습니다. 앱을 바꾸기 전에 현재 셸에서 locale과 git config를 먼저 확인하는 편이 빠릅니다.

지금 바로 할 일

• printf '한글 테스트\n'로 터미널 출력부터 확인합니다.
• locale 또는 chcp로 UTF-8 환경인지 봅니다.
• git config --global core.quotepath false를 적용하고 파일명 표시를 다시 확인합니다.
• Python이나 Node 스크립트가 있다면 읽기·쓰기 인코딩을 utf8로 명시합니다.

이 네 가지를 끝낸 뒤에도 깨진다면, 그때 Codex에게 현재 터미널 종류, OS, 재현 명령어, 깨진 출력 예시를 함께 주고 원인을 좁히게 하는 게 좋습니다. 막연히 “한글이 깨져요”보다 훨씬 빠르게 답이 나옵니다.

오늘도, 코딩할 용기.

관련 링크

• AI 에이전트 하네스 엔지니어링 입문 결정적 오케스트레이션 직접 짜기: 에이전트를 ‘믿는’ 대신 묶어두는 법
• ai 코딩 구독 요금 비교: Claude Code·Cursor·Copilot, 빌드용으로 돈값 하는 조합
• AI 코딩 에이전트 용어가 안 들릴 때 왕초보가 챙긴 최소 개념: Cursor와 Claude Code로 읽는 법
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크