부록 E. 한국어 환경 트러블슈팅

한국 사용자에게 Codex의 첫 장벽은 프롬프트가 아니다. 이상하게도 진짜 적은 한글 문자열, PowerShell, WSL 경로, 결제 페이지다. 영어권 가이드는 설치 명령은 잘 알려주지만, 한글이 �로 깨질 때 무엇부터 의심해야 하는지, 왜 Windows에서는 같은 명령도 어떤 날은 되고 어떤 날은 안 되는지, 결제는 됐는데 왜 CLI는 quota exceeded를 외치는지 같은 한국형 함정은 잘 안 다룬다.

이 부록의 목표는 간단하다. 문제를 "느낌"으로 때려 맞히지 말고, 증상별로 가장 가능성 높은 원인을 빠르게 좁히는 것이다. 잘만 익혀두면, 다음번에 비슷한 문제가 와도 10분 안에 방향을 잡을 수 있다.

먼저 이 표부터 보자

표만 봐도 패턴이 보인다. 한국어 환경 문제는 대개 모델 성능보다 실행 경로와 계정 상태에서 터진다. 그러니 "모델이 한국어를 못하나?"보다 "이 파일이 어떤 셸과 어떤 인코딩으로 읽히고 쓰였나?"를 먼저 묻는 편이 훨씬 실전적이다.

한글이 �로 깨질 때: 모델보다 경로를 먼저 의심하자

2026년에도 Codex에서 한글 깨짐 이야기가 완전히 사라진 것은 아니다. 다만 설명 방식이 달라져야 한다. 핵심은 "Codex가 한국어를 못해서"가 아니라, 특히 Windows에서 파일을 읽고 쓰는 경로가 UTF-8로 끝까지 유지되지 못하는 경우가 있고, 에이전트형 편집이 그 피해 범위를 키운다는 점이다.¹

이 문제는 한글이 많은 파일일수록 더 아프다. 예를 들어 i18n/ko.json이 살짝만 깨져도 빌드가 바로 실패한다. TSX 안의 UI 문구가 깨지면 런타임에서 뒤늦게 발견된다. README는 서비스는 안 죽여도 품질을 확 떨어뜨린다. 즉, 한글 깨짐은 보기 싫은 수준의 문제가 아니라, 곧바로 장애가 될 수 있는 문제다.¹

특히 위험한 파일은 다음과 같다.

실전에서는 이렇게 요청하는 편이 안전하다.

이 파일 전체를 정리하지 말고, ko.json의 login.title 과 login.description 키만 수정해줘.
키 순서 변경, 포맷팅 변경, 다른 문자열 수정은 하지 마.

이 한 줄이 생각보다 큰 사고를 막아준다. 에이전트형 도구는 친절한 척하다가 파일 전체를 예쁘게 정리해버리는 버릇이 있기 때문이다. 한글이 섞인 파일에서는 "예쁨"보다 "살아남음"이 우선이다.

한글 깨짐이 생겼을 때의 복구 순서

문제가 생기면 당황해서 같은 파일을 다시 더 크게 고치기 쉽다. 이때가 제일 위험하다. 이미 인코딩이 꼬인 파일을 다시 자동 수정시키면, 깨진 문자가 더 넓게 퍼질 수 있다.

복구 순서는 단순하게 가는 편이 좋다.

1. 먼저 git diff로 손상 범위를 확인한다.

2. 한글이 깨진 파일은 가능하면 Git 기준 정상 버전으로 되돌린다.

3. 다시 수정할 때는 파일 전체가 아니라 선택한 블록만 건드리게 한다.

4. 수정 직후 JSON 파싱, 타입체크, 빌드를 바로 돌린다.

5. 같은 문제가 두 번 반복되면, 그 작업은 네이티브 Windows에서 하지 말고 WSL2로 옮긴다.

한 번 깨진 문자열은 눈으로 보면 복구할 수 있을 것 같아도, 실제로는 따옴표와 이스케이프까지 함께 손상된 경우가 많다. 그러니 "고쳐보자"보다 "되돌리고 좁게 다시 하자"가 정답일 때가 많다.

PowerShell 인코딩: 출력, 변수, 파일 저장은 서로 다른 문제다

PowerShell을 쓰다 보면 이상한 순간이 있다. 콘솔에 한글은 멀쩡히 보이는데, 변수에 담으면 깨지고, 파일로 저장하면 또 다르게 깨진다. 이건 기분 탓이 아니다. PowerShell은 콘솔 출력 인코딩, 외부 프로그램과 주고받는 인코딩, cmdlet이 파일을 쓰는 기본 인코딩이 서로 다를 수 있다.²

