1편에서 Codex 한글 깨짐의 원인을 분석했고, 4편에서 에러 메시지 대처법을 다뤘습니다. 이번 글에서는 Codex 한글 설정을 OS별로 완전히 정리합니다. "왜 깨지는가"가 아니라 "어떻게 고치는가"에 집중합니다.

Codex 한글 설정 — 문제의 핵심은 코드페이지

Codex CLI는 내부적으로 UTF-8을 사용합니다. 문제는 Codex가 셸 명령을 실행할 때 운영체제의 시스템 코드페이지를 그대로 상속한다는 점입니다. 한국어 Windows의 기본 코드페이지는 CP949(EUC-KR)이므로, Codex가 UTF-8로 출력한 한글이 CP949로 해석되면서 깨집니다.

이 문제는 GitHub Issue #7290에서 "PowerShell 7과 VS Code를 UTF-8로 설정해도 Codex가 셸을 스폰할 때 시스템 코드페이지로 되돌아간다"고 보고되어 있습니다.

Windows에서 Codex 한글 설정 — 3단계 해결법

Windows에서 Codex 한글 설정이 가장 많은 문제를 일으킵니다. 아래 3가지를 순서대로 적용하세요.

1단계: 시스템 로케일 변경 (가장 근본적)

설정 → 시간 및 언어 → 언어 및 지역 → 관리 언어 설정 → 시스템 로캘 변경에서 **"Beta: 세계 언어 지원을 위해 유니코드 UTF-8 사용"**을 체크합니다. 재부팅이 필요합니다.

이 설정은 시스템 전체 코드페이지를 65001(UTF-8)로 바꿉니다. Windows 10 1903 이상, Windows 11에서 사용 가능합니다. 단, ANSI 전용 레거시 프로그램이 깨질 수 있으니 주의하세요.

2단계: PowerShell 프로필 설정

PowerShell 프로필($PROFILE)에 다음을 추가합니다.

[code lang="powershell"] [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 $OutputEncoding = [System.Text.Encoding]::UTF8 [/code]

chcp 65001보다 안정적입니다. chcp는 CMD 세션에만 적용되고 새 창을 열면 초기화되지만, PowerShell 프로필은 매 세션 자동 적용됩니다.

3단계: config.toml 한글 로케일 설정

Codex CLI의 설정 파일은 ~/.codex/config.toml입니다. 다음을 추가하면 Codex가 스폰하는 셸의 로케일을 강제로 한국어 UTF-8로 지정할 수 있습니다.

[code lang="toml"] [shell_environment_policy] inherit = "core"

[shell_environment_policy.overrides] LANG = "ko_KR.UTF-8" [/code]

참고: 전용 인코딩 설정 옵션은 존재하지 않습니다(GitHub Issue #4013). Codex가 내부적으로 UTF-8을 강제하므로, 문제는 항상 외부(OS/셸) 쪽에 있습니다.

Mac에서 Codex 한글 설정

macOS는 기본적으로 UTF-8이라 대부분 문제가 없습니다. 다만 한 가지 알려진 이슈가 있습니다.

Codex 샌드박스가 LC_ALL=C.UTF-8을 강제 설정하는데, macOS에는 C.UTF-8 로케일이 기본 제공되지 않습니다(GitHub Issue #9354). bash에서 setlocale 경고가 나올 수 있습니다.

해결: ~/.codex/config.toml에 다음을 추가합니다.

[code lang="toml"] [shell_environment_policy.overrides] LANG = "ko_KR.UTF-8" [/code]

Linux에서 Codex 한글 설정

Linux는 시스템 로케일이 UTF-8이면 추가 설정 없이 정상 작동합니다. locale 명령으로 확인하세요.

[code lang="bash"] locale

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

[/code]

만약 UTF-8이 아니라면:

[code lang="bash"] sudo locale-gen ko_KR.UTF-8 sudo update-locale LANG=ko_KR.UTF-8 [/code]

Codex 한글 설정 시 알아둘 추가 이슈

Codex 한글 설정을 완료해도 남아 있을 수 있는 문제들입니다.

• 한국어 IME 입력 문제: Codex TUI(터미널 UI)에서 한글 조합 중 화면이 깜빡이거나 글자가 사라질 수 있습니다. TUI가 전체 화면을 다시 그리면서 IME 조합 상태가 끊기는 현상입니다(GitHub Issue #4870)
• UTF-8 BOM 문제: Codex가 기본적으로 UTF-8 BOM을 붙여 파일을 저장하는데, 이것이 CJK 콘텐츠를 깨뜨릴 수 있습니다(GitHub Issue #15967)
• EUC-KR 레거시 파일: CP949/EUC-KR로 인코딩된 기존 파일을 Codex가 수정하면 깨집니다. Codex 사용 전에 iconv로 변환하세요

[code lang="bash"] iconv -f euc-kr -t utf-8 input.txt > output.txt [/code]

Codex 한글 설정 체크리스트

항목	Windows	Mac	Linux
시스템 UTF-8	로케일 변경 필수	기본 OK	locale 확인
PowerShell/셸	프로필에 UTF8 추가	불필요	불필요
config.toml LANG	권장	권장 (C.UTF-8 이슈 방지)	선택
IME 조합	이슈 있음	이슈 있음	정상
BOM 문제	주의	주의	주의
EUC-KR 파일	iconv 변환 필수	iconv 변환 필수	iconv 변환 필수

Codex 한글 설정의 핵심은 결국 시스템 코드페이지를 UTF-8로 통일하는 것입니다. Codex 자체는 UTF-8만 사용하므로, OS 쪽만 맞추면 대부분의 한글 깨짐이 해결됩니다. 다음 글에서는 Codex가 다운됐을 때 Claude Code나 Gemini CLI로 즉시 전환하는 방법을 다룹니다.