특히 Microsoft 문서를 보면, PowerShell 7+는 기본 출력이 utf8NoBOM 쪽으로 정리되어 있지만, Windows PowerShell 5.1은 오래된 동작이 많이 남아 있다.² 그래서 같은 UTF-8이라는 말만 믿고 지나가면 안 된다. 어느 PowerShell인지, 무엇을 어디에 쓰는지를 분리해서 봐야 한다.

PowerShell 7을 쓴다는 전제로는, 프로필에 아래 정도를 넣고 시작하면 체감이 꽤 좋아진다.

if (!(Test-Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force | Out-Null
}

[Console]::InputEncoding  = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding
$PSDefaultParameterValues['*:Encoding'] = 'utf8'

여기서 핵심은 두 가지다. [Console]::OutputEncoding은 외부 프로그램과의 입출력 쪽에 영향을 주고, $PSDefaultParameterValues['*:Encoding']는 Out-File, Set-Content 같은 cmdlet들의 기본 파일 인코딩을 통일하는 데 도움이 된다.² 즉, 화면만 멀쩡하게 보이게 하는 임시 처방이 아니라, 쓰기 경로도 함께 맞추는 것이 중요하다.

다만 PowerShell 5.1에서는 이야기가 조금 다르다. 비 ASCII 문자가 들어간 스크립트는 BOM 없는 UTF-8을 제대로 해석하지 못하는 경우가 있어서, 프로필 파일 같은 스크립트는 UTF-8 with BOM으로 저장해야 문제가 줄어든다.²³ 이 부분이 헷갈리는 이유는, 요즘 대부분의 개발 파일은 BOM 없는 UTF-8이 더 낫기 때문이다. 정리하면 이렇다.

이 차이를 모르고 "모든 파일을 UTF-8 with BOM으로 바꾸면 되겠네"라고 가면 또 다른 도구와 충돌한다. 인코딩은 세계 평화가 아니라, 문맥별 휴전 협정에 가깝다.

$PROFILE이 문제를 만들 때는 파일 인코딩부터 본다

$PROFILE에 alias 하나 추가했는데 한글 경로가 깨지거나, 프로필이 로드되면서 이상한 문자가 보이면 프로필 내용보다 프로필 파일 자체 인코딩을 먼저 의심해야 한다. 한국어 환경에서는 이게 꽤 자주 원인이다.³

가장 쉬운 방법은 VS Code에서 프로필을 열고 저장 인코딩을 확인하는 것이다.

code $PROFILE

Windows PowerShell 5.1을 계속 써야 하고, 프로필 안에 한글이 들어간다면 UTF-8 with BOM으로 저장하는 편이 안전하다.³ 반대로 PowerShell 7을 주로 쓴다면 프로필 내용이 단순할 때는 UTF-8로도 충분한 경우가 많다. 중요한 것은 "내 터미널이 UTF-8이라고 들었으니 파일도 자동으로 다 안전할 것"이라고 가정하지 않는 것이다.

그리고 프로필이 아예 실행되지 않는다면 실행 정책도 걸림돌이 될 수 있다. 이때는 현재 사용자 범위에서 아래처럼 풀어주는 정도로 해결되는 경우가 있다.⁴

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

물론 회사 PC나 보안 정책이 강한 환경에서는 함부로 바꾸지 말고, 정책 범위를 먼저 확인해야 한다.

Windows에서 두 번 이상 이상하면, WSL로 옮기는 게 더 빠르다

OpenAI 쪽 안내도 Windows에서는 네이티브 PowerShell 사용과 WSL2 사용을 함께 언급한다.⁵ 여기서 실무적으로 중요한 포인트는, "둘 다 된다"가 아니라 언제 무엇을 기본값으로 삼을지다.

한국 개발자 기준으로는 규칙을 하나 정해두면 편하다. 네이티브 Windows에서 같은 문제가 두 번 반복되면, 그 작업은 WSL2로 옮긴다. 이게 제일 덜 피곤하다.

이유는 단순하다. WSL2는 Linux 기준 도구 체인과 더 잘 맞고, 프로젝트를 Linux 파일시스템 안에 두면 샌드박스 경계도 더 또렷하다.⁶ Full Access를 켜더라도 대체로 WSL 내부에서 움직이기 때문에, Windows 전체를 흔들 가능성이 줄어든다.⁶

실전에서 특히 중요한 규칙은 하나 더 있다. 저장소를 /mnt/c/...가 아니라 ~/code/... 같은 WSL 내부 경로에 두라는 것이다. /mnt/c에 두면 성능이 느려지고, 경로 의미도 애매해지고, 샌드박스 경계도 흐려진다.⁶

가장 무난한 루틴은 이렇다.

mkdir -p ~/code
cd ~/code
git clone <repo-url>
cd <repo>
code .

이렇게 열면 VS Code는 편하고, 실행 환경은 Linux라서 덜 삐걱거린다. Windows 개발자에게 WSL은 옵션이 아니라, 많은 경우 정신 건강 패치에 가깝다.

한국어가 많은 파일은 "최소 변경"이 기본값이다

해외 예제에서는 종종 "이 파일 전체를 정리해줘", "구조를 더 깔끔하게 바꿔줘" 같은 요청을 자연스럽게 쓴다. 하지만 한글이 많은 프로젝트에서는 이런 요청이 생각보다 위험하다. 특히 다음과 같은 파일은 더 조심하는 편이 좋다.¹

1. messages/ko.json, locales/ko/*.json 같은 번역 리소스

2. TSX/JSX 안에 사용자 문구가 많이 박힌 컴포넌트

3. 한글 주석과 문서가 뒤섞인 설정 파일

이럴 때는 범위를 강하게 좁혀야 한다. 예를 들어 Next.js + Supabase 프로젝트라면 이렇게 말하는 편이 낫다.

app/(auth)/login/page.tsx 에서 폼 문구 중 한글 레이블 3개만 수정해줘.
컴포넌트 구조 변경, import 정리, prettier 스타일 변경은 하지 마.

그리고 수정 직후에는 바로 확인한다.

pnpm lint
pnpm typecheck
pnpm build

JSON이면 더 단순하다.

node -e "JSON.parse(require('fs').readFileSync('messages/ko.json','utf8')); console.log('ok')"

핵심은 "모델을 덜 믿자"가 아니라, 한글이 많은 파일에서는 작업 범위를 더 명시하자는 것이다.

인증이 꼬일 때: 로그인 방식부터 분리해서 생각하자

Codex는 크게 두 경로로 쓴다. ChatGPT 계정 로그인과 API 키다. 여기서 많은 혼란이 시작된다. 개인 개발자라면 대개 ChatGPT 로그인 쪽이 더 단순하고, OpenAI의 공식 저장소도 Plus, Pro, Business, Edu, Enterprise 플랜 사용자는 이 방식으로 시작하길 권한다.⁸

인증이 꼬일 때는 증상을 이렇게 나눠 보면 된다.

여기서 중요한 함정 하나가 있다. ChatGPT 구독이 있다고 해서, 모든 상황에서 API 플랫폼 설정이 자동으로 맞아 있는 것은 아니다. 반대로 API 쪽에 결제 수단을 넣었다고 해서, 로컬에서 ChatGPT 로그인 경로의 제한이 자동으로 사라지는 것도 아니다. 계정은 하나여도, 인증 경로는 별개로 봐야 한다.

quota exceeded와 usage limit reached는 한 가지 뜻이 아니다

이 메시지가 뜨면 대부분 "돈이 부족한가 보다"라고 생각한다. 물론 그럴 수도 있다. 하지만 실전에서는 원인이 하나가 아니다.

첫째, 정말로 현재 플랜의 사용량을 다 쓴 경우다. 이건 가장 단순하다. Usage 화면과 현재 인증 경로를 확인하면 된다.

둘째, API 경로를 쓰고 있는데 플랫폼 쪽 결제 설정, 조직 상태, 기본 결제 수단이 빠져 있는 경우다. 커뮤니티 사례를 보면 조직 인증이나 기본 결제 수단 설정이 일부 오류와 연결되는 경우가 있었다.⁹

셋째, 사용량이 남아 보이는데도 CLI가 Quota exceeded를 뱉는 경우다. 원격 서버, SSH, 혹은 특정 계정 상태에서 이런 보고가 있었고, 잔여 한도 표시와 실제 CLI 응답이 어긋나는 사례도 존재한다.¹⁰¹¹

그래서 이 메시지가 뜨면 아래 순서로 보는 편이 좋다.

1. 지금 Codex가 ChatGPT 로그인으로 붙어 있는지, API 키로 붙어 있는지 확인한다.

2. ChatGPT 경로라면 ChatGPT 플랜 상태와 Codex 사용량 화면을 본다.

3. API 경로라면 플랫폼 Billing, Usage, 월 사용 상한, 조직 상태를 본다.

4. 둘 다 이상 없는데 CLI만 막히면, 로그아웃 후 재로그인하고 인증 파일을 재생성한다.

5. 여전히 남아 있는데 막히면, 일시적 미터링 문제 가능성을 염두에 두고 스크린샷과 시각을 남긴다.¹⁰

이때 제일 흔한 실수는 플랜 문제와 미터링 문제를 한데 묶어버리는 것이다. 결제는 됐는데 반영이 꼬였을 수도 있고, 반대로 결제는 정상이어도 현재 로그인 경로가 다른 조직이나 다른 방식으로 붙어 있을 수도 있다.

한국 결제 이슈: "OpenAI 문제"와 "해외 결제 문제"를 분리해서 본다

한국 사용자는 결제에서 한 번 더 함정에 걸릴 수 있다. 다만 중요한 건, 이런 문제를 무조건 OpenAI만의 특수 사례로 보면 진단이 느려진다는 점이다. 실제로 다른 해외 SaaS 서비스에서도 한국 카드 결제 오류나 한국 발급 카드 제한 사례가 반복적으로 보고된다.¹²¹³

즉, 결제가 안 될 때는 질문을 이렇게 바꿔야 한다.

"OpenAI가 고장 났나?"가 아니라, 내 카드와 해외 PG 조합이 문제인가, 계정 청구 설정이 문제인가, 아니면 결제는 됐는데 사용량 반영이 문제인가?

실무적으로는 아래 순서가 빠르다.

1. 같은 카드로 다른 해외 온라인 결제가 되는지 확인한다.

2. 개인카드와 법인카드가 있다면 둘 다 시도해 본다. 법인카드는 해외 SaaS 결제가 막혀 있는 경우가 있다.

3. 카드사 앱에서 해외 온라인 결제, 3D Secure, 추가 본인인증 요청이 들어왔는지 확인한다.

4. 카드 명의, 영문 청구 주소, 우편번호를 다시 점검한다.

5. 특정 카드만 계속 실패하면 카드사 문제인지 PG 제한인지 분리하기 위해 다른 네트워크보다 다른 카드 브랜드를 먼저 바꿔본다.

여기서 특히 기억할 점은, 결제 실패와 결제 성공 후 사용 불가는 다른 문제라는 것이다. 결제창에서 아예 거절되면 카드/PG 쪽에 가깝고, 결제 후 대시보드나 CLI에서 사용량이 안 풀리면 계정 반영이나 미터링 쪽일 가능성이 크다.¹⁰¹²¹³

한국 사용자용 안전 기본값

문제를 자주 겪는 사람은 대개 실력이 부족해서가 아니라, 기본값이 불안정해서 그렇다. 아래 다섯 가지를 기본값으로 잡아두면 대부분의 함정을 크게 줄일 수 있다.

1. Windows에서 한글이 조금이라도 많은 프로젝트라면, CLI 작업은 WSL2를 우선한다.

2. PowerShell을 써야 한다면 PowerShell 7을 쓰고, 프로필과 파일 인코딩을 분리해서 관리한다.²³

3. 한글이 들어간 JSON과 TSX는 파일 전체 수정이 아니라 선택 영역 수정을 기본값으로 둔다.¹

4. 로컬 개인 작업은 ChatGPT 로그인, CI나 서버 자동화는 API 키처럼 역할을 나눈다.⁸

5. 결제와 사용량은 같은 화면에서 보지 말고, Billing과 Usage를 따로 확인한다.¹⁰¹¹

이 다섯 가지만 습관이 되면, 한국어 환경에서 Codex를 쓰는 난이도는 확 내려간다. 결국 중요한 것은 "한글이 특별해서 못 쓴다"가 아니라, 한글이 섞인 환경에서는 경로를 더 정교하게 관리해야 한다는 사실이다. 그 차이를 이해하면, 한국어 프로젝트에서도 Codex는 충분히 강력한 도구가 된다.

참고

¹Is "Codex Korean Text Corruption" Still a Thing? (2026 Update) Causes and Safe Workflows

²about_Character_Encoding - PowerShell | Microsoft Learn

³Powershell 시스템에서 한글 인식하게끔 하기

⁴Powershell에서 한글이 깨질 때

⁵CLI - Codex | OpenAI Developers

⁶How I Sandbox AI Coding Agents on Windows 11 with WSL2

⁷OpenAI Codex CLI: Official Description & Setup Guide (Updated 2026-02)

⁸openai/codex GitHub 저장소

⁹[OpenAI - Codex] ChatGPT Cli 사용법, 오류 해결방법

¹⁰Codex billing issue: purchased $40 credits, but now remaining balance is 0 usage ...

¹¹Quota exceeded. Check your plan and billing details. · Issue #6792 · openai/codex · GitHub

¹²Billing issue (korea) - SonarQube Cloud - Sonar Community

¹³엑심베이 결제시 'South Korea issued the card can not used' 라는 메시지가 표시됩니다